🌐 [translation-sync] Add Type Hints section to More Language Features lecture

.translate/state/python_advanced_features.md.yml

@@ -1,6 +1,6 @@
-source-sha: 1a87942398e15e03539083cc944a78653c532607
-synced-at: "2026-03-20"
-model: unknown
-mode: RESYNC
-section-count: 6
-tool-version: 0.11.0
+source-sha: f791129259d11c138d7662c88f994c9d5ebaa875
+synced-at: "2026-03-24"
+model: claude-sonnet-4-6
+mode: UPDATE
+section-count: 7
+tool-version: 0.12.2

lectures/python_advanced_features.md

@@ -8,29 +8,36 @@ kernelspec:
   language: python
   name: python3
 heading-map:
+  More Language Features: ویژگی‌های بیشتر زبان
   Overview: مروری کلی
-  Iterables and Iterators: Iterableها و Iteratorها
-  Iterables and Iterators::Iterators: Iteratorها
-  Iterables and Iterators::Iterators in For Loops: Iteratorها در حلقه‌های For
-  Iterables and Iterators::Iterables: Iterableها
-  Iterables and Iterators::Iterators and built-ins: Iteratorها و توابع داخلی
-  '`*` and `**` Operators': عملگرهای `*` و `**`
-  '`*` and `**` Operators::Unpacking Arguments': باز کردن آرگومان‌ها
-  '`*` and `**` Operators::Arbitrary Arguments': آرگومان‌های دلخواه
-  Decorators and Descriptors: Decoratorها و Descriptorها
-  Decorators and Descriptors::Decorators: Decoratorها
-  Decorators and Descriptors::Decorators::An Example: یک مثال
-  Decorators and Descriptors::Decorators::Enter Decorators: Decoratorها وارد می‌شوند
-  Decorators and Descriptors::Descriptors: Descriptorها
-  Decorators and Descriptors::Descriptors::A Solution: یک راه‌حل
-  Decorators and Descriptors::Descriptors::How it Works: چگونه کار می‌کند
-  Decorators and Descriptors::Descriptors::Decorators and Properties: Decoratorها و Propertyها
+  Iterables and iterators: Iterableها و Iteratorها
+  Iterables and iterators::Iterators: Iteratorها
+  Iterables and iterators::Iterators in for loops: Iteratorها در حلقه‌های for
+  Iterables and iterators::Iterables: Iterableها
+  Iterables and iterators::Iterators and built-ins: Iteratorها و توابع داخلی
+  '`*` and `**` operators': عملگرهای `*` و `**`
+  '`*` and `**` operators::Unpacking arguments': باز کردن آرگومان‌ها
+  '`*` and `**` operators::Arbitrary arguments': آرگومان‌های دلخواه
+  Type hints: راهنمای نوع
+  Type hints::Basic syntax: نحو پایه
+  Type hints::Common types: نوع‌های رایج
+  Type hints::Hints don't enforce types: راهنمای نوع، نوع‌ها را اعمال نمی‌کند
+  Type hints::Why use type hints?: چرا از راهنمای نوع استفاده کنیم؟
+  Type hints::Type hints in scientific Python: راهنمای نوع در پایتون علمی
+  Decorators and descriptors: Decoratorها و Descriptorها
+  Decorators and descriptors::Decorators: Decoratorها
+  Decorators and descriptors::Decorators::An example: یک مثال
+  Decorators and descriptors::Decorators::Enter decorators: Decoratorها وارد می‌شوند
+  Decorators and descriptors::Descriptors: Descriptorها
+  Decorators and descriptors::Descriptors::A solution: یک راه‌حل
+  Decorators and descriptors::Descriptors::How it works: چگونه کار می‌کند
+  Decorators and descriptors::Descriptors::Decorators and properties: Decoratorها و propertyها
   Generators: Generatorها
-  Generators::Generator Expressions: عبارات Generator
-  Generators::Generator Functions: توابع Generator
-  Generators::Generator Functions::Example 1: مثال 1
-  Generators::Generator Functions::Example 2: مثال 2
-  Generators::Advantages of Iterators: مزایای Iteratorها
+  Generators::Generator expressions: عبارات generator
+  Generators::Generator functions: توابع generator
+  Generators::Generator functions::Example 1: مثال 1
+  Generators::Generator functions::Example 2: مثال 2
+  Generators::Advantages of iterators: مزایای iteratorها
   Exercises: تمرین‌ها
 ---
 
@@ -47,14 +54,14 @@ heading-map:
 
 ## مروری کلی
 
-توصیه ما برای این سخنرانی آخر این است که **در مرور اول آن را رد کنید**، مگر اینکه میل شدیدی به خواندن آن داشته باشید.
+توصیه ما برای این درس آخر این است که *در مرور اول آن را رد کنید*، مگر اینکه میل شدیدی به خواندن آن داشته باشید.
 
-این سخنرانی اینجاست
+این درس اینجاست
 
 1. به عنوان مرجع، تا بتوانیم در صورت نیاز به آن لینک دهیم، و
 1. برای کسانی که تعدادی از کاربردها را انجام داده‌اند و اکنون می‌خواهند بیشتر درباره زبان Python یاد بگیرند
 
-موضوعات متنوعی در این سخنرانی بررسی می‌شوند، از جمله iteratorها، decoratorها و descriptorها، و generatorها.
+موضوعات متنوعی در این درس بررسی می‌شوند، از جمله iteratorها، type hintها، decoratorها و descriptorها، و generatorها.
 
 ## Iterableها و Iteratorها
 
@@ -66,6 +73,7 @@ heading-map:
 اکنون بیایید دقیق‌تر به نحوه کار آن نگاه کنیم، با تمرکز بر پیاده‌سازی Python از حلقه `for`.
 
 (iterators)=
+
 ### Iteratorها
 
 ```{index} single: Python; Iterators
@@ -155,7 +163,7 @@ next(nikkei_data)
 next(nikkei_data)
 ```
 
-### Iteratorها در حلقه‌های For
+### Iteratorها در حلقه‌های for
 
 ```{index} single: Python; Iterators
 ```
@@ -317,7 +325,6 @@ max(y)
 
 در این بخش، نحوه استفاده از آن‌ها و تمایز موارد استفاده آن‌ها را بررسی خواهیم کرد.
 
-
 ### باز کردن آرگومان‌ها
 
 وقتی روی لیستی از پارامترها عمل می‌کنیم، اغلب نیاز داریم که محتوای لیست را به عنوان آرگومان‌های منفرد به جای یک مجموعه استخراج کنیم هنگام ارسال آن‌ها به توابع.
@@ -484,6 +491,108 @@ arb(l1=l1, l2=l2, l3=l3)
 
 تفاوت این است که توابع با `*args` قادر خواهند بود *آرگومان‌های موضعی* با اندازه دلخواه بپذیرند، در حالی که `**kargs` به توابع اجازه می‌دهد تعداد دلخواه *آرگومان‌های کلیدواژه‌ای* بپذیرند.
 
+## راهنمای نوع
+
+```{index} single: Python; Type Hints
+```
+
+پایتون یک زبان *با نوع‌بندی پویا* است، به این معنا که نیازی به اعلام نوع متغیرها ندارید.
+
+(بحث {doc}`قبلی ما <need_for_speed>` درباره نوع‌بندی پویا در مقابل ایستا را ببینید.)
+
+با این حال، پایتون از **راهنمای نوع** اختیاری (که به آن حاشیه‌نویسی نوع نیز گفته می‌شود) پشتیبانی می‌کند که به شما امکان می‌دهد نوع‌های مورد انتظار متغیرها، پارامترهای تابع و مقادیر بازگشتی را مشخص کنید.
+
+راهنمای نوع از پایتون ۳.۵ معرفی شده و در نسخه‌های بعدی توسعه یافته است.
+تمام نحوی که در اینجا نشان داده شده در پایتون ۳.۹ و بعد از آن کار می‌کند.
+
+```{note}
+راهنمای نوع در زمان اجرا *توسط مفسر پایتون نادیده گرفته می‌شود* --- آنها بر نحوه اجرای کد شما تأثیر نمی‌گذارند. آنها صرفاً اطلاعاتی هستند و به عنوان مستندات برای انسان‌ها و ابزارها عمل می‌کنند.
+```
+
+### نحو پایه
+
+راهنمای نوع از دو نقطه `:` برای حاشیه‌نویسی متغیرها و پارامترها، و از پیکان `->` برای حاشیه‌نویسی نوع‌های بازگشتی استفاده می‌کند.
+
+در اینجا یک مثال ساده آمده است:
+
+```{code-cell} python3
+def greet(name: str, times: int) -> str:
+    return (name + '! ') * times
+
+greet('hello', 3)
+```
+
+در این تعریف تابع:
+
+- `name: str` نشان می‌دهد که `name` انتظار می‌رود یک رشته باشد
+- `times: int` نشان می‌دهد که `times` انتظار می‌رود یک عدد صحیح باشد
+- `-> str` نشان می‌دهد که تابع یک رشته برمی‌گرداند
+
+همچنین می‌توانید متغیرها را مستقیماً حاشیه‌نویسی کنید:
+
+```{code-cell} python3
+x: int = 10
+y: float = 3.14
+name: str = 'Python'
+```
+
+### نوع‌های رایج
+
+پرکاربردترین راهنمای نوع، نوع‌های توکار هستند:
+
+| نوع       | مثال                             |
+|-----------|----------------------------------|
+| `int`     | `x: int = 5`                    |
+| `float`   | `x: float = 3.14`              |
+| `str`     | `x: str = 'hello'`             |
+| `bool`    | `x: bool = True`               |
+| `list`    | `x: list = [1, 2, 3]`          |
+| `dict`    | `x: dict = {'a': 1}`           |
+
+برای ظرف‌ها، می‌توانید نوع‌های عناصر آنها را مشخص کنید:
+
+```{code-cell} python3
+prices: list[float] = [9.99, 4.50, 2.89]
+counts: dict[str, int] = {'apples': 3, 'oranges': 5}
+```
+
+### راهنمای نوع، نوع‌ها را اعمال نمی‌کند
+
+یک نکته مهم برای برنامه‌نویسان جدید پایتون: راهنمای نوع در زمان اجرا *اعمال نمی‌شود*.
+
+پایتون در صورت ارسال نوع «اشتباه» خطایی ایجاد نمی‌کند:
+
+```{code-cell} python3
+def add(x: int, y: int) -> int:
+    return x + y
+
+# Passes floats — Python doesn't complain
+add(1.5, 2.7)
+```
+
+راهنمای نوع `int` را نشان می‌دهد، اما پایتون با خوشحالی آرگومان‌های `float` را می‌پذیرد و `4.2` را برمی‌گرداند --- که آن هم `int` نیست.
+
+این تفاوت کلیدی با زبان‌های با نوع‌بندی ایستا مانند C یا Java است، که در آنها عدم تطابق نوع‌ها باعث خطاهای کامپایل می‌شود.
+
+### چرا از راهنمای نوع استفاده کنیم؟
+
+اگر پایتون آنها را نادیده می‌گیرد، چرا زحمت آن را بکشیم؟
+
+1. **خوانایی**: راهنمای نوع امضای تابع را خودمستندساز می‌کند. خواننده بلافاصله می‌داند که تابع چه نوع‌هایی را انتظار دارد و برمی‌گرداند.
+2. **پشتیبانی ویرایشگر**: محیط‌های توسعه یکپارچه مانند VS Code از راهنمای نوع برای ارائه تکمیل خودکار بهتر، تشخیص خطا و مستندات درون‌خطی استفاده می‌کنند.
+3. **بررسی خطا**: ابزارهایی مانند [mypy](https://mypy.readthedocs.io/) و [pyrefly](https://pyrefly.org/) راهنمای نوع را تحلیل می‌کنند تا اشکالات را *قبل از* اجرای کد شناسایی کنند.
+4. **کد تولیدشده توسط مدل‌های زبانی بزرگ**: مدل‌های زبانی بزرگ اغلب کدی با راهنمای نوع تولید می‌کنند، بنابراین درک نحو به شما کمک می‌کند تا خروجی آنها را بخوانید و استفاده کنید.
+
+### راهنمای نوع در پایتون علمی
+
+راهنمای نوع به بحث {doc}`نیاز به سرعت <need_for_speed>` مرتبط است:
+
+* کتابخانه‌های پرکارایی مانند [JAX](https://jax.readthedocs.io/) و [Numba](https://numba.pydata.org/) برای کامپایل کد ماشین سریع به دانستن نوع متغیرها متکی هستند.
+* در حالی که این کتابخانه‌ها نوع‌ها را در زمان اجرا استنتاج می‌کنند نه اینکه مستقیماً راهنمای نوع پایتون را بخوانند، *مفهوم* یکسان است --- اطلاعات صریح نوع، بهینه‌سازی را ممکن می‌سازد.
+* با تکامل اکوسیستم پایتون، انتظار می‌رود ارتباط بین راهنمای نوع و ابزارهای کارایی رشد کند.
+
+در حال حاضر، مزیت اصلی راهنمای نوع در پایتون روزمره *وضوح و پشتیبانی ابزاری* است، که با بزرگ‌تر شدن برنامه‌ها ارزش آن بیشتر می‌شود.
+
 ## Decoratorها و Descriptorها
 
 ```{index} single: Python; Decorators
@@ -656,6 +765,7 @@ def g(x):
 به نظر بسیاری از افراد، این نحو decorator را به یک بهبود قابل توجه برای زبان تبدیل می‌کند.
 
 (descriptors)=
+
 ### Descriptorها
 
 ```{index} single: Python; Descriptors
@@ -770,7 +880,7 @@ car.kms
 به عنوان یک property، وقتی مقدار آن را از طریق `car.miles = 6000` تنظیم می‌کنیم، متد setter
 آن فعال می‌شود --- در این مورد `set_miles`.
 
-#### Decoratorها و Propertyها
+#### Decoratorها و propertyها
 
 ```{index} single: Python; Decorators
 ```
@@ -814,6 +924,7 @@ class Car:
 برای اطلاعات بیشتر می‌توانید به [مستندات descriptor](https://docs.python.org/3/howto/descriptor.html) مراجعه کنید.
 
 (paf_generators)=
+
 ## Generatorها
 
 ```{index} single: Python; Generators
@@ -823,7 +934,7 @@ class Car:
 
 دو راه برای ساخت generatorها مطالعه خواهیم کرد: عبارات generator و توابع generator.
 
-### عبارات Generator
+### عبارات generator
 
 ساده‌ترین راه برای ساخت generatorها استفاده از *عبارات generator* است.
 
@@ -879,7 +990,7 @@ sum((x * x for x in range(10)))
 sum(x * x for x in range(10))
 ```
 
-### توابع Generator
+### توابع generator
 
 ```{index} single: Python; Generator Functions
 ```
@@ -1026,7 +1137,7 @@ def g(x):
         x = x * x
 ```
 
-### مزایای Iteratorها
+### مزایای iteratorها
 
 مزیت استفاده از iterator اینجا چیست؟
 
@@ -1084,7 +1195,6 @@ sum(draws)
 * نیاز به ایجاد لیست‌ها/tupleهای بزرگ را از بین می‌برند، و
 * یک رابط یکنواخت برای تکرار فراهم می‌کنند که می‌تواند به صورت شفاف در حلقه‌های `for` استفاده شود
 
-
 ## تمرین‌ها
 
 
@@ -1145,4 +1255,4 @@ for date in dates:
 ```
 
 ```{solution-end}
-```
+```