التابع tzinfo.tzname()‎ في بايثون

يعيد التابع اسم المنطقة الزمنية الخاصّة بالكائن datetime على هيئة سلسلة نصية.

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

‎tzinfo.tzname(dt)

القيمة المعادة

يعيد التابع اسم المنطقة الزمنية الخاصّة بالكائن datetime على هيئة سلسلة نصية.

لا يجري تعريف أيّ شيء بخصوص أسماء السلاسل النصية بواسطة الوحدة datetime، وليس من المطلوب أن يحمل الاسم دلالة معيّنة. فعلى سبيل المثال تعدّ السلاسل النصية التالية كلّها صحيحة: "GMT" و "UTC" و "‎-500" و "‎-5:00" و "EDT" و "US/Eastern" و "America/New York". يعيد التابع القيمة None إن كان اسم السلسلة النصية غير معروف.

يجب الانتباه إلى أنّ هذا تابع وليس سلسلة نصية ثابتة، والسبب الرئيسي هو أنّ بعض الأصناف الفرعية من tzinfo ستعيد أسماء مختلفة بالاعتماد على قيمة dt الممرّرة إليها، وخصوصًا إن كان أخذ الصنف tzinfo التوقيت الصيفي بالحسبان.

يؤدي استخدام التابع tzname()‎ بالطريقة الافتراضية إلى إطلاق الخطأ NotImplementedError.

تستدعى هذه التوابع بواسطة كائن datetime أو time وذلك استجابة للتوابع التي تحمل الأسماء ذاتها في هذه الكائنات. يمرّر كائن datetime نفسه كمعامل، في حين يمرّر الكائن time القيمة None كمعامل؛ ولهذا يجب تحضير توابع الصنف الفرعي للصنف tzinfo لاستقبال معامل dt قيمته None أو صنف datetime.

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

عند تمرير كائن datetime كاستجابة لأحد توابع الكائن datetime، يكون الكائن dt.tzinfo مماثلًا للكائن self.tzinfo، إلا إذا كان الشيفرة المكتوبة من قبل المستخدم تستدعي التابع tzinfo بصورة مباشرة. الهدف هنا هو أن تفسّر توابع tzinfo الكائن dt على أنّه ضمن التوقيت المحلي دون الحاجة إلى الاهتمام بالكائنات في المناطق الزمنية الأخرى.

أمثلة

يبين المثال التالي آلية عمل التابع:

مصادر

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