diff --git a/docs/fa/python-types.md b/docs/fa/python-types.md new file mode 100644 index 000000000..c3776a19a --- /dev/null +++ b/docs/fa/python-types.md @@ -0,0 +1,185 @@ + + +# معرفی انواع داده در پایتون (Python Types) + +پایتون از «نشانه‌های نوع» (type hints) که به آن‌ها «حاشیه‌نویسی نوع» (type annotations) نیز گفته می‌شود، پشتیبانی می‌کند. + +این **نشانه‌های نوع** یک سینتکس خاص دارند که امکان تعیین نوع داده متغیرها را فراهم می‌کنند. + +با تعیین نوع متغیرها، ادیتورها و ابزارها می‌توانند تجربه بهتری برای توسعه ارائه دهند. + +این یک **مرور سریع و کاربردی** درباره‌ی type hints در پایتون است و تنها حداقل موارد موردنیاز برای استفاده در **FastAPI** را پوشش می‌دهد؛ در واقع، آن‌قدر ساده است که به‌راحتی می‌توان آن را یاد گرفت. + +‏**FastAPI** کاملاً بر اساس این type hints ساخته شده و از مزایای آن‌ها بهره می‌برد. + +اما حتی اگر از **FastAPI** استفاده نمی‌کنید، یادگیری این مفاهیم همچنان برایتان مفید خواهد بود. + +/// note +اگر در پایتون حرفه‌ای هستید و همه‌چیز را درباره‌ی type hints می‌دانید، می‌توانید به فصل بعد بروید. +/// + +## انگیزه (Motivation) + +بیایید با یک مثال ساده شروع کنیم: + +{\* ../../docs\_src/python\_types/tutorial001.py \*} + +خروجی اجرای این برنامه: + +``` +John Doe +``` + +این تابع کارهای زیر را انجام می‌دهد: + +- پارامترهای `first_name` و `last_name` را دریافت می‌کند. +- با استفاده از `title()` حرف اول هر کدام را بزرگ می‌کند. +- آن‌ها را با یک فاصله در میانشان ادغام می‌کند. + +{\* ../../docs\_src/python\_types/tutorial001.py hl[2] \*} + +### ویرایش آن + +این یک برنامه‌ی بسیار ساده است. اما تصور کنید در حال نوشتن آن از ابتدا هستید. + +در مرحله‌ای که تعریف تابع را شروع کرده‌اید و پارامترها را مشخص نموده‌اید... + +اما باید متدی را فراخوانی کنید که حرف اول را بزرگ می‌کند. + +آیا `upper` بود؟ `uppercase`؟ `first_uppercase`؟ `capitalize`؟ + +اینجاست که سراغ دوست قدیمی برنامه‌نویس‌ها، یعنی **تکمیل خودکار** ادیتور می‌روید. + +پارامتر اول تابع (`first_name`) را تایپ می‌کنید، یک نقطه (`.`) می‌گذارید و `Ctrl+Space` را فشار می‌دهید تا تکمیل خودکار فعال شود. + +اما متأسفانه چیزی مفید نمایش داده نمی‌شود: + +### افزودن نوع (Add types) + +بیایید یک خط از نسخه‌ی قبلی را تغییر دهیم. بخش پارامترهای تابع را از: + +```Python + first_name, last_name +``` + +به این تغییر می‌دهیم: + +```Python + first_name: str, last_name: str +``` + +این همان **نشانه‌های نوع** است: + +{\* ../../docs\_src/python\_types/tutorial002.py hl[1] \*} + +این کار با تعریف مقدار پیش‌فرض (مثلاً `first_name="john"`) متفاوت است. ما از دونقطه (`:`) استفاده می‌کنیم، نه مساوی (`=`). + +افزودن type hints معمولاً رفتار برنامه را تغییر نمی‌دهد. + +حالا اگر در حال نوشتن همین تابع با type hints باشید و `Ctrl+Space` را فشار دهید، این را مشاهده می‌کنید: + +اکنون می‌توانید گزینه‌های صحیح را سریع‌تر پیدا کنید: + +## انگیزه‌ی بیشتر (More Motivation) + +این تابع که از قبل type hints دارد را بررسی کنید: + +{\* ../../docs\_src/python\_types/tutorial003.py hl[1] \*} + +از آنجا که ادیتور نوع متغیرها را می‌داند، نه تنها **تکمیل خودکار**، بلکه **بررسی خطاها** نیز انجام می‌شود: + +حالا متوجه می‌شوید که باید `age` را با `str(age)` به رشته تبدیل کنید: + +{\* ../../docs\_src/python\_types/tutorial004.py hl[2] \*} + +## اعلام انواع (Declaring Types) + +### انواع ساده (Simple Types) + +می‌توانید از انواع استاندارد پایتون مانند `int`، `float`، `bool` و `bytes` استفاده کنید: + +{\* ../../docs\_src/python\_types/tutorial005.py hl[1] \*} + +### انواع جنریک با پارامترهای نوع (Generic Types) + +ساختارهای داده‌ای مانند `list`، `dict`، `set` و `tuple` که می‌توانند شامل مقادیر دیگر باشند، «جنریک» نامیده می‌شوند. برای تعیین نوع داخلی آن‌ها از ماژول `typing` استفاده می‌شود. + +#### نسخه‌های جدید پایتون + +در نسخه‌های جدید پایتون (مثلاً ۳.۹+)، می‌توانید به جای `List` از `list` استفاده کنید: + +```Python +def process_items(items: list[str]): + for item in items: + print(item) +``` + +#### لیست (List) + +//// tab | Python 3.9+ + +```Python +{!> ../../docs_src/python_types/tutorial006_py39.py!} +``` + +//// + +#### تاپل و ست (Tuple and Set) + +//// tab | Python 3.9+ + +```Python +{!> ../../docs_src/python_types/tutorial007_py39.py!} +``` + +//// + +#### دیکشنری (Dict) + +//// tab | Python 3.9+ + +```Python +{!> ../../docs_src/python_types/tutorial008_py39.py!} +``` + +//// + +#### یونیون (Union) + +در پایتون ۳.۱۰+ می‌توانید از سینتکس `|` استفاده کنید: + +//// tab | Python 3.10+ + +```Python +{!> ../../docs_src/python_types/tutorial008b_py310.py!} +``` + +//// + +#### مقادیر اختیاری (Optional) + +```Python +from typing import Optional + +def say_hi(name: Optional[str] = None): + if name is not None: + print(f"Hey {name}!") + else: + print("Hello World") +``` + +## نوعدهی در FastAPI + +‏FastAPI از type hints برای: + +- دریافت خودکار پارامترها +- تبدیل داده‌ها +- اعتبارسنجی +- تولید مستندات OpenAPI + +استفاده می‌کند. + +/// اطلاعات +اگر همه‌ی آموزش را گذرانده‌اید و بازگشته‌اید تا اطلاعات بیشتری درباره‌ی انواع داده به دست آورید، یک منبع خوب "cheat sheet" از mypy است. +/// +