الصنف `datetime.timedelta()‎` في بايثون

يمثّل كائن timedelta المدّة الزمنية التي تفصل بين تاريخين أو وقتين معيّنين.

البنية العامة

‎datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

المعاملات

جميع المعاملات في عبارة إنشاء الصنف timedelta اختيارية، وقيمتها الافتراضية تساوي 0، ويمكن أن تكون أعدادًا صحيحة أو ذات فاصلة عائمة، ويمكن كذلك أن تكون موجبة أو سالبة.

تُخزّن قيم المعاملات days و seconds و microseconds داخليًا، أما بقية المعاملات فتُحوّل إلى الوحدات التالية:

تحوّل المللي ثانية إلى 1000 مايكرو ثانية.
تحوّل الدقيقة إلى 60 ثانية.
تحوّل الساعة إلى 3600 ثانية.
يحوّل الأسبوع إلى 7 أيام.

ثم يجري معايرة normalize الأيام والثواني وأجزاء الثواني لتصبح الصيغة الممثلة واحدة، على أن تكون:

‎0 <= microseconds < 1000000‎
‎0 <= seconds < 3600*24 (عدد الثواني في اليوم الواحد)‎
‎-999999999 <= days <= 999999999‎

إن استخدمت الأعداد ذات الفاصلة العائمة في أيّ من المعاملات، وكان هناك عدد من أجزاء الثانية الكسرية، تُدمج أجزاء الثواني المتبّقية من جميع المعاملات وتقرّب قيمة مجموعها إلى أقرب جزء من الثانية باعتماد طريقة تقريب النصف إلى أقرب عدد زوجي round-half-to-even. وفي حال كانت جميع المعاملات أعدادًا صحيحة تكون نواتج عملية التحويل والمعايرة مضبوطة (ولن يكون هناك أي فقدان للمعلومات).

إن كانت قيمة الأيام التي جرت معايرتها خارج النطاق المحدّد، تطلق اللغة الخطأ OverflowError.

لاحظ أنّ معايرة القيم السالبة قد تعطي نتائج غير متوقعة، فمثلًا:

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

خصائص الصنف timedelta

يقدم صنف timedelta خصائص الصنف التالية:

timedelta.min

أقل قيمة سالبة للكائن timedelta، وهي timedelta(-999999999)‎.

timedelta.max

أعلى قيمة موجبة للكائن timedelta وهي timedelta(days=999999999, hours=23, minutes=59,seconds=59, microseconds=999999)‎.

timedelta.resolution

أقل قيمة ممكنة للمدة الزمنية التي تفصل بين كائني timedelta غير متساويين timedelta(microseconds=1)‎.

لاحظ أنّه بسبب عملية المعايرة، فإنّ timedelta.max > -timedelta.min. لا يمكن تمثيل الخاصية ‎-timedelta.max ككائن timedelta.

خصائص نسخة الصنف timedelta

ملاحظة: هذه الخصائص للقراءة فقط.

ملاحظات :

1- النتيجة مضبوطة، ولكن قد تحصل زيادة في بعض الأحيان.

2- النتيجة مضبوطة، ولا يمكن أن تحصل أي زيادة.

3- القسمة على 0 تؤدي إلى إطلاق الخطأ ZeroDivisionError.

4- يمكن تمثيل الخاصية ‎-timedelta.max ككائن timedelta.

5- تجري معايرة السلاسل النصية التي تمثّل كائنات timedelta بنفس طريقة معايرة صيغة التمثيل الداخلية، ويؤدي هذا إلى الحصول على بعض النتائج غير المتوقّعة مع القيم السالبة لكائنات timedelta. فمثلًا:

>>> timedelta(hours=-5)
datetime.timedelta(days=-1, seconds=68400)
>>> print(_)
-1 day, 19:00:00

ملاحظة: في الإصدار 3.2 من اللغة، تدعم كائنات timedelta إجراء القسمة التقريبية أو الحقيقية على بعضها البعض، وتدعم كذلك عمليات باقي القسمة remainder operations و الدالة divmod()‎.إلى جانب ذلك أصبحت كائنات timedelta تدعم عمليات القسم والضرب الحقيقية مع كائنات float.

يمكن إجراء المقارنات بين كائنات timedelta، ويعدّ كائن timedelta الذي يمثّل المدّة الزمنية الأقصر الطرف الأصغر في المقارنة.

تُطلق اللغة الخطأ TypeError وذلك لمنع عملية المقارنة التي تُعقد بين أنواع مختلفة من التراجع fallback إلى عملية المقارنة الافتراضية والتي تُعقد حسب عنوان الكائن، وتُستثنى من ذلك المقارنة باستخدام العاملين == و ‎!‎=‎، حيث تعيد عملية المقارنة القيمتين False و True على التوالي، وتدعم عملية التحويل إلى بايتات (pickling).

يمكن تقطيع hash كائنات timedelta (أي استخدامها كمفاتيح للقواميس)، وتدعم pickling، ويحمل كائن timedelta القيمة True في كل الأحوال إلا إذا كان مساويًا للقيمة timedelta(0)‎.

توابع نسخة الصنف timedelta

تقدّم نسخة الصنف timedelta تابعًا واحدًا فقط:

التابع `timedelta.total_seconds()‎`:

يعيد التابع عدد الثواني الكلّي في المدّة الزمنية التي يمثّلها كائن timedelta.

انظر أيضًا

الصنف datetime.date في بايثون.
الصنف datetime.datetime في بايثون.
الصنف datetime.time في بايثون.

مصادر

قسم timedelta في صفحة Basic date and time types في توثيق بايثون الرسمي.