l21: working on Data Classe

Author: Saeid Darvish

lessons/l21.rst

@@ -24,10 +24,86 @@
 ----
 
 
+Decorators
+----------------------------
+
+از درس سیزدهم با مفهوم Decoratorها و نیز کاربرد آن‌ها به همراه تابع در زبان برنامه‌نویسی پایتون آشنا شده‌ایم، در این بخش به بررسی Decoratorهابه همراه کلاس‌ها و متدها می‌پردازیم.
+
+علاوه بر اینکه با استفاده از کلاس می‌توان یک Decorator ایجاد کرد، از Decorator‌ها نیز می‌توان بر روی کلاس یا متدهای داخل یک کلاس بهره گرفت. در ادامه به بررسی این موارد می‌پردازیم.
+
+
+قراردادن Decorator بر روی متد
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+این کار همانند قراردادن Decorator بر روی تابع می‌باشد (درس سیزدهم) و تفاوتی ندارد. پیش‌تر نیز از Decoratorهایی همچون ``classmethod@`` یا ``staticmethod@`` بر روی متدها استفاده می‌کردیم. به مثالی در همین زمینه توجه نمایید:
+
+
+.. code-block:: python
+    :linenos:
+
+    import functools
+
+    def debug(func):
+        """Print the function signature and return value
+           Source: https://realpython.com/primer-on-python-decorators/#debugging-code"""
+
+        @functools.wraps(func)
+        def wrapper_debug(*args, **kwargs):
+            args_repr = [repr(a) for a in args]                     
+            kwargs_repr = [f"{k}={v!r}" for k, v in kwargs.items()]
+            signature = ", ".join(args_repr + kwargs_repr)      
+            print(f"Calling {func.__name__}({signature})")
+            value = func(*args, **kwargs)
+            print(f"{func.__name__!r} returned {value!r}")       
+            return value
+        return wrapper_debug
+
+
+
+    class Sample:
+
+        @debug
+        def __init__(self, x=0, y=0):
+            self.x = x
+            self.y = y
+
+
+    sample = Sample(5, y=6)
+
+::
+
+    Calling __init__(<__main__.Sample object at 0x7fd96ddec8d0>, 5, y=6)
+    '__init__' returned None
+
+در نمونه کد بالا یک Decorator با نام ``debug`` ایجاد گردیده است (Decorator درس سیزدهم و f-string درس هفتم)، با قراردادن این Decorator بر روی یک تابع یا متد: نام تابع، آرگومان‌های ارسال شده و همچنین مقدار خروجی تابع را بر روی خروجی نمایش می‌دهد.
+
+
+
+قراردادن Decorator بر روی کلاس
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+کلاس به عنوان Decorator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+Descriptors
+----------------------------
+
+
+
+Properties
+----------------------------
+
+
+
+
 Data Classes
 ----------------------------
 
-از **نسخه 3.7 پایتون** یک ویژگی جالب به پایتون اضافه گردید. دیتا کلاس **(Data Class)**، در واقع یک سینتکسی ساده‌سازی شده برای ایجاد کلاس‌هایی که معمولا تنها حاوی Instance Attribute می‌باشند. این نوع کلاس با استفاده از دکوراتور ``dataclass@`` از ماژول ``dataclasses`` ایجاد می‌گردد [`اسناد پایتون <https://docs.python.org/3/library/dataclasses.html>`__]. برای مثال کلاس زیر را در نظر بگیرید:
+از **نسخه 3.7 پایتون** یک ویژگی جالب به پایتون اضافه گردید. دیتا کلاس **(Data Class)** [`PEP 557 <https://www.python.org/dev/peps/pep-0557>`__]، در واقع یک سینتکسی ساده‌سازی شده برای ایجاد کلاس‌هایی که معمولا تنها حاوی Instance Attribute می‌باشند. این نوع کلاس با استفاده از دکوراتور ``dataclass@`` از ماژول ``dataclasses`` ایجاد می‌گردد [`اسناد پایتون <https://docs.python.org/3/library/dataclasses.html>`__]. برای مثال کلاس زیر را در نظر بگیرید:
 
 
 .. code-block:: python
@@ -60,7 +136,7 @@ Data Classes
 
 در این نوع کلاس برای تعریف Attributeها از سینتکس  Variable Annotations [`PEP 526 <https://www.python.org/dev/peps/pep-0526/>`__] استفاده می‌شود. این سینتکس و در کل ذکر نوع داده در پایتون یا Type Hints [`PEP 484 <https://www.python.org/dev/peps/pep-0484/>`__] **موضوع درس بعدی است**. در این شیوه نوع متغیرها به صراحت ذکر می‌گردد. در حالت عادی تعریف یک متغییر در زبان برنامه‌نویسی پایتون به صورت ``var = value`` می‌باشد (درس ششم)، همانطور که می‌دانیم تاکنون هیچ‌گاه در پایتون برای تعریف متغییر نیازی به ذکر صریح نوع داده نمی‌بود، **اکنون نیز نیازی نیست**، ولی از **نسخه 3.6 پایتون** می‌توانیم اینکار را انجام دهیم، می‌توانیم نوع داده را خودمان مشخص کنیم یا به اصطلاح آن نوع را annotation کنیم. سینتکس این عملیات به صورت ``var: annotation`` می‌باشد، این سینتکس مشخص می‌کند که متغییر var از نوع annotation می‌باشد. همچنین با استفاده از سینتکس ``var: annotation = value`` نیز می‌توان همزمان عملیات انتساب و مقداردهی را نیز انجام داد. باید توجه داشت که تغییری در ساختار مفسر پایتون ایجاد نشده است!، بلکه صرفا سینتکس جدیدی اضافه شده که می‌تواند به ابزارهای شخص‌ثالث (third party) همانند IDEها برای کنترل نوع داده‌ها در زمان توسعه برنامه یاری‌رسان باشد.
 
-باید توجه داشت که طبق سند PEP 484 پیروی از اصول Type Hints در پایتون اجباری نبوده و نخواهد شد. ولی Data Class یک استثناست و در آن حتما می‌بایست Attributeها به شیوه شرح داده شده، تعریف گردند.
+باید توجه داشت که طبق سند PEP 484 پیروی از اصول Type Hints در پایتون اجباری نبوده و نخواهد شد. ولی Data Class یک استثناست و در آن حتما می‌بایست Attributeها به شیوه شرح داده شده، تعریف گردند و به آن‌ها فیلدهای (field) دیتا کلاس گفته می‌شود.
 
 از آنجا که این نوع کلاس برای ایجاد یک کاربرد عمومی از کلاس‌ها توسعه یافته (نگهداری اطلاعات)، بنابراین بسیاری از عملیات‌ها در آن خودکارسازی شده تا پیاده‌سازی این کلاس ساده‌تر از هر کلاس دیگری باشد. برای مثال نیازی به پیاده‌سازی متد ``__init__`` نیست و این متد به صورت خودکار برای کلاس ما ایجاد می‌گردد. اکنون اگر بخواهیم دیتاکلاس مثال قبل را به صورت عادی پیاده‌سازی کنیم:
 
@@ -167,7 +243,7 @@ Data Classes
 
 
 
-از طریق ماژول ``dataclasses`` یک نوع یک annotation type جدید با نام ``InitVar`` در دسترس است. چنانچه در تعریف هر یک از Attributeها کلاس از این نوع استفاده کنیم، آن Attribute به عنوان پارامتر به متد ``__post_init__`` ارسال می‌گردد. باید توجه داشت که این نوع Attributeها به عنوان **Init-only variables** شناخته می‌شوند [`اسناد پایتون <https://docs.python.org/3/library/dataclasses.html#init-only-variables>`__] و مفسر پایتون آن‌ها را صرفا به ``__post_init__`` ارسال می‌کند و جزو فیلدهای دیتا کلاس قرار نمی‌دهد:
+از طریق ماژول ``dataclasses`` یک نوع یک annotation type جدید با نام ``InitVar`` در دسترس است. چنانچه در تعریف هر یک از Attributeها کلاس از این نوع استفاده کنیم، آن Attribute به عنوان پارامتر به متد ``__post_init__`` ارسال می‌گردد. باید توجه داشت که این نوع Attributeها به عنوان **Init-only variables** شناخته می‌شوند [`اسناد پایتون <https://docs.python.org/3/library/dataclasses.html#init-only-variables>`__] و مفسر پایتون آن‌ها را صرفا به ``__post_init__`` ارسال می‌کند و **جزو فیلدهای دیتا کلاس قرار نمی‌دهد**:
 
 
 .. code-block:: python
@@ -193,85 +269,65 @@ Data Classes
     Student(score=100)
 
 
-تابع ``fields``
+تابع ``field`` و ``fields``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-
-
-
-Decorators
-----------------------------
-
-از درس سیزدهم با مفهوم Decoratorها و نیز کاربرد آن‌ها به همراه تابع در زبان برنامه‌نویسی پایتون آشنا شده‌ایم، در این بخش به بررسی Decoratorهابه همراه کلاس‌ها و متدها می‌پردازیم.
-
-علاوه بر اینکه با استفاده از کلاس می‌توان یک Decorator ایجاد کرد، از Decorator‌ها نیز می‌توان بر روی کلاس یا متدهای داخل یک کلاس بهره گرفت. در ادامه به بررسی این موارد می‌پردازیم.
-
-
-قراردادن Decorator بر روی متد
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-این کار همانند قراردادن Decorator بر روی تابع می‌باشد (درس سیزدهم) و تفاوتی ندارد. پیش‌تر نیز از Decoratorهایی همچون ``classmethod@`` یا ``staticmethod@`` بر روی متدها استفاده می‌کردیم. به مثالی در همین زمینه توجه نمایید:
-
+تابع ``fields`` از ماژول ``dataclasses`` یک شی از دیتا کلاس یا خود دیتا کلاس را از ورودی دریافت و یک تاپل حاوی تمام فیلد‌های آن بر می‌گرداند [`اسناد پایتون <https://docs.python.org/3/library/dataclasses.html#dataclasses.fields>`__]:
 
 .. code-block:: python
     :linenos:
 
-    import functools
-
-    def debug(func):
-        """Print the function signature and return value
-           Source: https://realpython.com/primer-on-python-decorators/#debugging-code"""
+    from dataclasses import dataclass, InitVar, fields
 
-        @functools.wraps(func)
-        def wrapper_debug(*args, **kwargs):
-            args_repr = [repr(a) for a in args]                     
-            kwargs_repr = [f"{k}={v!r}" for k, v in kwargs.items()]
-            signature = ", ".join(args_repr + kwargs_repr)      
-            print(f"Calling {func.__name__}({signature})")
-            value = func(*args, **kwargs)
-            print(f"{func.__name__!r} returned {value!r}")       
-            return value
-        return wrapper_debug
+    @dataclass
+    class Student:
+        name: str
+        score: int = 70
+        age: InitVar[int] = 18
 
 
+    obj = Student('saeid', 90, 20)
+    print(obj)
+    print(fields(obj))
 
-    class Sample:
+::
 
-        @debug
-        def __init__(self, x=0, y=0):
-            self.x = x
-            self.y = y
+   Student(name='saeid', score=90)
+   (Field(name='name',type=<class 'str'>,default=<dataclasses._MISSING_TYPE object at 0x7f7e5c68cd68>,default_factory=<dataclasses._MISSING_TYPE object at 0x7f7e5c68cd68>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD), Field(name='score',type=<class 'int'>,default=70,default_factory=<dataclasses._MISSING_TYPE object at 0x7f7e5c68cd68>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD))
 
 
-    sample = Sample(5, y=6)
+پیش‌تر گفتیم، Attributeهای داخل یک دیتا کلاس فیلد (Field) خوانده می‌شوند. خروجی بالا نمایش ساختار یک شی Field از دیتا کلاس می‌باشد [`اسناد پایتون <https://docs.python.org/3/library/dataclasses.html#dataclasses.field>`__]. در واقع متغیرهایی که داخل دیتا کلاس با سنتکس Variable Annotations تعریف می‌شوند، به صورت خودکار به فیلد (Field) تبدیل می‌شوند. فیلدها می‌توانند حاوی مقدار پیش‌فرض باشند (همانند فیلد ``score``). برای کاستن از حجم functionality داخل یک دیتا کلاس، ماژول ``dataclasses`` پایتون شامل تابعی است با نام ``field`` که توانایی و انعطاف زیادی در فراهم آوردن مقدار پیش‌فرض برای فیلدهای تعریف شده ایجاد می‌کند. 
 
-::
+یک شی فیلد شامل پارامترهایی است که از طریق تابع ``field`` قابل تنظیم هستند، البته به جز دو پارامتر زیر که از تعریف Variable Annotations استنباط می‌شوند:
 
-    Calling __init__(<__main__.Sample object at 0x7fd96ddec8d0>, 5, y=6)
-    '__init__' returned None
 
-در نمونه کد بالا یک Decorator با نام ``debug`` ایجاد گردیده است (Decorator درس سیزدهم و f-string درس هفتم)، با قراردادن این Decorator بر روی یک تابع یا متد: نام تابع، آرگومان‌های ارسال شده و همچنین مقدار خروجی تابع را بر روی خروجی نمایش می‌دهد.
+* ``name``: نام فیلد
 
+* ``type``: نوع (type) فیلد
 
+**تعریف مقدار پیش‌فرض برای یک فیلد با استفاده از تابع** ``field``::
 
-قراردادن Decorator بر روی کلاس
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    field(*, default=MISSING, default_factory=MISSING, repr=True, hash=None, init=True, compare=True, metadata=None)
 
+* توجه:‌ همانطور که از مبحث Keyword-Only Arguments از درس دوازدهم به یاد داریم، فراخوانی این تابع تنها با استفاده از ارسال آرگومان به صورت نام=مقدار مجاز خواهید بود.
 
 
-کلاس به عنوان Decorator
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* ``default``:  مقدار پیش‌فرض فیلد، در صورت عدم نیاز می‌بایست با مقدار ویژه ``MISSING`` مقداردهی گردد.
 
+* ``default_factory``: یک موجودیت callable بدون آرگومان را دریافت می‌کند و در زمانی که به مقدار پیش‌فرض برای فیلد نیاز باشد، فراخوانی می‌گردد. در صورت عدم نیاز می‌بایست با مقدار ویژه ``MISSING`` مقداردهی گردد. به بیانی دیگر می‌توان با استفاده از این پارامتر،‌ یک تابع به فیلد اختصاص داد که مقدار یا مقادیر پیش‌فرضی را برای فیلد مورد نظر تولید نماید. 
 
+* توجه: در هر فیلد تنها یکی از دو پارامتر ``default`` یا ``default_factory`` می‌بایست حاوی مقداری غیر از ``MISSING`` باشد.
 
-Descriptors
-----------------------------
 
+* ``repr``, ``init``, ``compare``, ``hash``: در صورتی که هر کدام از این پارامتر‌ها برابر با مقدار ``True`` (پیش‌فرض) تنطیم گردند، فیلد مربوطه به متدهای ایجاد شده متناظر با هر پارامتر ارسال خواهد شد::
 
+      repr    -->> __repr__ __str__
+      init    -->> __init__
+      compare -->> __eq__ __ne__ __lt__ __le__ __gt__ __ge__
+      hash    -->> __hash__
 
-Properties
-----------------------------
 
+* توجه چنانچه مقدار ``compare`` برای ``True`` تنظیم گردد (حالت پیش‌فرض)،‌مقدار ``hash`` می‌بایست ``None`` (و نه ``False``) باشد، چرا که عملیات مقایسه دو شی دیگر به مقدار hash وابسته نبوده و از طریق متدهای تولید شده (__eq__ و غیره) انجام خواهد شد.