Merge pull request #1 from Mohammad222PR/docs/add-fa-docs

docs(fastapi): add Persian (fa) translation for Python Types document…

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 است.
+///
+