Python/datetime/datetime

كائن datetime هو كائن مفرد يتضمّن جميع المعلومات المرتبطة بكائني التاريخ date والوقت time. وكما هو الحال مع هذين الكائنين، فإنّ كائن datetime يفترض وجود التقويم الكريكوري والممتد في كلا الاتجاهين، ويفترض كذلك وجود ‎3600*24 ثانية بالضبط في كل يوم.

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

class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

المعاملات

المعاملات الثلاثة الأولى (year, month, day) (السنة والشهر واليوم) تكون مطلوبة عند إنشاء صنف datetime. يمكن للمعامل tzinfo أن يأخذ القيمة None أو نسخة من صنف tzinfo فرعي. أما بقية المعاملات فيمكن أن تكون أعدادًا صحيحة ضمن النطاقات التالية:

• ‎MINYEAR <= year <= MAXYEAR‎
• ‎1 <= month <= 12‎
• عدد الأيام في السنة والشهر المحدّدين ‎‎1 <= day <=‎
• ‎0 <= hour < 24‎
• ‎0 <= minute < 60‎
• ‎0 <= second < 60‎
• ‎0 <= microsecond < 1000000‎
• ‎fold in [0, 1]‎

تطلق اللغة الخطأ ValueError، إن تجاوزت قيمة المعامل المعطاة إحدى هذه النطاقات.

ملاحظة: أضيف المعامل fold في الإصدار 3.6 من بايثون.

خصائص الصنف datetime:

date.min

أقدم تاريخ ووقت يمكن تمثيلهما. datetime(MINYEAR, 1, 1, tzinfo=None)‎.

date.max

أقصى تاريخ ووقت يمكن تمثيلهما datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)‎.

date.resolution

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

خصائص نسخة الصنف datetime:

تمتلك النسخ التي تنشأ من الصنف date الخصائص التالية:

date.year

السنة، وتمتد من MINYEAR إلى MAXYEAR ضمنيًّا.

date.month

الشهر، ويمتد من 1 إلى 12 ضمنيًّا.

date.day

اليوم، ويمتد من 1 إلى عدد الأيام ضمن الشهر المعطى في السنة المعطاة.

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

time.hour

الساعة ضمن المدى 0 إلى 23.

time.minute

الدقيقة ضمن المدى 0 إلى 59.

time.second

الثانية ضمن المدى 0 إلى 59.

جزء من الثانية، ضمن المدى 0 إلى 999999.

time.tzinfo

الكائن المُمرّر كقيمة للمعامل tzinfo في الدالة البانية للكائن time، أو القيمة None إن كانت قيمة المعامل tzinfo الممرّرة هي None.

time.fold

ضمن المدى ‎[0, 1]‎. ويستخدم للتمييز بين أوقات الانقضاء الحقيقية wall times خلال فترة زمنية مكرّرة. (تحدث الفترة الزمنية المكرّرة عند تأخير الساعات في التوقيت الصيفي، أو عند إنقاص مقدار إزاحة منطقة معيّنة عن التوقيت العالمي المنسّق UTC لأسباب سياسية).

تمثل القيمة 0 التوقيت المتقدّم بين التوقيتين، والقيمة 1 التوقيت المتأخر بين التوقيتين ضمن نفس تمثيل وقت الانقضاء الحقيقي.

ملاحظة: هذه الخاصية جديدة في الإصدار 3.6.

يوضّح المثال التالي خصائص نسخة الصنف time:

>>> from datetime import datetime
>>> dt = datetime(2018, 7, 4, 12, 39, 33)
>>> dt
datetime.datetime(2018, 7, 4, 12, 39, 33)
>>> print(dt)
2018-07-04 12:39:33
>>> dt.year
2018
>>> dt.month
7
>>> dt.day
4
>>> dt.hour
12
>>> dt.minute
39
>>> dt.second
33

عمليات الكائن datetime

يقدّم كائن datetime العمليات التالية:

العملية	النتيجة
datetime2 = datetime1 + timedelta	(1)
datetime2 = datetime1 - timedelta	(2)
timedelta = datetime1 - datetime2	(3)
datetime1 < datetime2	مقارنة كائن datetime مع كائن datetime آخر (4)

1. يمثّل كائن datetime2 المدّة الزمنية timedelta المحذوفة من الكائن datetime1، وذلك بالتقدم في الزمن إن كانت timedelta.days > 0، أو الرجوع بالزمن إن كانت timedelta.days < 0. تمتلك نتيجة هذه العملية خاصية tzinfo ذاتها التي تمتلكها المدخلات، وبعد إجراء هذه العملية يصبح datetime2 - datetime1 == timedelta. تطلق اللغة الخطأ OverflowError إن كان datetime2.year أصغر من MINYEAR أو أكبر من MAXYEAR. وجدير بالذكر أنّه لن تجرى أيّة تعديلات على المنطقة الزمنية حتى إن كانت المدخلات كائنات واعية.
2. تحسب هذه العملية قيمة datetime2 بحيث يكون datetime2 + timedelta == datetime1. كما هو الحال في عملية الجمع فإنّ النتيجة تمتلك خاصية tzinfo ذاتها التي تمتلكها المدخلات، ولا تجرى أيّة تعديلات على المنطقة الزمنية حتى لو كانت المدخلات كائنات واعية.
3. لا تتم عملية طرح كائن datetime من كائن datetime آخر إلا إذا كان كلاهما بسيطًا أو واعيًا. تطلق اللغة الخطأ TypeError إن كان أحد الكائنين بسيطًا والآخر واعيًا. إن كان الكائنان كلاهما بسيطًا أو واعيًا ويمتلكها خاصية tzinfo ذاتها، فستتجاهل اللغة خاصية tzinfo وتكون النتيجة عبارة عن كائن timedelta (نفترض أنه t) بحيث يكون datetime2 + t == datetime1، ولن تُجرى أي تعديلات في المنطقة الزمنية في هذه الحالة. إن كان الكائنان كلاهما واعيين ويمتلكان خصائص tzinfo مختلفة، فإن العملية a-b ستعمل كما لو حُوّل a و b في البداية إلى كائنات datetime بسيطة بتوقيت UTC. وتكون النتيجة ‎(a.replace(tzinfo=None) - a.utcoffset()) -(b.replace(tzinfo=None) - b.utcoffset())‎ باستثناء أنّه لن يحدث فيضان overflow أثناء إجراء العملية.
4. يكون الكائن datetime1 أصغر من datetime2 عندما يسبق الكائن الأول الكائن الثاني في الوقت. تطلق اللغة الخطأ TypeError إن جرت المقارنة بين كائن بسيط وآخر واعٍ، وعند إجراء مقارنات المساواة فإنّ الكائنات البسيطة لا تتساوى مع الكائنات الواعية على الإطلاق. إن كان جانبا المقارنة واعيين ويمتلكان خاصية tzinfo ذاتها، فإنّ اللغة تتجاهل هذه الخاصية وتجري المقارنة حسب كائنات datetime الأساسية. أما في حال اختلاف خاصية tzinfo بين الكائنين يجري تعديل جانبي المقارنة بطرح مقدار إزاحة كل منهما عن التوقيت العالمي المنسّق (يُحسب مقدار الإزاحة باستخدام التابع self.utcoffset()‎).

ملاحظة: لا تطلق عملية المقارنة بين كائن datetime بسيط وآخر واعٍ الخطأ TypeError في الإصدار 3.3.

ملاحظة: تُطلق اللغة الخطأ TypeError وذلك لمنع عملية المقارنة التي تُعقد بين أنواع مختلفة من التراجع fallback إلى عملية المقارنة الافتراضية والتي تُعقد حسب عنوان الكائن، وذلك عند إجراء المقارنة بين كائن datetime وكائن من نوع آخر مختلف، ولكن تعاد القيمة NotImplemented إن كان طرف المقارنة الآخر يمتلك الخاصية timetuple()‎. وبهذا تُمنح الأنواع الأخرى من كائنات date الفرصة لإجراء مقارنات بين أنواع مختلفة. إن لم يمتلك طرف المقارنة الآخر خاصية timetuple()‎ تطلق اللغة الخطأ TypeError إلا إذا جرت المقارنة باستخدام العاملين == و ‎!‎=‎، حيث تعيد عملية المقارنة القيمتين False و True على التوالي.

يمكن استخدام كائنات datetime كمفاتيح في القواميس، وفي السياقات البوليانية، تعدّ جميع كائنات datetime صحيحة.

توابع الصنف datetime

التابع datetime.today()‎

يعيد التابع الوقت والتاريخ حسب التوقيت المحلّي، مع إعطاء المعامل tzinfo القيمة None.

التابع datetime.now()‎

يعيد التابع الوقت التاريخ الحاليين حسب الإعدادات المحليّة، مع إمكانية تحديد المنطقة الزمنية.

التابع datetime.utcnow()‎

يعيد التابع الوقت والتاريخ حسب التوقيت العالمي المنسّق، مع إعطاء tzinfo القيمة None.

انظر أيضًا

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

مصادر

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