التابع datetime.astimezone() في بايثون
يعيد التابع كائن datetime مع خاصية tzinfo الممرّرة كمعامل للتابع، ويَجري تعديل بيانات الوقت والتاريخ بحيث تكون النتيجة مشابهة لوقت الكائن نفسه حسب التوقيت العالمي المنسّق، ولكنّ بالتوقيت المحلّي المحدّد بالمعامل tz.
البنية العامة
datetime.astimezone(tz=None)
المعاملات
tz
يجب أن يكون المعامل tz -في حال توفّره- نسخة من صنف tzinfo فرعي، ويجب أن لا يعيد تابعاه utcoffset() و dst() القيمة None. إن كان الكائن نفسه بسيطًا، فإنّ اللغة تفترض أنّه يمثّل الوقت حسب المنطقة الزمنية الخاصة بنظام التشغيل.
في حال استدعاء التابع دون تحديد المعاملات (أو إن أخذ المعامل tz القيمة None) فإنّ اللغة ستفترض أنّ المنطقة الزمنية المطلوبة هي المنطقة الزمنية المحددة الخاصة بنظام التشغيل، وتعيّن نسخة من الكائن timezone إلى الخاصية tzinfo التابعة لنسخة الكائن datetime المحوّلة ويؤخذ اسم المنطقة الزمنية ومقدار إزاحتها عن التوقيت العالمي المنسّق من نظام التشغيل.
إن كانت قيمة self.tzinfo هي tz، فإنّ التعبير self.astimezone(tz) مساوٍ للكائن نفسه self، بمعنى أنّه لن تجرى أي تعديلات على التاريخ والوقت. وفيما عدا ذلك تكون النتيجة حسب التوقيت المحلي في المنطقة الزمنية tz، ويمثّل نفس الوقت (حسب التوقيت العالمي المنسّق) الذي يمثّله الكائن نفسه self: ونتيجة لذلك سيمتلك التعبير afterastz = dt.astimezone(tz), astz - astz.utcoffset() نفس بيانات الوقت والتاريخ التي يمتلكها التعبير dt- dt.utcoffset().
القيمة المعادة
يعيد التابع كائن datetime مع خاصية tzinfo الممرّرة كمعامل للتابع، ويَجري تعديل بيانات الوقت والتاريخ بحيث تكون النتيجة مشابهة لوقت الكائن نفسه حسب التوقيت العالمي المنسّق، ولكنّ بالتوقيت المحلّي المحدّد بالمعامل tz.
يمكن ربط كائن منطقة زمنية tz بكائن datetime (نفترض أنّ اسمه dt) دون إجراء التعديلات على بيانات الوقت والتاريخ باستخدام التعبير dt.replace(tzinfo=tz). ويمكن حذف كائن المنطقة الزمنية من كائن datetime واعٍ دون تحويل بيانات الوقت والتاريخ، باستخدام التعبير dt.replace(tzinfo=None).
من الجدير بالذكر أنّه يمكن إعادة تعريف (override) التابع الافتراضي tzinfo.fromutc() في صنف tzinfo الفرعي للتأثير على النتيجة المعادة من التابع astimezone().
ملاحظات:
- في الإصدار 3.3 من اللغة أصبح بالإمكان حذف المعامل
tz. - في الإصدار 3.6 من اللغة أصبح بالإمكان استدعاء التابع
astimezone()على النسخ البسيطة والتي يفترض بها تمثيل النظام المحلّي الخاصّ بالنظام.
أمثلة
إن تجاهلنا الحالات التي تنتج عنها الأخطاء، فإنّ التابع astimezone() يعمل بالصورة التالية:
def astimezone(self, tz):
if self.tzinfo is tz:
return self
# تحويل الكائن نفسه إلى UTC، وإلحاق كائن المنطقة الزمنية الجديد.
utc = (self - self.utcoffset()).replace(tzinfo=tz)
# التحويل من UTC إلى المنطة الزمنية tz.
return tz.fromutc(utc)