l25: datetime.time, methods - starting

Saeid Darvish · Saeid Darvish · commit fb71fa990308 · 2021-04-10T20:56:25.000+04:30
diff --git a/lessons/l25.rst b/lessons/l25.rst
@@ -421,6 +421,18 @@
 
 
 
+* **متد** ``today`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.date.today>`__]: جدا از اینکه شی موجود حاوی چه تاریخی است، یک شی تاریخ جدید بر اساس تاریخ روز جاری - با توجه به تنظیمات سیستم‌ - برمی‌گرداند::
+
+    >>> from datetime import date
+
+    >>> d = date(2021, 4, 9)
+    >>> d.today()
+    datetime.date(2021, 4, 10)
+
+
+
+
+
 کلاس ``datetime.time``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -472,17 +484,17 @@
 
 همانطور که از تعریف این کلاس مشخص است، برای نمونه‌سازی از کلاس ``datetime.time`` می‌توان  شش Instance attribute آن را مقداردهی نماییم. این شش attribute که همگی اختیاری و دارای مقدار پیش‌فرض هستند عبارتند از:
 
-* ``hour``: از نوع ``int`` می‌باشد و مقداری برابر با ساعت مورد نظر خواهد داشت. این مقدار می‌بایست  عددی از بین اعداد ``0`` تا ``24`` باشد (``range(24)``). 
+* ``hour``: از نوع ``int`` می‌باشد و مقداری برابر با ساعت مورد نظر خواهد داشت. این مقدار می‌بایست  عددی از بین اعداد ``0`` تا ``24`` باشد : range(24)
 
-* ``minute``: از نوع ``int`` می‌باشد و مقداری برابر با دقیقه مورد نظر خواهد داشت که می‌بایست عددی از بین اعداد ``0`` تا ``60`` باشد (``range(60)``).
+* ``minute``: از نوع ``int`` می‌باشد و مقداری برابر با دقیقه مورد نظر خواهد داشت که می‌بایست عددی از بین اعداد ``0`` تا ``60`` باشد : range(60)
 
-* ``second``: از نوع ``int`` می‌باشد و مقداری برابر با ثانیه مورد نظر خواهد داشت که می‌بایست عددی از بین اعداد ``0`` تا ``60`` باشد (``range(60)``).
+* ``second``: از نوع ``int`` می‌باشد و مقداری برابر با ثانیه مورد نظر خواهد داشت که می‌بایست عددی از بین اعداد ``0`` تا ``60`` باشد : range(60)
 
-* ``microsecond``: از نوع ``int`` می‌باشد و مقداری برابر با میکروثانیه مورد نظر خواهد داشت که می‌بایست عددی از بین اعداد ``0`` تا ``1000000`` باشد (``range(1000000)``). هر میکروثانیه برابر با 0.000001 ثانیه می‌باشد.
+* ``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 پایتون به بعد اضافه شده است و تنها با استفاده از شیوه نام=مقدار قابل مقداردهی می‌باشد. 
+* ``fold``: از نسخه 3.6 پایتون به بعد اضافه شده است و تنها با استفاده از شیوه **نام=مقدار** قابل مقداردهی می‌باشد. این پارامتر در واقع یک نشانگر برای ابهام‌زدایی در بیان ساعت می‌باشد. برای مثال از کاربرد این پارامتر وضعیت «ساعت تابستانی» [`ویکی‌پدیا <https://en.wikipedia.org/wiki/Daylight_saving_time>`__] را تصور کنید. ساعت رسمی ایران هر سال در ساعت ۲۴ روز اول فروردین ماه یک ساعت به جلو کشیده می‌شود و در ساعت ۲۴ روز سی‌ام شهریور ماه به حالت قبلی برگردانده می‌شود، اکنون در روز سی‌ام شهریور ماه ساعت ۲۳ تا ۲۴ دوبار تکرار می‌شود، در این مواقع می‌توان از این پارامتر برای مشخص کردن وضعیت ساعت استفاده کرد. به این صورت که مقدار ``0`` بیانگر وضعیت قبل از تغییر و ``1`` بیانگر وضعیت پس از تغییر می‌تواند باشد.
 
   باید توجه داشت که مقدار این شش attribute پس از نمونه‌سازی قابل تغییر نخواهد بود و به اصطلاح read-only هستند::
 
@@ -491,9 +503,10 @@
       File "<stdin>", line 1, in <module>
     AttributeError: attribute 'hour' of 'datetime.time' objects is not writable
 
+
 |
 
-**۲- با استفاده از کلاس متد** ``fromisoformat`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.time.fromisoformat>`__] از کلاس ``datetime.time`` (البته از نسخه 3.7 پایتون به بعد)، در تعریف این متد یک پارامتر از نوع ``str`` قرار داده شده است که در واقع این متد یک ساعت را براساس قالب کلی استاندارد ISO 8601 [`ویکی‌پدیا <https://en.wikipedia.org/wiki/ISO_8601>`__] دریافت و یک شی معادل از کلاس ``datetime.time`` را برمی‌گرداند. این قالب معمولا برابر ``hh:mm:ss`` می‌باشد که از سمت چپ معرف دو رقم ساعت، دونقطه (colon)، دو رقم دقیقه، دونقطه (colon) و دو رقم ثانیه می‌باشد؛ همانند: ``04:23:01``::
+**۲- با استفاده از کلاس متد** ``fromisoformat`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.time.fromisoformat>`__] از کلاس ``datetime.time`` (البته از نسخه 3.7 پایتون به بعد)، در تعریف این متد یک پارامتر از نوع ``str`` قرار داده شده است که در واقع این متد یک ساعت را براساس قالب کلی استاندارد ISO 8601 [`ویکی‌پدیا <https://en.wikipedia.org/wiki/ISO_8601>`__] دریافت و یک شی معادل از کلاس ``datetime.time`` را برمی‌گرداند. این قالب معمولا برابر ``hh:mm:ss`` می‌باشد که از سمت چپ معرف دو رقم ساعت، دونقطه (colon)، دو رقم دقیقه، دونقطه (colon) و دو رقم ثانیه می‌باشد؛ همانند: ``04:23:01`` - قالب‌های قابل پذیرش به صورت زیر خواهند بود::
 
     >>> import datetime
     
@@ -540,6 +553,51 @@
     >>> t
     datetime.time(4, 0, tzinfo=datetime.timezone(datetime.timedelta(seconds=16200)))
 
+مقایسه دو شی ساعت
+----------------------------
+
+دو شی ``datetime.time`` پایتون قابلیت مقایسه با یکدیگر را دارند اگر هر دو naive یا هر دو aware باشند:
+
+
+::
+
+    >>> from datetime import time
+
+    >>> t_22 = time(22, 0, 0)
+    >>> t_20 = time(20, 0, 0)
+
+    >>> t_22 > t_20
+    True
+    >>> t_22 == t_22
+    True
+    >>> t_22 < t_20
+    False
+
+توجه داشته باشید که نمی‌توان از عملگرهایی همچون ``-`` یا ``+`` برای یک شی از نوع ``datetime.time`` استفاده کرد.
+
+
+متدهای شی ساعت
+----------------------------
+
+برخی از Instance methodهای یک شی ساعت پایتون به شرح زیر هستند:
+
+
+
+* **متد** ``replace`` [`اسناد پایتون <https://docs.python.org/3/library/datetime.html#datetime.time.replace>`__]: با استفاده از این متد می‌توان یک شی ساعت جدید همانند شی جاری ایجاد کرد ولی با کمی تغییرات::
+
+    replace(hour, minute, second, microsecond, tzinfo, *, fold)
+
+  ::
+
+    >>> from datetime import time
+
+    >>> t_22 = time(hour=22, minute=22, second=22)
+
+    >>> t_20 = t_22.replace(hour=20, minute=20)
+    >>> t_20
+    datetime.time(20, 20, 22)
+
+
 
 
 کلاس ``datetime.datetime``
