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

• المقارنة بين كائن وقت وآخر، حيث يعدّ الكائن a أقلّ من الكائن b إن كان الأول سابقًا للثاني في الوقت. إن كان أحد الكائنين بسيطًا naive وكان الآخر واعيًا، فإنّ اللغة تطلق الخطأ TypeError إن جرت المقارنة الترتيب بين الكائنين. أما عند مقارنة المساواة بين كائني وقت، فإنّ نسخ الكائنات البسيطة لا تساوي أبداً نسخ الكائنات الواعية.

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

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

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

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

• efficient pickling

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

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

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

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

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

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

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

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

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

مصادر

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