عرض مصدر Python/datetime/timedelta

<noinclude>{{DISPLAYTITLE:الصنف <code>datetime.timedelta()‎</code> في بايثون}}</noinclude>


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

<syntaxhighlight lang="python3">
‎datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)
</syntaxhighlight>

== المعاملات ==
جميع المعاملات في عبارة إنشاء الصنف 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 ==

يقدم صنف <code>timedelta</code> خصائص الصنف التالية:
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.

== انظر أيضًا ==

== مصادر ==
[https://docs.python.org/3/library/datetime.html#datetime.timedelta قسم date Objects في صفحة Basic date and time types في توثيق بايثون الرسمي.]

[[تصنيف:Python]]
[[تصنيف:Python Modules]]
[[تصنيف:Python Methods]]