عرض مصدر Python/datetime/tzinfo/dst

<noinclude>{{DISPLAYTITLE:التابع <code>tzinfo.dst()‎</code> في بايثون}}</noinclude>

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

<syntaxhighlight lang="python3">
‎tzinfo.dst(dt)
</syntaxhighlight>

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

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

يعيد التابع كائن timedelta يمثّل مقدار التعديل لنظام التوقيت الصيفي (DST)، ويعيد القيمة <code>None</code> إن لم تكن معلومات التوقيت الصيفي معروفة، ويعيد <code>timedelta(0)‎</code> إن لم يكن التوقيت الصيفي مفعّلًا. أما لو كان التوقيت الصيفي مفعّلًا، فإنّ التابع يعيد كائن <code>[[Python/datetime/timedelta|timedelta]]</code> (راجع التابع <code>[[Python/datetime/tzinfo/utcoffset|utcoffset()]]</code>‎ للمزيد من التفاصيل).

يجب الانتباه إلى أنّ مقدار إزاحة التوقيت الصيفي - إن كان مطبّقًا - مضاف مسبقًا إلى مقدار الإزاحة عن التوقيت العالمي المنسّق والذي يعيده التابع <code>[[Python/datetime/tzinfo/utcoffset|utcoffset()]]</code>‎، لهذا لا حاجة إلى استدعاء التابع <code>dst()</code>‎ إلا إذا كان المطلوب الحصول على معلومات التوقيت الصيفي على نحو منفصل.

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

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

يجب أن يعيد التعبير: <code>tz.utcoffset(dt) - tz.dst(dt)‎</code> النتيجة نفسها لأي كائن <code>[[Python/datetime/datetime|datetime]]</code> تكون فيه <code>dt.tzinfo == tz</code>.

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

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

إن لم يضمن الصنف الفرعي من <code>tzinfo</code> ذلك، فقد يكون بمقدوره إعادة تعريف طريقة الاستخدام الافتراضية للتابع <code>[[Python/datetime/tzinfo/fromutc|tzinfo.fromutc()]]</code>‎ ليعمل بصورة صحيحة مع التابع <code>[[Python/datetime/datetime/astimezone|astimezone()‎]]</code>.

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

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

== أمثلة ==

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

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

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

== انظر أيضًا ==
* التابع <code>[[Python/datetime/datetime/dst|datetime.dst()‎]]</code>: يتيح التابع القدرة على تحديد ما إذا كان التوقيت الصيفي مستخدمًا أم لا.
* التابع <code>[[Python/datetime/datetime/astimezone|datetime.astimezone()‎]]</code>: يعيد التابع كائن <code>datetime</code> مع خاصية <code>tzinfo</code> الممرّرة كمعامل للتابع، ويَجري تعديل بيانات الوقت والتاريخ بحيث تكون النتيجة مشابهة لوقت الكائن نفسه حسب التوقيت العالمي المنسّق، ولكنّ بالتوقيت المحلّي المحدّد بالمعامل <code>tz</code>.

== مصادر ==
[https://docs.python.org/3/library/datetime.html#datetime.tzinfo.dst قسم tzinfo Objects في صفحة Basic date and time types في توثيق بايثون الرسمي.]

[[تصنيف:Python]]
[[تصنيف:Python Modules]]
[[تصنيف:Python Methods]]