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

يمثّل كائن time الوقت (المحلّي) في يوم غير محدّد، وهو عرضة للتعديل بواسطة كائن tzinfo.

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

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

المعاملات

جميع المعاملات في عبارة إنشاء الصنف time اختيارية، وتأخذ القيمة الافتراضية 0، ويأخذ المعامل tzinfo القيمة الافتراضية None.

يمكن أن تكون قيم جميع المعاملات (باستثناء المعامل tzinfo) أعدادًا صحيحة وضمن المديات التالية:

• ‎0 <= hour < 24‎
• ‎0 <= minute < 60‎
• ‎0 <= second < 60‎
• ‎0 <= microsecond < 1000000‎
• ‎fold in [0, 1]‎

تطلق اللغة الخطأ ValueError في حال كانت قيمة أحد المعاملات السابقة خارج النطاق المحددّ له.

خصائص الصنف time

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

time.min

أقل قيمة للوقت قابلة للتمثيل، time(0, 0, 0, 0)‎.

time.max

أقصى قيمة للوقت قابلة للتمثيل، time(23, 59, 59, 999999)‎.

time.resolution

أقل مقدار ممكن للفارق بين كائني time غير متساويين، timedelta(microseconds=1)‎، مع ملاحظة أنّ اللغة لا تدعم إجراء العمليات الحسابية على كائنات time.

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

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 time
>>> t = time(12, 10, 30)
>>> t
datetime.time(12, 10, 30)
>>> print(t)
12:10:30
>>> t.second
30
>>> t.hour
12
>>> t.minute
10
>>> t.microsecond
0

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

• يمكن المقارنة بين كائن وقت وآخر، ويعدّ الكائن a أصغر من الكائن b إن كان الأول سابقًا للثاني في الوقت. إن كان أحد الكائنين بسيطًا naive وكان الآخر واعيًا، فإنّ اللغة تطلق الخطأ TypeError إن جرت المقارنة الترتيب بين الكائنين. أما عند مقارنة المساواة بين كائني وقت، فإنّ نسخ الكائنات البسيطة لا تساوي أبداً نسخ الكائنات الواعية. إن كان كلا الكائنين واعيين، وكانت خاصية tzinfo لكلّ منهما تحمل القيمة ذاتها، فإنّ اللغة تتجاهل خاصية tzinfo المشتركة بينهما، وتجري المقارنة على أساس الوقت. أما في حالة اختلاف قيمة خاصية tzinfo، فإنّ طرفي المقارنة يعدّلان في البداية بطرح مقدار إزاحتهما عن التوقيت العالمي المنسّق UTC (يحسب التابع self.utcoffset()‎ مقدار الإزاحة).

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

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

• التقطيع، يمكن استخدام الكائن كمفتاح في قاموس.

يحمل كائن time القيمة True دائمًا في السياقات المنطقية.

ملاحظة: قبل الإصدار 3.5 من بايثون، كان كائن time يحمل القيمة false إذا كان يمثّل منتصف الليل حسب التوقيت العالمي المنسّق. كان هذا السلوك سببًا في وقوع الالتباس وحدوث الأخطاء، وقد ألغي في الإصدار 3.5 من اللغة.

يبين المثال التالي مقارنة بسيطة بين كائني time مختلفين:

>>> t1 = time(12, 10, 30)
>>> t2 = time(11, 9, 54)
>>> t1 == t2
False
>>> t1 < t2
False
>>> t1 > t2
True

دالة بانية أخرى

يمكن إنشاء كائن time باستخدام الدالة البانية time.fromisoformat()‎.

تعيد هذه الدالة البانية كائن time موافقة للمعامل time_string وهو عبارة عن سلسلة نصية، ويُنسّق الكائن الجديد بواسطة أحد التنسيقات التي يقدّمها التابع time.isofromat()‎.

تدعم هذه الدالة السلاسل النصية ذات التنسيق:

HH[:MM[:SS[.mmm[mmm]]]][+HH:MM[:SS[.ffffff]]]

جدير بالذكر أنّ هذه الدالة لا تدعم تفسير سلاسل المعيار ISO 8601، وأنّ الهدف منها هو أداء الوظيفة المعاكسة للتابع time.isofromat()‎.

ملاحظة: هذه الدالة جديدة في الإصدار 3.7 من اللغة.

توابع نسخ الكائن time

تقدم نسخ الكائن time التوابع التالية:

التابع time.replace()‎

يستبدل التابع القيم المعطاة في المعاملات بالقيم الأصلية في كائن الوقت.

التابع time.isoformat()‎

يعيد التابع سلسلة نصية تمثّل الوقت بصيغة المعيار ISO 8601.

مصادر

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