l25: datetime.tzinfo, completed

Saeid · Saeid · commit e171402f789b · 2021-04-11T09:38:35.000+04:30
diff --git a/lessons/l25.rst b/lessons/l25.rst
@@ -41,26 +41,27 @@
 
 * **کلاس** ``date``: مناسب برای ایجاد شی تاریخ در پایتون می‌باشد که اشیا آن هیچ آگاهی نسبت به ساعت و منطقه زمانی (Time zone) [`ویکی‌پدیا <https://en.wikipedia.org/wiki/Time_zone>`__] نخواهند داشت و تنها مربوط به روزی خاص بر اساس گاه‌شماری میلادی (Gregorian calendar) [`ویکی‌پدیا <https://en.wikipedia.org/wiki/Gregorian_calendar>`__] می‌باشند.
 
-* **کلاس** ``time``: مناسب برای ایجاد شی ساعت در پایتون می‌باشد و اشیا این کلاس هیچ آگاهی نسبت به تاریخ یا روز خاصی ندارند.
+* **کلاس** ``time``: مناسب برای ایجاد شی ساعت در پایتون می‌باشد و اشیا این کلاس هیچ آگاهی نسبت به تاریخ یا روز خاصی ندارند و تنها حاوی یک زمان مشخص از شبانه‌روز خواهند بود.
 
-* **کلاس** ``datetime``: ترکیبی از دو کلاس ``date`` و ``time`` که اشیای آن نسبت به یک زمان (تاریخ و ساعت) مشخص آگاهی دارند.
-
-در ادامه به بررسی این سه کلاس و دیگر اجزای مهم از ماژول datetime خواهیم پرداخت.
-
-.. note::
-
-  در زبان برنامه‌نویسی پایتون اشیای مرتبط با زمان براساس توانایی آگاهی آن‌ها از منطقه زمانی (Time zone) به دو دسته **«آگاه» (aware)** و **«ساده» (naive)** تقسیم‌بندی می‌شوند. بر همین اساس اشیای کلاس ``date`` از نوع naive و اشیای دو کلاس ``time`` و ``datetime`` می‌توانند برحسب شرایط  aware یا naive باشند.
+* **کلاس** ``datetime``: ترکیبی از دو کلاس ``date`` و ``time`` که اشیای آن می‌توانند نسبت به یک زمان (تاریخ و ساعت) مشخص آگاهی کامل داشته باشند.
 
+در ادامه به بررسی این سه کلاس خواهیم پرداخت، اما پیش از این کار لازم است با دو کلاس دیگر از ماژول datetime آشنا شویم،  ``timedelta`` و ``tzinfo``.
 
 
 کلاس ``datetime.timedelta``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-پیش از بررسی کلاس‌های یاد شده لازم است با کلاسی دیگر از ماژول datetime آشنا شویم. در زبان برنامه‌نویسی پایتون از اشیای کلاس ``timedelta`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#timedelta-objects>`__] برای بیان «مدت زمان» (duration) مشخص یا اختلاف بین دو تاریخ یا ساعت استفاده می‌شود. الگوی نمونه‌سازی از این کلاس به شکل زیر است::
+در زبان برنامه‌نویسی پایتون از اشیای کلاس ``timedelta`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#timedelta-objects>`__] برای بیان «مدت زمان» (duration) مشخص یا اختلاف بین دو تاریخ یا زمان استفاده می‌شود. الگوی نمونه‌سازی از این کلاس به شکل زیر است::
 
-    td = timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)
+    td = timedelta(days=0, 
+                   seconds=0, 
+                   microseconds=0, 
+                   milliseconds=0, 
+                   minutes=0, 
+                   hours=0, 
+                   weeks=0)
 
-با نمونه‌سازی از این کلاس و ارسال آرگومان‌های دلخواه، براساس تمام واحدهای پرتکرار از زمان یا حتی ترکیبی از آن‌ها می‌توانیم یک مدت‌زمان در سیستم زمانی پایتون ایجاد کنیم؛ هفته (weeks)، روز (days)، ساعت (hours)، دقیقه (minutes)، ثانیه (seconds)، میلی‌ثانیه (milliseconds یا همان 0.001 ثانیه) و میکروثانیه (microseconds یا همان 0.000001 ثانیه). تمامی این مقادیر اختیاری و با مقدار پیش‌فرض ``0`` هستند که می‌توانند از نوع ``int`` یا ``float``، مثبت یا منفی باشند
+با نمونه‌سازی از این کلاس و ارسال آرگومان‌های دلخواه، براساس تمام واحدهای پرتکرار از زمان یا حتی ترکیبی از آن‌ها می‌توانیم یک مدت‌زمان در سیستم زمانی پایتون ایجاد کنیم؛ هفته (weeks)، روز (days)، ساعت (hours)، دقیقه (minutes)، ثانیه (seconds)، میلی‌ثانیه (milliseconds یا همان 0.001 ثانیه) و میکروثانیه (microseconds یا همان 0.000001 ثانیه). تمامی این مقادیر اختیاری و با مقدار پیش‌فرض ``0`` هستند که می‌توانند از نوع ``int`` یا ``float``، مثبت یا منفی باشند:
 
 ::
 
@@ -105,7 +106,7 @@
 
 
 
-توجه داشته باشید که از تمام انواع آرگومانی که ارسال می‌کنید این تنها ``seconds`` ،``days`` و ``microseconds`` هستند که دارای attribute متناظر بوده و قابل دسترس می‌باشند. در واقع تمامی مقادیر ارسالی در زمان نمونه‌سازی با یکدیگر ترکیب شده و در نهایت به این سه attribute تبدیل می‌شوند. به مقداردهی در زمان نمونه‌سازی و نیز به خروجی سطر پایانی از نمونه کدهای بالا توجه نمایید.
+توجه داشته باشید که از تمام انواع آرگومانی که ارسال می‌کنید این تنها ``seconds`` ،``days`` و ``microseconds`` هستند که دارای attribute متناظر بوده و قابل دسترس می‌باشند. در واقع تمامی مقادیر ارسالی در زمان نمونه‌سازی با یکدیگر ترکیب شده و در نهایت به این سه attribute تبدیل می‌شوند. به مقداردهی در زمان نمونه‌سازی و نیز به خروجی مقادیر از نمونه کدهای بالا توجه نمایید.
 
 همچنین از نسخه 3.2 پایتون می‌توانید با استفاده از متد ``total_seconds`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.timedelta.total_seconds>`__] کل مدت زمان ذخیره شده در شی timedelta را در واحد ثانیه دریافت نمایید::
 
@@ -178,10 +179,15 @@
 کلاس ``datetime.tzinfo``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-هر وقت که صحبت از ساعت و زمان باشد، «منطقه زمانی» (Time zone) نیز جزئی از گفتگو خواهد بود. در زبان برنامه‌نویسی پایتون کلاس ``tzinfo`` از ماژول کلاس ``datetime`` امکان ایجاد منطقه زمانی را فراهم آورده است [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.tzinfo>`__]. ``tzinfo`` در واقع یک کلاس Abstract (درس نوزدهم) می‌باشد که نمی‌توان از آن نمونه‌سازی و شی ایجاد کرد ولی می‌توان به کمک آن کلاس منطقه زمانی دلخواه خود را ایجاد نماییم. برای مشاهده اجزا و نکات مربوط به پیاده‌سازی منطقه زمانی دلخواه می‌توانید به مستندات زبان برنامه‌نویسی پایتون مراجعه نمایید. 
+هر وقت که صحبت از ساعت و زمان باشد، «منطقه زمانی» (Time zone) نیز جزئی از گفتگو خواهد بود. در زبان برنامه‌نویسی پایتون کلاس ``tzinfo`` از ماژول کلاس ``datetime`` امکان ایجاد منطقه زمانی را فراهم آورده است [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.tzinfo>`__]. ``tzinfo`` در واقع یک کلاس Abstract (درس نوزدهم) می‌باشد که نمی‌توان از آن نمونه‌سازی و شی ایجاد کرد ولی می‌توان به کمک آن، کلاس منطقه زمانی دلخواه خود را ایجاد نماییم. برای مشاهده اجزا و نکات مربوط به پیاده‌سازی منطقه زمانی دلخواه می‌توانید به مستندات زبان برنامه‌نویسی پایتون مراجعه نمایید. 
 
 اشتباه نکنید، در اکثر مواقع نیازی به پیاده‌سازی یک کلاس منطقه زمانی در پایتون نمی‌باشد. چرا که از قبل کلاس ``timezone`` از ماژول ``datetime`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#timezone-objects>`__] توسط این زبان فراهم آورده شده است. این کلاس یک subclass از ``datetime.tzinfo`` بوده و مبنای محاسبه منطقه زمانی در آن UTC [`ویکی‌پدیا <https://en.wikipedia.org/wiki/Coordinated_Universal_Time>`__] می‌باشد. این کلاس به تنهایی تمامی نیازهای معمول ما نسبت به ثبت منطقه زمانی در پایتون را برطرف می‌سازد. در سراسر ایران منطقه زمانی یکسان می‌باشد و به صورت استاندارد از مبنای UTC محاسبه می‌گردد؛ به این صورت که در شش ماه نخست سال برابر ``UTC+4:30`` و در شش ماه دوم از سال این مقدار برابر ``UTC+3:30`` خواهد بود [`ویکی‌پدیا Iran Standard Time (IRST) <https://en.wikipedia.org/wiki/Iran_Standard_Time>`__].
 
+.. note::
+
+  در زبان برنامه‌نویسی پایتون اشیای مرتبط با زمان براساس توانایی آگاهی آن‌ها از منطقه زمانی (Time zone) به دو دسته **«آگاه» (aware)** و **«ساده» (naive)** تقسیم‌بندی می‌شوند. بر همین اساس اشیای کلاس ``date`` از نوع naive و اشیای دو کلاس ``time`` و ``datetime`` می‌توانند برحسب شرایط  aware یا naive باشند.
+
+
 
 کلاس ``datetime.timezone``
 ------------------------------
@@ -208,8 +214,42 @@
 
     >>> tz = timezone(timedelta(hours=-5), 'Eastern Time Zone')
 
+از طریق شی ``datetime.timezone`` چهار متد زیر در دسترس خواهد بود، در واقع  این‌ها متدهایی هستند که توسط ``datetime.timezone`` از کلاس ``datetime.tzinfo`` ارث‌برده و Override شده‌اند:
+
+* **متد** ``utcoffset(dt)`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.timezone.utcoffset>`__]: ورودی نادیده گرفته می‌شود و خروجی یک شی ``datetime.timedelta`` برابر اختلاف فاصله زمانی از مبنا UTC می‌باشد.
+
+* **متد** ``tzname(dt)`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.timezone.tzname>`__]: نام منطقه زمانی ارسال شده در زمان نمونه‌سازی را برمی‌گرداند. چنانچه در زمان نمونه‌سازی مقداری ارسال نشده و نام برابر ``None`` باشد، یک نام به صورت خودکار تولید خواهد شد. ورودی می‌تواند ``None`` یا یک شی aware از نوع ``datetime.datetime`` باشد.
+
+* **متد** ``dst(dt)`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.timezone.dst>`__]: خروجی این متد برای اشیا ``datetime.timezone`` همواره برابر ``None`` خواهد بود.
+
+* **متد** ``fromutc(dt)`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.timezone.fromutc>`__]: ورودی می‌بایست یک شی aware از نوع ``datetime.datetime`` باشد و خروجی نیز برابر ``dt + offset`` خواهد بود. در واقع این متد یک شی ``datetime.datetime`` دریافت و منطقه زمانی آن را بر اساس اطلاعات خود تغییر و برمی‌گرداند.
+
+این کلاس حاوی یک Class attribute نیز می‌باشد. ``utc`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.timezone.utc>`__] که برابر یک شی ``datetime.timezone`` جدید براساس منطقه زمانی UTC می‌باشد. یعنی:‌ ``timezone(timedelta(0))``
 
 
+::
+
+    >>> from datetime import timedelta, timezone
+    >>> tz = timezone(timedelta(hours=4, minutes=30), 'Asia/Tehran')
+
+    >>> tz.utcoffset(None)
+    datetime.timedelta(seconds=16200)
+    
+    >>> tz.tzname(None)
+    'Asia/Tehran'
+    
+::
+
+
+    >>> tz = timezone(timedelta(hours=4, minutes=30))
+    >>> tz.tzname(None)
+    'UTC+04:30'
+
+
+::
+
+    >>> type(timezone.utc)
+    <class 'datetime.timezone'>
 
 
 کلاس ``datetime.date``
@@ -531,7 +571,7 @@
 
 * ``microsecond``: از نوع ``int`` می‌باشد و مقداری برابر با میکروثانیه مورد نظر خواهد داشت که می‌بایست عددی از بین اعداد ``0`` تا ``1000000`` باشد : range(1000000) - هر میکروثانیه برابر با 0.000001 ثانیه می‌باشد.
 
-* ``tzinfo``: معرف منطقه زمانی (Time zone) است که مقدار پیش‌فرض آن ``None`` می‌باشد و می‌تواند یک شی از  زیرکلاس‌های (subclass) کلاس ``tzinfo`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.tzinfo>`__] را بپذیرد. در ادامه بیشتر در مورد این نوع اشیا صحبت خواهیم کرد.
+* ``tzinfo``: معرف منطقه زمانی (Time zone) است که مقدار پیش‌فرض آن ``None`` می‌باشد و می‌تواند یک شی از  زیرکلاس‌های (subclass) کلاس ``tzinfo`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.tzinfo>`__] را بپذیرد.
 
 * ``fold``: از نسخه 3.6 پایتون به بعد اضافه شده است و تنها با استفاده از شیوه **نام=مقدار** قابل مقداردهی می‌باشد. این پارامتر در واقع یک نشانگر برای ابهام‌زدایی در بیان ساعت می‌باشد. برای مثال از کاربرد این پارامتر وضعیت «ساعت تابستانی» [`ویکی‌پدیا <https://en.wikipedia.org/wiki/Daylight_saving_time>`__] را تصور کنید. ساعت رسمی ایران هر سال در ساعت ۲۴ روز اول فروردین ماه یک ساعت به جلو کشیده می‌شود و در ساعت ۲۴ روز سی‌ام شهریور ماه به حالت قبلی برگردانده می‌شود، اکنون در روز سی‌ام شهریور ماه ساعت ۲۳ تا ۲۴ دوبار تکرار می‌شود، در این مواقع می‌توان از این پارامتر برای مشخص کردن وضعیت ساعت استفاده کرد. به این صورت که مقدار ``0`` بیانگر وضعیت قبل از تغییر و ``1`` بیانگر وضعیت پس از تغییر می‌تواند باشد.
 
