الصنف 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

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

days

عدد الأيام في كائن timedelta وتأخذ القيم من ‎-999999999 إلى 999999999‎ ضمنيًّا.

seconds

عدد الثواني في كائن timedeltaوتأخذ القيم من 0 إلى 86399 ضمنيًّا.

microseconds

عدد أجزاء الثواني في كائن timedelta وتأخذ القيم من 0 إلى 999999 ضمنيًّا.

عمليات نسخ الصنف timedelta

تدعم نسخ الصنف timedelta العمليات الموضّحة في الجدول التالي:

العملية	النتيجة	ملاحظات
t1 = t2 + t3	حاصل جمع t2 و t3. بعد ذلك يصبح التعبيران t1 - t2 == t3 و t1 - t3 == t2 صحيحين.	(1)
t1 = t2 - t3	حاصل طرح t3 من t2. بعد ذلك يصبح التعبيران t1 == t2 - t3 و t2 == t1 + t3 صحيحين.	(1)
‎t1 = t2 * i  أو ‎t1 = i * t2‎	حاصل ضرب كائن timedelta بعدد صحيح. بعد ذلك يصبح التعبير t1 // i == t2 صحيحًا، بشرط أن تكون i != 0. وبصورة عامة فإن التعبير t1 * i == t1 * (i-1) + t1  يكون صحيحًا.	(1)
t1 = t2 * f أو t1 = f * t2	حاصل ضرب كائن timedelta بعدد عشري ذي فاصلة عائمة. تُقرّب النتيجة إلى أقرب مضاعفات timedelta.resolution باستخدام طريقة تقريب النصف إلى أقرب عدد موجب round-half-to-even.
f = t2 / t3	حاصل قسمة t2 على t3، وتعيد العملية كائن float.	(3)
t1 = t2 / f أو t1 = t2 / i	حاصل قسمة كائن timedelta على عدد عشري ذي فاصلة عائمة. تُقرّب النتيجة إلى أقرب مضاعفات timedelta.resolution باستخدام طريقة تقريب النصف إلى أقرب عدد موجب round-half-to-even.
t1 = t2 // i أو t1 = t2 // t3	تقرب النتيجة إلى أكبر عدد صحيح سابق، ويجري التخلص من الباقي (إن وجد). في الحالة الثانية، تعيد العملية عددًا صحيحًا.	(3)
t1 = t2 % t3	يُحسب المتبقي ككائن timedelta.	(3)
q, r = divmod(t1, t2)‎	يُحسب حاصل القسمة والمتبقي منها: q = t1 // t2 و r = t1 % t2. q عدد صحيح، و r هو كائن timedelta.	(3)
‎+t1‎	تعيد العملية كائن timedelta يحمل القيمة نفسها.	(2)
‎-t1‎	هذه العملية مكافئة للتعبير‎ (-t1.days, -t1.seconds, -t1.microseconds)‎و للتعبير t1* -1.	(4)
abs(t)‎	هذه العملية مكافئة للتعبير ‎+t عندما يكون t.days >= 0، وللتعبير ‎-t‎ عندما يكون t.days < 0. (2)‎.	(2)
str(t)‎	تعيد هذه العملية سلسلة نصية تحمل الصيغة ‎[D day[s], ][H]H:MM:SS[.UUUUUU]‎ وتكون D سالبة عندما يكون t سالبًا.	(5)
repr(t)‎	تعيد هذه العملية تمثيلًا نصّيًا للكائن 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 في توثيق بايثون الرسمي.