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

يعيد التابع مقدار التعديل لنظام التوقيت الصيفي (DST).

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

‎tzinfo.dst(dt)

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

يعيد التابع مقدار التعديل لنظام التوقيت الصيفي (DST).

يعيد التابع كائن timedelta يمثّل مقدار التعديل لنظام التوقيت الصيفي (DST)، ويعيد القيمة None إن لم تكن معلومات التوقيت الصيفي معروفة، ويعيد timedelta(0)‎ إن لم يكن التوقيت الصيفي مفعّلًا. أما لو كان التوقيت الصيفي مفعّلًا، فإنّ التابع يعيد كائن timedelta (راجع التابع utcoffset()‎ للمزيد من التفاصيل).

يجب الانتباه إلى أنّ مقدار إزاحة التوقيت الصيفي - إن كان مطبّقًا - مضاف مسبقًا إلى مقدار الإزاحة عن التوقيت العالمي المنسّق والذي يعيده التابع utcoffset()‎، لهذا لا حاجة إلى استدعاء التابع dst()‎ إلا إذا كان المطلوب الحصول على معلومات التوقيت الصيفي على نحو منفصل.

فعلى سبيل المثال يستدعي التابع datetime.timetuple()‎ التابع dst()‎ وهو من توابع خاصّيته tzinfo لتحديد طريقة تعيين قيمة الراية tm_isdst، ويستدعي التابع tzinfo.fromutc()‎ التابع dst()‎ عند الانتقال بين المناطق الزمنية للأخذ بالحسبان التغييرات التي قد تطرأ على التوقيت بسبب نظام التوقيت الصيفي.

يجب أن تكون نسخة الصنف الفرعي للصنف tzinfo (لنفترض أنها tz) والتي تمثّل التوقيتين المعياري والصيفي متّسقة ومطابقة للمفهوم التالي:

يجب أن يعيد التعبير: tz.utcoffset(dt) - tz.dst(dt)‎ النتيجة نفسها لأي كائن datetime تكون فيه dt.tzinfo == tz.

يعيد هذا التعبير في الأصناف الفرعية السليمة من tzinfo مقدار الإزاحة المعياري "standard offset" للمنطقة الزمنية والذي يجب أن لا يعتمد على التاريخ أو الوقت، ولكن على المنطقة الزمنية فقط.

يعتمد التابع datetime.astimezone()‎ على هذا الأمر، ولكنّه غير قادر على اكتشاف المخالفات، وتقع مسؤولية ذلك على عاتق المبرمج.

إن لم يضمن الصنف الفرعي من tzinfo ذلك، فقد يكون بمقدوره إعادة تعريف طريقة الاستخدام الافتراضية للتابع tzinfo.fromutc()‎ ليعمل بصورة صحيحة مع التابع astimezone()‎.

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

ملاحظة: لم يعد مقدار إزاحة التوقيت الصيفي مقصورًا على الأعداد الصحيحة للدقائق.

أمثلة

عادة ما يستخدم التابع dst()‎ بإحدى الطريقتين التاليتين:

الطريقة الأولى:

def dst(self, dt):
    # صنف ذو مقدار إزاحة ثابت: لا يجري حساب DST
    return timedelta(0)

الطريقة الثانية:

def dst(self, dt):
    # تعيين dston و dstoff لأوقات الانتقال في نظام التوقيت الصيفي
	# الخاص بمنطقة زمنية معينة وذلك بالاستناد إلى السنة dt.year
	# ويُعرض بالتوقيت المعياري المحلّي.
    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)

انظر أيضًا

• التابع datetime.dst()‎: يتيح التابع القدرة على تحديد ما إذا كان التوقيت الصيفي مستخدمًا أم لا.
• التابع datetime.astimezone()‎: يعيد التابع كائن datetime مع خاصية tzinfo الممرّرة كمعامل للتابع، ويَجري تعديل بيانات الوقت والتاريخ بحيث تكون النتيجة مشابهة لوقت الكائن نفسه حسب التوقيت العالمي المنسّق، ولكنّ بالتوقيت المحلّي المحدّد بالمعامل tz.

مصادر

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