Kinuax
1 week ago
committed by
GitHub
GitHub
11 changed files with 1364 additions and 84 deletions
|
After Width: | Height: | Size: 3.6 KiB |
|
After Width: | Height: | Size: 4.0 KiB |
@ -0,0 +1,444 @@ |
|||
# هم‌زمانی و async / await |
|||
|
|||
جزئیات در مورد سینتکس `async def` برای *توابع عملیات مسیر* و یه کم پیش‌زمینه در مورد کد ناهم‌زمان، هم‌زمانی و موازی‌سازی. |
|||
|
|||
## عجله داری؟ |
|||
|
|||
<abbr title="خیلی طولانی بود؛ نخوندم"><strong>TL;DR:</strong></abbr> |
|||
|
|||
اگه از کتابخونه‌های سوم‌شخصی استفاده می‌کنی که بهت می‌گن با `await` صداشون کنی، مثل: |
|||
|
|||
```Python |
|||
results = await some_library() |
|||
``` |
|||
|
|||
اون وقت، *توابع عملیات مسیرت* رو با `async def` تعریف کن، اینجوری: |
|||
|
|||
```Python hl_lines="2" |
|||
@app.get('/') |
|||
async def read_results(): |
|||
results = await some_library() |
|||
return results |
|||
``` |
|||
|
|||
/// note |
|||
|
|||
فقط توی توابعی که با `async def` ساخته شدن می‌تونی از `await` استفاده کنی. |
|||
|
|||
/// |
|||
|
|||
--- |
|||
|
|||
اگه از یه کتابخونه سوم‌شخص استفاده می‌کنی که با یه چیزی (مثل دیتابیس، API، سیستم فایل و غیره) ارتباط داره و از `await` پشتیبانی نمی‌کنه (که الان برای بیشتر کتابخونه‌های دیتابیس اینجوریه)، اون وقت *توابع عملیات مسیرت* رو عادی، فقط با `def` تعریف کن، اینجوری: |
|||
|
|||
```Python hl_lines="2" |
|||
@app.get('/') |
|||
def results(): |
|||
results = some_library() |
|||
return results |
|||
``` |
|||
|
|||
--- |
|||
|
|||
اگه برنامه‌ات (به هر دلیلی) لازم نیست با چیز دیگه‌ای ارتباط برقرار کنه و منتظر جوابش بمونه، از `async def` استفاده کن. |
|||
|
|||
--- |
|||
|
|||
اگه نمی‌دونی چیکار کنی، از `def` معمولی استفاده کن. |
|||
|
|||
--- |
|||
|
|||
**توجه**: می‌تونی توی *توابع عملیات مسیرت* هر چقدر که لازم داری `def` و `async def` رو قاطی کنی و هر کدوم رو با بهترین گزینه برات تعریف کنی. FastAPI خودش کار درست رو باهاشون انجام می‌ده. |
|||
|
|||
به هر حال، توی هر کدوم از موقعیت‌های بالا، FastAPI هنوز ناهم‌زمان کار می‌کنه و خیلی خیلی سریع هست. |
|||
|
|||
ولی با دنبال کردن مراحل بالا، می‌تونه یه سری بهینه‌سازی عملکرد هم بکنه. |
|||
|
|||
## جزئیات فنی |
|||
|
|||
نسخه‌های مدرن پایتون از **"کد ناهم‌زمان"** با چیزی که بهش **"کروتین"** می‌گن پشتیبانی می‌کنن، با سینتکس **`async` و `await`**. |
|||
|
|||
بیاید این جمله رو تکه‌تکه توی بخش‌های زیر ببینیم: |
|||
|
|||
* **کد ناهم‌زمان** |
|||
* **`async` و `await`** |
|||
* **کروتین‌ها** |
|||
|
|||
## کد ناهم‌زمان |
|||
|
|||
کد ناهم‌زمان یعنی زبون 💬 یه راهی داره که به کامپیوتر / برنامه 🤖 بگه توی یه جای کد، باید منتظر بمونه تا *یه چیز دیگه* یه جای دیگه تموم بشه. فرض کن اون *یه چیز دیگه* اسمش "فایل-آروم" 📝 باشه. |
|||
|
|||
پس، توی اون مدت، کامپیوتر می‌تونه بره یه کار دیگه بکنه، تا وقتی "فایل-آروم" 📝 تموم بشه. |
|||
|
|||
بعدش کامپیوتر / برنامه 🤖 هر وقت فرصتی داشته باشه برمی‌گرده، چون دوباره منتظره، یا هر وقت همه کاری که اون لحظه داشته تموم کرده. و می‌بینه آیا کارایی که منتظرشون بوده تموم شدن یا نه، و هر کاری که باید بکنه رو انجام می‌ده. |
|||
|
|||
بعد، اون 🤖 اولین کاری که تموم شده (مثلاً "فایل-آروم" 📝 ما) رو برمی‌داره و هر کاری که باید باهاش بکنه رو ادامه می‌ده. |
|||
|
|||
این "منتظر یه چیز دیگه بودن" معمولاً به عملیات <abbr title="ورودی و خروجی">I/O</abbr> اشاره داره که نسبتاً "آروم" هستن (نسبت به سرعت پردازنده و حافظه RAM)، مثل منتظر موندن برای: |
|||
|
|||
* داده‌هایی که از کلاینت از طریق شبکه فرستاده می‌شن |
|||
* داده‌هایی که برنامه‌ات فرستاده تا از طریق شبکه به کلاینت برسه |
|||
* محتوای یه فایل توی دیسک که سیستم بخوندش و به برنامه‌ات بده |
|||
* محتوایی که برنامه‌ات به سیستم داده تا توی دیسک بنویسه |
|||
* یه عملیات API از راه دور |
|||
* یه عملیات دیتابیس که تموم بشه |
|||
* یه کوئری دیتابیس که نتایجش برگرده |
|||
* و غیره. |
|||
|
|||
چون زمان اجرا بیشتر صرف انتظار برای عملیات <abbr title="ورودی و خروجی">I/O</abbr> می‌شه، بهشون می‌گن عملیات "I/O bound". |
|||
|
|||
بهش "ناهم‌زمان" می‌گن چون کامپیوتر / برنامه لازم نیست با کار آروم "همزمان" باشه، منتظر لحظه دقیق تموم شدن کار بمونه، در حالی که هیچ کاری نمی‌کنه، تا نتیجه رو بگیره و کارش رو ادامه بده. |
|||
|
|||
به جاش، چون یه سیستم "ناهم‌زمان" هست، وقتی کار تموم شد، می‌تونه یه کم توی صف منتظر بمونه (چند میکروثانیه) تا کامپیوتر / برنامه هر کاری که رفته بکنه رو تموم کنه، و بعد برگرده نتیجه رو بگیره و باهاش کار کنه. |
|||
|
|||
برای "همزمان" (برخلاف "ناهم‌زمان") معمولاً از اصطلاح "ترتیبی" هم استفاده می‌کنن، چون کامپیوتر / برنامه همه مراحل رو به ترتیب دنبال می‌کنه قبل از اینکه بره سراغ یه کار دیگه، حتی اگه اون مراحل شامل انتظار باشن. |
|||
|
|||
### هم‌زمانی و برگرها |
|||
|
|||
این ایده **ناهم‌زمان** که بالا توضیح دادم گاهی بهش **"هم‌زمانی"** هم می‌گن. با **"موازی‌سازی"** فرق داره. |
|||
|
|||
**هم‌زمانی** و **موازی‌سازی** هر دو به "اتفاق افتادن چیزای مختلف کم‌وبیش همزمان" ربط دارن. |
|||
|
|||
ولی جزئیات بین *هم‌زمانی* و *موازی‌سازی* خیلی متفاوته. |
|||
|
|||
برای دیدن فرقش، این داستان در مورد برگرها رو تصور کن: |
|||
|
|||
### برگرهای همزمان |
|||
|
|||
با عشقت می‌ری فست‌فود بگیرین، توی صف وایمیستی در حالی که صندوقدار سفارش آدمای جلوی تو رو می‌گیره. 😍 |
|||
|
|||
<img src="/img/async/concurrent-burgers/concurrent-burgers-01.png" class="illustration"> |
|||
|
|||
بعد نوبت تو می‌شه، سفارش دو تا برگر خیلی شیک برای خودت و عشقت می‌دی. 🍔🍔 |
|||
|
|||
<img src="/img/async/concurrent-burgers/concurrent-burgers-02.png" class="illustration"> |
|||
|
|||
صندوقدار یه چیزی به آشپز توی آشپزخونه می‌گه تا بدونن باید برگرهای تو رو آماده کنن (گرچه الان دارن برگرهای مشتریای قبلی رو درست می‌کنن). |
|||
|
|||
<img src="/img/async/concurrent-burgers/concurrent-burgers-03.png" class="illustration"> |
|||
|
|||
پول رو می‌دی. 💸 |
|||
|
|||
صندوقدار شماره نوبتت رو بهت می‌ده. |
|||
|
|||
<img src="/img/async/concurrent-burgers/concurrent-burgers-04.png" class="illustration"> |
|||
|
|||
وقتی منتظری، با عشقت می‌ری یه میز انتخاب می‌کنی، می‌شینی و کلی با عشقت حرف می‌زنی (چون برگرهات خیلی شیکن و آماده کردنشون یه کم طول می‌کشه). |
|||
|
|||
وقتی پشت میز با عشقت نشستی، در حالی که منتظر برگرهایی، می‌تونی اون زمان رو صرف تحسین این کنی که عشقت چقدر باحال، ناز و باهوشه ✨😍✨. |
|||
|
|||
<img src="/img/async/concurrent-burgers/concurrent-burgers-05.png" class="illustration"> |
|||
|
|||
وقتی منتظری و با عشقت حرف می‌زنی، هر از گاهی شماره‌ای که رو پیشخون نشون داده می‌شه رو چک می‌کنی که ببینی نوبتت شده یا نه. |
|||
|
|||
بعد یه جایی بالاخره نوبتت می‌شه. می‌ری پیشخون، برگرهات رو می‌گیری و برمی‌گردی سر میز. |
|||
|
|||
<img src="/img/async/concurrent-burgers/concurrent-burgers-06.png" class="illustration"> |
|||
|
|||
تو و عشقت برگرها رو می‌خورین و یه وقت خوب باهم دارین. ✨ |
|||
|
|||
<img src="/img/async/concurrent-burgers/concurrent-burgers-07.png" class="illustration"> |
|||
|
|||
/// info |
|||
|
|||
تصاویر قشنگ از <a href="https://www.instagram.com/ketrinadrawsalot" class="external-link" target="_blank">کترینا تامپسون</a>. 🎨 |
|||
|
|||
/// |
|||
|
|||
--- |
|||
|
|||
تصور کن تو توی این داستان کامپیوتر / برنامه 🤖 هستی. |
|||
|
|||
وقتی توی صف هستی، فقط بیکاری 😴، منتظر نوبتت هستی، کار خیلی "مفیدی" نمی‌کنی. ولی صف سریع پیش می‌ره چون صندوقدار فقط سفارش می‌گیره (آمادشون نمی‌کنه)، پس این خوبه. |
|||
|
|||
بعد، وقتی نوبتت می‌شه، کار "مفید" واقعی می‌کنی، منو رو پردازش می‌کنی، تصمیم می‌گیری چی می‌خوای، انتخاب عشقت رو می‌گیری، پول می‌دی، چک می‌کنی اسکناس یا کارت درست رو دادی، چک می‌کنی درست حساب شده، چک می‌کنی سفارش آیتمای درست رو داره و غیره. |
|||
|
|||
ولی بعد، گرچه هنوز برگرهات رو نداری، کارت با صندوقدار "موقتاً متوقف" ⏸ می‌شه، چون باید منتظر بمونی 🕙 تا برگرهات آماده بشن. |
|||
|
|||
ولی وقتی از پیشخون دور می‌شی و با شماره نوبتت سر میز می‌شینی، می‌تونی توجهت رو 🔀 به عشقت بدی و "کار" ⏯ 🤓 رو اون بکنی. بعدش دوباره داری یه چیز خیلی "مفید" انجام می‌دی، مثل لاس زدن با عشقت 😍. |
|||
|
|||
بعد صندوقدار 💁 با گذاشتن شماره‌ات رو نمایشگر پیشخون می‌گه "من با درست کردن برگرها تموم کردم"، ولی تو مثل دیوونه‌ها وقتی شماره‌ات رو نمایشگر میاد فوری نمی‌پری. می‌دونی کسی برگرهات رو نمی‌دزده چون شماره نوبتت رو داری، و اونا هم مال خودشون رو دارن. |
|||
|
|||
پس منتظر می‌مونی تا عشقت داستانش رو تموم کنه (کار فعلی ⏯ / وظیفه‌ای که داره پردازش می‌شه 🤓)، آروم لبخند می‌زنی و می‌گی که می‌ری برگرها رو بیاری ⏸. |
|||
|
|||
بعد می‌ری پیشخون 🔀، به کار اولیه که حالا تموم شده ⏯، برگرها رو می‌گیری، تشکر می‌کنی و می‌برشون سر میز. این مرحله / وظیفه تعامل با پیشخون رو تموم می‌کنه ⏹. این به نوبه خودش یه وظیفه جدید، "خوردن برگرها" 🔀 ⏯، می‌سازه، ولی اون قبلی که "گرفتن برگرها" بود تموم شده ⏹. |
|||
|
|||
### برگرهای موازی |
|||
|
|||
حالا فرض کن اینا "برگرهای همزمان" نیستن، بلکه "برگرهای موازی" هستن. |
|||
|
|||
با عشقت می‌ری فست‌فود موازی بگیری. |
|||
|
|||
توی صف وایمیستی در حالی که چند تا (مثلاً 8 تا) صندوقدار که همزمان آشپز هم هستن سفارش آدمای جلوی تو رو می‌گیرن. |
|||
|
|||
همه قبل تو منتظرن برگرهاشون آماده بشه قبل از اینکه پیشخون رو ترک کنن، چون هر کدوم از 8 تا صندوقدار می‌ره و برگر رو همون موقع درست می‌کنه قبل از اینکه سفارش بعدی رو بگیره. |
|||
|
|||
<img src="/img/async/parallel-burgers/parallel-burgers-01.png" class="illustration"> |
|||
|
|||
بالاخره نوبت تو می‌شه، سفارش دو تا برگر خیلی شیک برای خودت و عشقت می‌دی. |
|||
|
|||
پول رو می‌دی 💸. |
|||
|
|||
<img src="/img/async/parallel-burgers/parallel-burgers-02.png" class="illustration"> |
|||
|
|||
صندوقدار می‌ره آشپزخونه. |
|||
|
|||
منتظر می‌مونی، جلوی پیشخون وایستادی 🕙، که کسی قبل از تو برگرهات رو نگیره، چون شماره نوبت نیست. |
|||
|
|||
<img src="/img/async/parallel-burgers/parallel-burgers-03.png" class="illustration"> |
|||
|
|||
چون تو و عشقت مشغول این هستین که نذارین کسی جلوتون بیاد و هر وقت برگرها رسیدن اونا رو بگیره، نمی‌تونی به عشقت توجه کنی. 😞 |
|||
|
|||
این کار "همزمان" هست، تو با صندوقدار/آشپز 👨🍳 "همزمان" هستی. باید منتظر بمونی 🕙 و درست همون لحظه که صندوقدار/آشپز 👨🍳 برگرها رو تموم می‌کنه و بهت می‌ده اونجا باشی، وگرنه ممکنه یکی دیگه اونا رو بگیره. |
|||
|
|||
<img src="/img/async/parallel-burgers/parallel-burgers-04.png" class="illustration"> |
|||
|
|||
بعد صندوقدار/آشپزت 👨🍳 بالاخره بعد از یه مدت طولانی انتظار 🕙 جلوی پیشخون با برگرهات برمی‌گرده. |
|||
|
|||
<img src="/img/async/parallel-burgers/parallel-burgers-05.png" class="illustration"> |
|||
|
|||
برگرهات رو می‌گیری و با عشقت می‌ری سر میز. |
|||
|
|||
فقط می‌خورینشون، و تمومه. ⏹ |
|||
|
|||
<img src="/img/async/parallel-burgers/parallel-burgers-06.png" class="illustration"> |
|||
|
|||
حرف زدن یا لاس زدن زیاد نبود چون بیشتر وقت صرف انتظار 🕙 جلوی پیشخون شد. 😞 |
|||
|
|||
/// info |
|||
|
|||
تصاویر قشنگ از <a href="https://www.instagram.com/ketrinadrawsalot" class="external-link" target="_blank">کترینا تامپسون</a>. 🎨 |
|||
|
|||
/// |
|||
|
|||
--- |
|||
|
|||
توی این سناریوی برگرهای موازی، تو یه کامپیوتر / برنامه 🤖 با دو تا پردازنده (تو و عشقت) هستی، هر دو منتظر 🕙 و توجهشون ⏯ رو برای مدت طولانی "انتظار جلوی پیشخون" 🕙 گذاشتن. |
|||
|
|||
فست‌فود 8 تا پردازنده (صندوقدار/آشپز) داره. در حالی که فست‌فود برگرهای همزمان شاید فقط 2 تا داشته (یه صندوقدار و یه آشپز). |
|||
|
|||
ولی با این حال، تجربه نهایی بهترین نیست. 😞 |
|||
|
|||
--- |
|||
|
|||
این معادل موازی داستان برگرها بود. 🍔 |
|||
|
|||
برای یه مثال "واقعی‌تر" از زندگی، یه بانک رو تصور کن. |
|||
|
|||
تا همین چند وقت پیش، بیشتر بانک‌ها چند تا صندوقدار 👨💼👨💼👨💼👨💼 داشتن و یه صف بزرگ 🕙🕙🕙🕙🕙🕙🕙🕙. |
|||
|
|||
همه صندوقدارها کار رو با یه مشتری بعد از اون یکی 👨💼⏯ انجام می‌دادن. |
|||
|
|||
و باید توی صف 🕙 مدت زیادی منتظر بمونی وگرنه نوبتت رو از دست می‌دی. |
|||
|
|||
احتمالاً نمی‌خوای عشقت 😍 رو با خودت ببری بانک 🏦 برای کارای روزمره. |
|||
|
|||
### نتیجه‌گیری برگرها |
|||
|
|||
توی این سناریوی "برگرهای فست‌فود با عشقت"، چون کلی انتظار 🕙 هست، خیلی منطقی‌تره که یه سیستم همزمان ⏸🔀⏯ داشته باشی. |
|||
|
|||
این برای بیشتر برنامه‌های وب هم صدق می‌کنه. |
|||
|
|||
خیلی خیلی کاربر، ولی سرورت منتظر 🕙 اتصال نه‌چندان خوبشون هست تا درخواست‌هاشون رو بفرستن. |
|||
|
|||
و بعد دوباره منتظر 🕙 که جواب‌ها برگردن. |
|||
|
|||
این "انتظار" 🕙 توی میکروثانیه‌ها اندازه‌گیری می‌شه، ولی با این حال، جمعش که بکنی آخرش کلی انتظار می‌شه. |
|||
|
|||
برای همین استفاده از کد ناهم‌زمان ⏸🔀⏯ برای APIهای وب خیلی منطقیه. |
|||
|
|||
این نوع ناهم‌زمانی چیزیه که NodeJS رو محبوب کرد (گرچه NodeJS موازی نیست) و نقطه قوت Go به‌عنوان یه زبون برنامه‌نویسیه. |
|||
|
|||
و همون سطح عملکردی هست که با **FastAPI** می‌گیری. |
|||
|
|||
و چون می‌تونی هم‌زمانی و موازی‌سازی رو همزمان داشته باشی، عملکرد بالاتری از بیشتر فریم‌ورک‌های تست‌شده NodeJS می‌گیری و هم‌تراز با Go، که یه زبون کامپایل‌شده نزدیک به C هست <a href="https://www.techempower.com/benchmarks/#section=data-r17&hw=ph&test=query&l=zijmkf-1" class="external-link" target="_blank">(همه اینا به لطف Starlette)</a>. |
|||
|
|||
### آیا هم‌زمانی از موازی‌سازی بهتره؟ |
|||
|
|||
نه! این نتیجه داستان نیست. |
|||
|
|||
هم‌زمانی با موازی‌سازی فرق داره. و توی **سناریوهای خاص** که کلی انتظار دارن بهتره. به همین خاطر، معمولاً برای توسعه برنامه‌های وب خیلی از موازی‌سازی بهتره. ولی نه برای همه‌چیز. |
|||
|
|||
برای اینکه یه تعادل بذاریم، این داستان کوتاه رو تصور کن: |
|||
|
|||
> باید یه خونه بزرگ و کثیف رو تمیز کنی. |
|||
|
|||
*آره، کل داستان همینه*. |
|||
|
|||
--- |
|||
|
|||
هیچ انتظاری 🕙 اونجا نیست، فقط کلی کار برای انجام دادن توی جاهای مختلف خونه. |
|||
|
|||
می‌تونی مثل مثال برگرها نوبت بذاری، اول پذیرایی، بعد آشپزخونه، ولی چون منتظر چیزی نیستی 🕙، فقط داری تمیز می‌کنی و تمیز می‌کنی، نوبت‌ها هیچ تأثیری نداره. |
|||
|
|||
با نوبت یا بدون نوبت (هم‌زمانی) همون قدر طول می‌کشه تا تمومش کنی و همون مقدار کار رو کردی. |
|||
|
|||
ولی توی این موقعیت، اگه بتونی اون 8 تا صندوقدار/آشپز/حالا-تمیزکار رو بیاری، و هر کدومشون (به‌علاوه خودت) یه قسمت از خونه رو تمیز کنن، می‌تونی همه کار رو **موازی** انجام بدی، با کمک اضافی، و خیلی زودتر تمومش کنی. |
|||
|
|||
توی این سناریو، هر کدوم از تمیزکارها (از جمله خودت) یه پردازنده‌ست که کار خودش رو می‌کنه. |
|||
|
|||
و چون بیشتر زمان اجرا صرف کار واقعی می‌شه (به جای انتظار)، و کار توی کامپیوتر با <abbr title="واحد پردازش مرکزی">CPU</abbr> انجام می‌شه، به این مشکلات می‌گن "CPU bound". |
|||
|
|||
--- |
|||
|
|||
مثال‌های رایج عملیات CPU bound چیزایی هستن که نیاز به پردازش ریاضی پیچیده دارن. |
|||
|
|||
مثلاً: |
|||
|
|||
* پردازش **صدا** یا **تصویر**. |
|||
* **بینایی کامپیوتری**: یه تصویر از میلیون‌ها پیکسل تشکیل شده، هر پیکسل 3 تا مقدار / رنگ داره، پردازشش معمولاً نیاز داره چیزی رو رو اون پیکسل‌ها همزمان حساب کنی. |
|||
* **یادگیری ماشین**: معمولاً کلی ضرب "ماتریس" و "بردار" لازم داره. یه جدول بزرگ پر از عدد رو تصور کن که همه‌شون رو همزمان ضرب می‌کنی. |
|||
* **یادگیری عمیق**: این یه زیرشاخه از یادگیری ماشینه، پس همون قضیه صدق می‌کنه. فقط این که یه جدول عدد برای ضرب کردن نیست، بلکه یه مجموعه بزرگ از اونا هست، و توی خیلی موارد از یه پردازنده خاص برای ساخت و / یا استفاده از این مدل‌ها استفاده می‌کنی. |
|||
|
|||
### هم‌زمانی + موازی‌سازی: وب + یادگیری ماشین |
|||
|
|||
با **FastAPI** می‌تونی از هم‌زمانی که برای توسعه وب خیلی رایجه (همون جذابیت اصلی NodeJS) استفاده کنی. |
|||
|
|||
ولی می‌تونی از فواید موازی‌سازی و چندپردازشی (اجرای چند پروسه به‌صورت موازی) برای کارای **CPU bound** مثل سیستم‌های یادگیری ماشین هم بهره ببری. |
|||
|
|||
این، به‌علاوه این واقعیت ساده که پایتون زبون اصلی برای **علم داده**، یادگیری ماشین و به‌خصوص یادگیری عمیقه، باعث می‌شه FastAPI یه انتخاب خیلی خوب برای APIها و برنامه‌های وب علم داده / یادگیری ماشین باشه (بین خیلی چیزای دیگه). |
|||
|
|||
برای دیدن اینکه چطور توی محیط واقعی به این موازی‌سازی برسی، بخش [استقرار](deployment/index.md){.internal-link target=_blank} رو ببین. |
|||
|
|||
## `async` و `await` |
|||
|
|||
نسخه‌های مدرن پایتون یه راه خیلی ساده و قابل‌فهم برای تعریف کد ناهم‌زمان دارن. این باعث می‌شه مثل کد "ترتیبی" معمولی به نظر بیاد و توی لحظه‌های درست "انتظار" رو برات انجام بده. |
|||
|
|||
وقتی یه عملیاتی هست که قبل از دادن نتیجه‌ها نیاز به انتظار داره و از این قابلیت‌های جدید پایتون پشتیبانی می‌کنه، می‌تونی اینجوری کدنویسیش کنی: |
|||
|
|||
```Python |
|||
burgers = await get_burgers(2) |
|||
``` |
|||
|
|||
نکته کلیدی اینجا `await` هست. به پایتون می‌گه که باید ⏸ منتظر بمونه تا `get_burgers(2)` کارش 🕙 تموم بشه قبل از اینکه نتیجه‌ها رو توی `burgers` ذخیره کنه. با این، پایتون می‌دونه که می‌تونه بره یه کار دیگه 🔀 ⏯ توی این مدت بکنه (مثل گرفتن یه درخواست دیگه). |
|||
|
|||
برای اینکه `await` کار کنه، باید توی یه تابع باشه که از این ناهم‌زمانی پشتیبانی کنه. برای این کار، فقط با `async def` تعریفش می‌کنی: |
|||
|
|||
```Python hl_lines="1" |
|||
async def get_burgers(number: int): |
|||
# یه سری کار ناهم‌زمان برای ساختن برگرها انجام بده |
|||
return burgers |
|||
``` |
|||
|
|||
...به جای `def`: |
|||
|
|||
```Python hl_lines="2" |
|||
# این ناهم‌زمان نیست |
|||
def get_sequential_burgers(number: int): |
|||
# یه سری کار ترتیبی برای ساختن برگرها انجام بده |
|||
return burgers |
|||
``` |
|||
|
|||
با `async def`، پایتون می‌دونه که توی اون تابع باید حواسش به عبارت‌های `await` باشه، و می‌تونه اجرای اون تابع رو "موقتاً متوقف" ⏸ کنه و بره یه کار دیگه 🔀 قبل از برگشتن بکنه. |
|||
|
|||
وقتی می‌خوای یه تابع `async def` رو صدا کنی، باید "منتظرش" بمونی. پس این کار نمی‌کنه: |
|||
|
|||
```Python |
|||
# این کار نمی‌کنه، چون get_burgers با async def تعریف شده |
|||
burgers = get_burgers(2) |
|||
``` |
|||
|
|||
--- |
|||
|
|||
پس، اگه از یه کتابخونه استفاده می‌کنی که بهت می‌گه می‌تونی با `await` صداش کنی، باید *توابع عملیات مسیرت* که ازش استفاده می‌کنن رو با `async def` بسازی، مثل: |
|||
|
|||
```Python hl_lines="2-3" |
|||
@app.get('/burgers') |
|||
async def read_burgers(): |
|||
burgers = await get_burgers(2) |
|||
return burgers |
|||
``` |
|||
|
|||
### جزئیات فنی‌تر |
|||
|
|||
شاید متوجه شده باشی که `await` فقط توی توابعی که با `async def` تعریف شدن می‌تونه استفاده بشه. |
|||
|
|||
ولی در عین حال، توابعی که با `async def` تعریف شدن باید "منتظر"شون بمونی. پس توابع با `async def` فقط توی توابعی که با `async def` تعریف شدن می‌تونن صدا زده بشن. |
|||
|
|||
حالا، قضیه مرغ و تخم‌مرغ چیه، چطور اولین تابع `async` رو صدا می‌کنی؟ |
|||
|
|||
اگه با **FastAPI** کار می‌کنی، لازم نیست نگران این باشی، چون اون "اولین" تابع، *تابع عملیات مسیرت* هست، و FastAPI می‌دونه چطور کار درست رو بکنه. |
|||
|
|||
ولی اگه بخوای بدون FastAPI از `async` / `await` استفاده کنی، اینم ممکنه. |
|||
|
|||
### کد ناهم‌زمان خودت رو بنویس |
|||
|
|||
Starlette (و **FastAPI**) بر پایه <a href="https://anyio.readthedocs.io/en/stable/" class="external-link" target="_blank">AnyIO</a> هستن، که باعث می‌شه با کتابخونه استاندارد پایتون <a href="https://docs.python.org/3/library/asyncio-task.html" class="external-link" target="_blank">asyncio</a> و <a href="https://trio.readthedocs.io/en/stable/" class="external-link" target="_blank">Trio</a> سازگار باشه. |
|||
|
|||
به‌خصوص، می‌تونی مستقیماً از <a href="https://anyio.readthedocs.io/en/stable/" class="external-link" target="_blank">AnyIO</a> برای موارد استفاده پیشرفته هم‌زمانی که نیاز به الگوهای پیچیده‌تر توی کد خودت دارن استفاده کنی. |
|||
|
|||
و حتی اگه از FastAPI استفاده نکنی، می‌تونی برنامه‌های ناهم‌زمان خودت رو با <a href="https://anyio.readthedocs.io/en/stable/" class="external-link" target="_blank">AnyIO</a> بنویسی تا خیلی سازگار باشه و فوایدش رو بگیری (مثل *هم‌زمانی ساختاریافته*). |
|||
|
|||
من یه کتابخونه دیگه روی AnyIO ساختم، یه لایه نازک روش، تا یه کم annotationهای نوع رو بهتر کنم و **تکمیل خودکار** بهتر، **خطاهای درون‌خطی** و غیره بگیرم. یه مقدمه و آموزش ساده هم داره که بهت کمک می‌کنه **بفهمی** و **کد ناهم‌زمان خودت رو بنویسی**: <a href="https://asyncer.tiangolo.com/" class="external-link" target="_blank">Asyncer</a>. اگه بخوای **کد ناهم‌زمان رو با کد معمولی** (بلاک‌کننده/همزمان) ترکیب کنی خیلی به‌دردت می‌خوره. |
|||
|
|||
### شکل‌های دیگه کد ناهم‌زمان |
|||
|
|||
این سبک استفاده از `async` و `await` توی زبون نسبتاً جدیده. |
|||
|
|||
ولی کار با کد ناهم‌زمان رو خیلی ساده‌تر می‌کنه. |
|||
|
|||
همین سینتکس (یا تقریباً یکسان) اخیراً توی نسخه‌های مدرن جاوااسکریپت (توی مرورگر و NodeJS) هم اضافه شده. |
|||
|
|||
ولی قبل از اون، مدیریت کد ناهم‌زمان خیلی پیچیده‌تر و سخت‌تر بود. |
|||
|
|||
توی نسخه‌های قبلی پایتون، می‌تونستی از نخ‌ها یا <a href="https://www.gevent.org/" class="external-link" target="_blank">Gevent</a> استفاده کنی. ولی کد خیلی پیچیده‌تر می‌شه برای فهمیدن، دیباگ کردن و فکر کردن بهش. |
|||
|
|||
توی نسخه‌های قبلی NodeJS / جاوااسکریپت مرورگر، از "کال‌بک‌ها" استفاده می‌کردی. که می‌رسید به <a href="http://callbackhell.com/" class="external-link" target="_blank">جهان کال‌بک‌ها</a>. |
|||
|
|||
## کروتین‌ها |
|||
|
|||
**کروتین** فقط یه اصطلاح خیلی شیک برای چیزیه که یه تابع `async def` برمی‌گردونه. پایتون می‌دونه که این یه چیزی مثل تابع هست، می‌تونه شروع بشه و یه جایی تموم بشه، ولی ممکنه داخلش هم موقف ⏸ بشه، هر وقت یه `await` توش باشه. |
|||
|
|||
ولی همه این قابلیت استفاده از کد ناهم‌زمان با `async` و `await` خیلی وقتا خلاصه می‌شه به استفاده از "کروتین‌ها". این قابل مقایسه با ویژگی اصلی Go، یعنی "Goroutineها" هست. |
|||
|
|||
## نتیجه‌گیری |
|||
|
|||
بیاید همون جمله از بالا رو ببینیم: |
|||
|
|||
> نسخه‌های مدرن پایتون از **"کد ناهم‌زمان"** با چیزی که بهش **"کروتین"** می‌گن پشتیبانی می‌کنن، با سینتکس **`async` و `await`**. |
|||
|
|||
حالا باید بیشتر برات معنی بده. ✨ |
|||
|
|||
همه اینا چیزیه که به FastAPI (از طریق Starlette) قدرت می‌ده و باعث می‌شه عملکرد چشمگیری داشته باشه. |
|||
|
|||
## جزئیات خیلی فنی |
|||
|
|||
/// warning |
|||
|
|||
احتمالاً می‌تونی اینو رد کنی. |
|||
|
|||
اینا جزئیات خیلی فنی از نحوه کار **FastAPI** زیر پوسته‌ست. |
|||
|
|||
اگه یه کم دانش فنی (کروتین‌ها، نخ‌ها، بلاک کردن و غیره) داری و کنجکاوی که FastAPI چطور `async def` رو در مقابل `def` معمولی مدیریت می‌کنه، ادامه بده. |
|||
|
|||
/// |
|||
|
|||
### توابع عملیات مسیر |
|||
|
|||
وقتی یه *تابع عملیات مسیر* رو با `def` معمولی به جای `async def` تعریف می‌کنی، توی یه استخر نخ خارجی اجرا می‌شه که بعدش منتظرش می‌مونن، به جای اینکه مستقیم صداش کنن (چون سرور رو بلاک می‌کنه). |
|||
|
|||
اگه از یه فریم‌ورک ناهم‌زمان دیگه میای که به روش بالا کار نمی‌کنه و عادت داری *توابع عملیات مسیر* ساده فقط محاسباتی رو با `def` معمولی برای یه سود کوچیک عملکرد (حدود 100 نانوثانیه) تعریف کنی، توجه کن که توی **FastAPI** اثرش کاملاً برعکسه. توی این موارد، بهتره از `async def` استفاده کنی مگه اینکه *توابع عملیات مسیرت* کدی داشته باشن که عملیات <abbr title="ورودی/خروجی: خوندن یا نوشتن دیسک، ارتباطات شبکه">I/O</abbr> بلاک‌کننده انجام بده. |
|||
|
|||
با این حال، توی هر دو موقعیت، احتمالش زیاده که **FastAPI** هنوز [سریع‌تر](index.md#performance){.internal-link target=_blank} از فریم‌ورک قبلی‌ات باشه (یا حداقل قابل مقایسه باهاش). |
|||
|
|||
### وابستگی‌ها |
|||
|
|||
همین برای [وابستگی‌ها](tutorial/dependencies/index.md){.internal-link target=_blank} هم صدق می‌کنه. اگه یه وابستگی یه تابع `def` معمولی به جای `async def` باشه، توی استخر نخ خارجی اجرا می‌شه. |
|||
|
|||
### زیروابستگی‌ها |
|||
|
|||
می‌تونی چند تا وابستگی و [زیروابستگی](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} داشته باشی که همدیگه رو نیاز دارن (به‌عنوان پارامترهای تعریف تابع)، بعضی‌هاشون ممکنه با `async def` ساخته بشن و بعضی‌ها با `def` معمولی. بازم کار می‌کنه، و اونایی که با `def` معمولی ساخته شدن توی یه نخ خارجی (از استخر نخ) صدا زده می‌شن به جای اینکه "منتظرشون" بمونن. |
|||
|
|||
### توابع کاربردی دیگه |
|||
|
|||
هر تابع کاربردی دیگه‌ای که مستقیم خودت صداش می‌کنی می‌تونه با `def` معمولی یا `async def` ساخته بشه و FastAPI رو نحوه صدازدنش تأثیر نمی‌ذاره. |
|||
|
|||
این برخلاف توابعی هست که FastAPI برات صداشون می‌کنه: *توابع عملیات مسیر* و وابستگی‌ها. |
|||
|
|||
اگه تابع کاربردیت یه تابع معمولی با `def` باشه، مستقیم صداش می‌کنن (همون‌طور که توی کدت نوشتی)، نه توی استخر نخ، اگه تابع با `async def` ساخته شده باشه، باید وقتی توی کدت صداش می‌کنی `await`ش کنی. |
|||
|
|||
--- |
|||
|
|||
دوباره، اینا جزئیات خیلی فنی هستن که احتمالاً اگه دنبالشون اومده باشی برات مفید باشن. |
|||
|
|||
وگرنه، با راهنمایی‌های بخش بالا باید خوب باشی: <a href="#in-a-hurry">عجله داری؟</a>. |
|||
@ -0,0 +1,298 @@ |
|||
# متغیرهای محیطی |
|||
|
|||
/// tip |
|||
|
|||
اگه از قبل می‌دونی متغیرهای محیطی چی هستن و چطور ازشون استفاده می‌شه، می‌تونی این بخش رو رد کنی. |
|||
|
|||
/// |
|||
|
|||
یه متغیر محیطی (که بهش "**env var**" هم می‌گن) یه متغیریه که **خارج** از کد پایتون، توی **سیستم‌عامل** زندگی می‌کنه و می‌تونه توسط کد پایتونت (یا برنامه‌های دیگه) خونده بشه. |
|||
|
|||
متغیرهای محیطی می‌تونن برای مدیریت **تنظیمات** برنامه، به‌عنوان بخشی از **نصب** پایتون و غیره مفید باشن. |
|||
|
|||
## ساخت و استفاده از متغیرهای محیطی |
|||
|
|||
می‌تونی متغیرهای محیطی رو توی **شل (ترمینال)** **بسازی** و ازشون استفاده کنی، بدون اینکه به پایتون نیاز داشته باشی: |
|||
|
|||
//// tab | لینوکس، مک‌اواس، ویندوز بش |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
// می‌تونی یه متغیر محیطی به اسم MY_NAME بسازی با |
|||
$ export MY_NAME="Wade Wilson" |
|||
|
|||
// بعد می‌تونی با برنامه‌های دیگه ازش استفاده کنی، مثل |
|||
$ echo "Hello $MY_NAME" |
|||
|
|||
Hello Wade Wilson |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
//// |
|||
|
|||
//// tab | ویندوز پاورشل |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
// یه متغیر محیطی به اسم MY_NAME بساز |
|||
$ $Env:MY_NAME = "Wade Wilson" |
|||
|
|||
// با برنامه‌های دیگه ازش استفاده کن، مثل |
|||
$ echo "Hello $Env:MY_NAME" |
|||
|
|||
Hello Wade Wilson |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
//// |
|||
|
|||
## خوندن متغیرهای محیطی توی پایتون |
|||
|
|||
می‌تونی متغیرهای محیطی رو **خارج** از پایتون، توی ترمینال (یا با هر روش دیگه) بسازی، و بعد توی **پایتون** اونا رو بخونی. |
|||
|
|||
مثلاً می‌تونی یه فایل `main.py` داشته باشی با: |
|||
|
|||
```Python hl_lines="3" |
|||
import os |
|||
|
|||
name = os.getenv("MY_NAME", "World") |
|||
print(f"Hello {name} from Python") |
|||
``` |
|||
|
|||
/// tip |
|||
|
|||
آرگومان دوم <a href="https://docs.python.org/3.8/library/os.html#os.getenv" class="external-link" target="_blank">`os.getenv()`</a> مقدار پیش‌فرضیه که برمی‌گردونه. |
|||
|
|||
اگه ندی، به‌صورت پیش‌فرض `None` هست، اینجا ما `"World"` رو به‌عنوان مقدار پیش‌فرض گذاشتیم. |
|||
|
|||
/// |
|||
|
|||
بعد می‌تونی اون برنامه پایتون رو صدا کنی: |
|||
|
|||
//// tab | لینوکس، مک‌اواس، ویندوز بش |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
// اینجا هنوز متغیر محیطی رو تنظیم نکردیم |
|||
$ python main.py |
|||
|
|||
// چون متغیر محیطی رو تنظیم نکردیم، مقدار پیش‌فرض رو می‌گیریم |
|||
|
|||
Hello World from Python |
|||
|
|||
// ولی اگه اول یه متغیر محیطی بسازیم |
|||
$ export MY_NAME="Wade Wilson" |
|||
|
|||
// و بعد دوباره برنامه رو صدا کنیم |
|||
$ python main.py |
|||
|
|||
// حالا می‌تونه متغیر محیطی رو بخونه |
|||
|
|||
Hello Wade Wilson from Python |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
//// |
|||
|
|||
//// tab | ویندوز پاورشل |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
// اینجا هنوز متغیر محیطی رو تنظیم نکردیم |
|||
$ python main.py |
|||
|
|||
// چون متغیر محیطی رو تنظیم نکردیم، مقدار پیش‌فرض رو می‌گیریم |
|||
|
|||
Hello World from Python |
|||
|
|||
// ولی اگه اول یه متغیر محیطی بسازیم |
|||
$ $Env:MY_NAME = "Wade Wilson" |
|||
|
|||
// و بعد دوباره برنامه رو صدا کنیم |
|||
$ python main.py |
|||
|
|||
// حالا می‌تونه متغیر محیطی رو بخونه |
|||
|
|||
Hello Wade Wilson from Python |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
//// |
|||
|
|||
چون متغیرهای محیطی می‌تونن خارج از کد تنظیم بشن، ولی کد می‌تونه اونا رو بخونه، و لازم نیست با بقیه فایل‌ها ذخیره (کمیتی به `git`) بشن، معمولاً برای پیکربندی یا **تنظیمات** استفاده می‌شن. |
|||
|
|||
همچنین می‌تونی یه متغیر محیطی رو فقط برای **یه اجرای خاص برنامه** بسازی، که فقط برای اون برنامه و فقط برای مدت زمان اجراش در دسترسه. |
|||
|
|||
برای این کار، درست قبل از خود برنامه، توی همون خط بسازش: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
// یه متغیر محیطی MY_NAME رو توی خط برای این اجرای برنامه بساز |
|||
$ MY_NAME="Wade Wilson" python main.py |
|||
|
|||
// حالا می‌تونه متغیر محیطی رو بخونه |
|||
|
|||
Hello Wade Wilson from Python |
|||
|
|||
// متغیر محیطی بعدش دیگه وجود نداره |
|||
$ python main.py |
|||
|
|||
Hello World from Python |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
/// tip |
|||
|
|||
می‌تونی بیشتر در موردش توی <a href="https://12factor.net/config" class="external-link" target="_blank">برنامه دوازده‌فاکتوری: پیکربندی</a> بخونی. |
|||
|
|||
/// |
|||
|
|||
## نوع‌ها و اعتبارسنجی |
|||
|
|||
این متغیرهای محیطی فقط می‌تونن **رشته‌های متنی** رو نگه دارن، چون خارج از پایتون هستن و باید با برنامه‌های دیگه و بقیه سیستم (و حتی سیستم‌عامل‌های مختلف مثل لینوکس، ویندوز، مک‌اواس) سازگار باشن. |
|||
|
|||
یعنی **هر مقداری** که توی پایتون از یه متغیر محیطی خونده می‌شه یه `str` هست، و هر تبدیل به نوع دیگه یا هر اعتبارسنجی باید توی کد انجام بشه. |
|||
|
|||
توی [راهنمای کاربر پیشرفته - تنظیمات و متغیرهای محیطی](./advanced/settings.md){.internal-link target=_blank} بیشتر در مورد استفاده از متغیرهای محیطی برای مدیریت **تنظیمات برنامه** یاد می‌گیری. |
|||
|
|||
## متغیر محیطی `PATH` |
|||
|
|||
یه متغیر محیطی **خاص** به اسم **`PATH`** وجود داره که سیستم‌عامل‌ها (لینوکس، مک‌اواس، ویندوز) ازش برای پیدا کردن برنامه‌هایی که قراره اجرا بشن استفاده می‌کنن. |
|||
|
|||
مقدار متغیر `PATH` یه رشته طولانی از پوشه‌هاست که توی لینوکس و مک‌اواس با دونقطه `:` و توی ویندوز با نقطه‌ویرگول `;` از هم جدا شدن. |
|||
|
|||
مثلاً، متغیر محیطی `PATH` می‌تونه اینجوری باشه: |
|||
|
|||
//// tab | لینوکس، مک‌اواس |
|||
|
|||
```plaintext |
|||
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin |
|||
``` |
|||
|
|||
یعنی سیستم باید دنبال برنامه‌ها توی این پوشه‌ها بگرده: |
|||
|
|||
* `/usr/local/bin` |
|||
* `/usr/bin` |
|||
* `/bin` |
|||
* `/usr/sbin` |
|||
* `/sbin` |
|||
|
|||
//// |
|||
|
|||
//// tab | ویندوز |
|||
|
|||
```plaintext |
|||
C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 |
|||
``` |
|||
|
|||
یعنی سیستم باید دنبال برنامه‌ها توی این پوشه‌ها بگرده: |
|||
|
|||
* `C:\Program Files\Python312\Scripts` |
|||
* `C:\Program Files\Python312` |
|||
* `C:\Windows\System32` |
|||
|
|||
//// |
|||
|
|||
وقتی یه **دستور** توی ترمینال تایپ می‌کنی، سیستم‌عامل **دنبال** برنامه توی **هر کدوم از این پوشه‌ها** که توی متغیر محیطی `PATH` لیست شدن می‌گرده. |
|||
|
|||
مثلاً، وقتی توی ترمینال `python` تایپ می‌کنی، سیستم‌عامل دنبال یه برنامه به اسم `python` توی **اولین پوشه** توی اون لیست می‌گرده. |
|||
|
|||
اگه پیداش کنه، **استفاده‌ش می‌کنه**. وگرنه توی **پوشه‌های بعدی** دنبالش می‌گرده. |
|||
|
|||
### نصب پایتون و به‌روزرسانی `PATH` |
|||
|
|||
وقتی پایتون رو نصب می‌کنی، ممکنه ازت بپرسن آیا می‌خوای متغیر محیطی `PATH` رو به‌روزرسانی کنی. |
|||
|
|||
//// tab | لینوکس، مک‌اواس |
|||
|
|||
فرض کن پایتون رو نصب کردی و توی یه پوشه `/opt/custompython/bin` قرار گرفته. |
|||
|
|||
اگه بگی بله برای به‌روزرسانی متغیر محیطی `PATH`، نصاب `/opt/custompython/bin` رو به متغیر محیطی `PATH` اضافه می‌کنه. |
|||
|
|||
ممکنه اینجوری بشه: |
|||
|
|||
```plaintext |
|||
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin |
|||
``` |
|||
|
|||
اینجوری، وقتی توی ترمینال `python` تایپ می‌کنی، سیستم برنامه پایتون رو توی `/opt/custompython/bin` (آخرین پوشه) پیدا می‌کنه و از اون استفاده می‌کنه. |
|||
|
|||
//// |
|||
|
|||
//// tab | ویندوز |
|||
|
|||
فرض کن پایتون رو نصب کردی و توی یه پوشه `C:\opt\custompython\bin` قرار گرفته. |
|||
|
|||
اگه بگی بله برای به‌روزرسانی متغیر محیطی `PATH`، نصاب `C:\opt\custompython\bin` رو به متغیر محیطی `PATH` اضافه می‌کنه. |
|||
|
|||
```plaintext |
|||
C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin |
|||
``` |
|||
|
|||
اینجوری، وقتی توی ترمینال `python` تایپ می‌کنی، سیستم برنامه پایتون رو توی `C:\opt\custompython\bin` (آخرین پوشه) پیدا می‌کنه و از اون استفاده می‌کنه. |
|||
|
|||
//// |
|||
|
|||
پس، اگه تایپ کنی: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ python |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
//// tab | لینوکس، مک‌اواس |
|||
|
|||
سیستم برنامه `python` رو توی `/opt/custompython/bin` **پیدا** می‌کنه و اجراش می‌کنه. |
|||
|
|||
تقریباً معادل اینه که تایپ کنی: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ /opt/custompython/bin/python |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
//// |
|||
|
|||
//// tab | ویندوز |
|||
|
|||
سیستم برنامه `python` رو توی `C:\opt\custompython\bin\python` **پیدا** می‌کنه و اجراش می‌کنه. |
|||
|
|||
تقریباً معادل اینه که تایپ کنی: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ C:\opt\custompython\bin\python |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
//// |
|||
|
|||
این اطلاعات وقتی در مورد [محیط‌های مجازی](virtual-environments.md){.internal-link target=_blank} یاد می‌گیری به‌دردت می‌خوره. |
|||
|
|||
## نتیجه‌گیری |
|||
|
|||
با این باید یه درک پایه‌ای از **متغیرهای محیطی** و نحوه استفاده‌شون توی پایتون داشته باشی. |
|||
|
|||
می‌تونی بیشتر در موردشون توی <a href="https://en.wikipedia.org/wiki/Environment_variable" class="external-link" target="_blank">ویکی‌پدیا برای متغیر محیطی</a> بخونی. |
|||
|
|||
توی خیلی موارد مشخص نیست که متغیرهای محیطی چطور می‌تونن فوری مفید و کاربردی باشن. ولی توی موقعیت‌های مختلف توسعه مدام پیداشون می‌شه، پس خوبه که در موردشون بدونی. |
|||
|
|||
مثلاً، توی بخش بعدی در مورد [محیط‌های مجازی](virtual-environments.md) به این اطلاعات نیاز داری. |
|||
@ -0,0 +1,578 @@ |
|||
# مقدمه‌ای بر انواع نوع در پایتون |
|||
|
|||
پایتون از "نوع‌نما"های اختیاری (که بهشون "type hints" یا "type annotations" هم می‌گن) پشتیبانی می‌کنه. |
|||
|
|||
این **"نوع‌نماها"** یا annotationها یه سینتکس خاص هستن که بهت اجازه می‌دن <abbr title="مثلاً: str, int, float, bool">نوع</abbr> یه متغیر رو مشخص کنی. |
|||
|
|||
با مشخص کردن نوع متغیرها، ویرایشگرها و ابزارها می‌تونن پشتیبانی بهتری بهت بدن. |
|||
|
|||
این فقط یه **آموزش سریع / یادآوری** در مورد نوع‌نماهای پایتونه. فقط حداقل چیزایی که برای استفاده ازشون با **FastAPI** لازمه رو پوشش می‌ده... که در واقع خیلی کمه. |
|||
|
|||
**FastAPI** کاملاً بر پایه این نوع‌نماهاست و این بهش کلی مزیت و فایده می‌ده. |
|||
|
|||
ولی حتی اگه هیچ‌وقت از **FastAPI** استفاده نکنی، بازم یادگیری یه کم در موردشون به نفعته. |
|||
|
|||
/// note |
|||
|
|||
اگه حرفه‌ای پایتونی و همه‌چیز رو در مورد نوع‌نماها می‌دونی، برو سراغ فصل بعدی. |
|||
|
|||
/// |
|||
|
|||
## انگیزه |
|||
|
|||
بیاید با یه مثال ساده شروع کنیم: |
|||
|
|||
{* ../../docs_src/python_types/tutorial001.py *} |
|||
|
|||
وقتی این برنامه رو اجرا کنی، خروجی اینه: |
|||
|
|||
``` |
|||
John Doe |
|||
``` |
|||
|
|||
این تابع این کارا رو می‌کنه: |
|||
|
|||
* یه `first_name` و `last_name` می‌گیره. |
|||
* حرف اول هر کدوم رو با `title()` بزرگ می‌کنه. |
|||
* <abbr title="اونا رو کنار هم می‌ذاره، یکی بعد از اون یکی.">ترکیبشون</abbr> می‌کنه با یه فاصله وسطشون. |
|||
|
|||
{* ../../docs_src/python_types/tutorial001.py hl[2] *} |
|||
|
|||
### ویرایشش کن |
|||
|
|||
این یه برنامه خیلی ساده‌ست. |
|||
|
|||
ولی حالا تصور کن داری از صفر می‌نویسیش. |
|||
|
|||
یه جایی شروع کردی به تعریف تابع، پارامترهات آماده‌ست... |
|||
|
|||
ولی بعد باید "اون متدی که حرف اول رو بزرگ می‌کنه" رو صدا کنی. |
|||
|
|||
آیا اسمش `upper` بود؟ یا `uppercase`؟ شاید `first_uppercase`؟ یا `capitalize`؟ |
|||
|
|||
بعد، با دوست قدیمی برنامه‌نویسا، تکمیل خودکار ویرایشگر، امتحان می‌کنی. |
|||
|
|||
پارامتر اول تابع، `first_name` رو تایپ می‌کنی، بعد یه نقطه (`.`) می‌ذاری و `Ctrl+Space` رو می‌زنی تا تکمیل خودکار بیاد. |
|||
|
|||
ولی متأسفانه، چیز مفیدی نمی‌گیری: |
|||
|
|||
<img src="/img/python-types/image01.png"> |
|||
|
|||
### نوع اضافه کن |
|||
|
|||
بیا فقط یه خط از نسخه قبلی رو تغییر بدیم. |
|||
|
|||
دقیقاً این بخش، پارامترهای تابع رو، از: |
|||
|
|||
```Python |
|||
first_name, last_name |
|||
``` |
|||
|
|||
به: |
|||
|
|||
```Python |
|||
first_name: str, last_name: str |
|||
``` |
|||
|
|||
عوض می‌کنیم. |
|||
|
|||
همینه. |
|||
|
|||
اینا همون "نوع‌نماها" هستن: |
|||
|
|||
{* ../../docs_src/python_types/tutorial002.py hl[1] *} |
|||
|
|||
این با تعریف مقدار پیش‌فرض فرق داره، مثل: |
|||
|
|||
```Python |
|||
first_name="john", last_name="doe" |
|||
``` |
|||
|
|||
یه چیز متفاوته. |
|||
|
|||
ما از دونقطه (`:`) استفاده می‌کنیم، نه علامت مساوی (`=`). |
|||
|
|||
و اضافه کردن نوع‌نماها معمولاً چیزی که اتفاق می‌افته رو از چیزی که بدون اونا می‌افتاد تغییر نمی‌ده. |
|||
|
|||
ولی حالا، دوباره تصور کن وسط ساختن اون تابع هستی، ولی این بار با نوع‌نماها. |
|||
|
|||
توی همون نقطه، سعی می‌کنی تکمیل خودکار رو با `Ctrl+Space` فعال کنی و اینو می‌بینی: |
|||
|
|||
<img src="/img/python-types/image02.png"> |
|||
|
|||
با این، می‌تونی اسکرول کنی، گزینه‌ها رو ببینی، تا وقتی که اون چیزی که "به نظرت آشنا میاد" رو پیدا کنی: |
|||
|
|||
<img src="/img/python-types/image03.png"> |
|||
|
|||
## انگیزه بیشتر |
|||
|
|||
این تابع رو چک کن، الان نوع‌نما داره: |
|||
|
|||
{* ../../docs_src/python_types/tutorial003.py hl[1] *} |
|||
|
|||
چون ویرایشگر نوع متغیرها رو می‌دونه، فقط تکمیل خودکار نمی‌گیری، بلکه چک خطاها هم داری: |
|||
|
|||
<img src="/img/python-types/image04.png"> |
|||
|
|||
حالا می‌دونی که باید درستش کنی، `age` رو با `str(age)` به یه رشته تبدیل کنی: |
|||
|
|||
{* ../../docs_src/python_types/tutorial004.py hl[2] *} |
|||
|
|||
## تعریف نوع‌ها |
|||
|
|||
تازه اصلی‌ترین جا برای تعریف نوع‌نماها رو دیدی. به‌عنوان پارامترهای تابع. |
|||
|
|||
این هم اصلی‌ترین جاییه که با **FastAPI** ازشون استفاده می‌کنی. |
|||
|
|||
### نوع‌های ساده |
|||
|
|||
می‌تونی همه نوع‌های استاندارد پایتون رو تعریف کنی، نه فقط `str`. |
|||
|
|||
مثلاً می‌تونی از اینا استفاده کنی: |
|||
|
|||
* `int` |
|||
* `float` |
|||
* `bool` |
|||
* `bytes` |
|||
|
|||
{* ../../docs_src/python_types/tutorial005.py hl[1] *} |
|||
|
|||
### نوع‌های عمومی با پارامترهای نوع |
|||
|
|||
یه سری ساختار داده هستن که می‌تونن مقدارهای دیگه رو نگه دارن، مثل `dict`، `list`، `set` و `tuple`. و مقدارهای داخلیشون هم می‌تونن نوع خودشون رو داشته باشن. |
|||
|
|||
به این نوع‌ها که نوع‌های داخلی دارن می‌گن "**عمومی**" یا "generic". و می‌شه اونا رو تعریف کرد، حتی با نوع‌های داخلیشون. |
|||
|
|||
برای تعریف این نوع‌ها و نوع‌های داخلیشون، می‌تونی از ماژول استاندارد پایتون `typing` استفاده کنی. این ماژول مخصوص پشتیبانی از نوع‌نماهاست. |
|||
|
|||
#### نسخه‌های جدیدتر پایتون |
|||
|
|||
سینتکس با استفاده از `typing` با همه نسخه‌ها، از پایتون 3.6 تا جدیدترین‌ها، از جمله پایتون 3.9، 3.10 و غیره **سازگاره**. |
|||
|
|||
با پیشرفت پایتون، **نسخه‌های جدیدتر** پشتیبانی بهتری برای این نوع‌نماها دارن و توی خیلی موارد حتی لازم نیست ماژول `typing` رو وارد کنی و ازش برای تعریف نوع‌نماها استفاده کنی. |
|||
|
|||
اگه بتونی برای پروژه‌ات از یه نسخه جدیدتر پایتون استفاده کنی، می‌تونی از این سادگی اضافه بهره ببری. |
|||
|
|||
توی همه مستندات، مثال‌هایی هستن که با هر نسخه پایتون سازگارن (وقتی تفاوتی هست). |
|||
|
|||
مثلاً "**Python 3.6+**" یعنی با پایتون 3.6 یا بالاتر (مثل 3.7، 3.8، 3.9، 3.10 و غیره) سازگاره. و "**Python 3.9+**" یعنی با پایتون 3.9 یا بالاتر (مثل 3.10 و غیره) سازگاره. |
|||
|
|||
اگه بتونی از **جدیدترین نسخه‌های پایتون** استفاده کنی، از مثال‌های نسخه آخر استفاده کن، چون اونا **بهترین و ساده‌ترین سینتکس** رو دارن، مثلاً "**Python 3.10+**". |
|||
|
|||
#### لیست |
|||
|
|||
مثلاً، بیایم یه متغیر تعریف کنیم که یه `list` از `str` باشه. |
|||
|
|||
//// tab | Python 3.9+ |
|||
|
|||
متغیر رو با همون سینتکس دونقطه (`:`) تعریف کن. |
|||
|
|||
به‌عنوان نوع، `list` رو بذار. |
|||
|
|||
چون لیست یه نوعه که نوع‌های داخلی داره، اونا رو توی کروشه‌ها می‌ذاری: |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../docs_src/python_types/tutorial006_py39.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.8+ |
|||
|
|||
از `typing`، `List` رو (با `L` بزرگ) وارد کن: |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../docs_src/python_types/tutorial006.py!} |
|||
``` |
|||
|
|||
متغیر رو با همون سینتکس دونقطه (`:`) تعریف کن. |
|||
|
|||
به‌عنوان نوع، `List` رو که از `typing` وارد کردی بذار. |
|||
|
|||
چون لیست یه نوعه که نوع‌های داخلی داره، اونا رو توی کروشه‌ها می‌ذاری: |
|||
|
|||
```Python hl_lines="4" |
|||
{!> ../../docs_src/python_types/tutorial006.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
/// info |
|||
|
|||
اون نوع‌های داخلی توی کروشه‌ها بهشون "پارامترهای نوع" می‌گن. |
|||
|
|||
توی این مورد، `str` پارامتر نوعیه که به `List` (یا `list` توی پایتون 3.9 و بالاتر) پاس داده شده. |
|||
|
|||
/// |
|||
|
|||
یعنی: "متغیر `items` یه `list` هست، و هر کدوم از آیتم‌های این لیست یه `str` هستن". |
|||
|
|||
/// tip |
|||
|
|||
اگه از پایتون 3.9 یا بالاتر استفاده می‌کنی، لازم نیست `List` رو از `typing` وارد کنی، می‌تونی همون نوع معمولی `list` رو به جاش استفاده کنی. |
|||
|
|||
/// |
|||
|
|||
با این کار، ویرایشگرت حتی وقتی داری آیتم‌های لیست رو پردازش می‌کنی بهت کمک می‌کنه: |
|||
|
|||
<img src="/img/python-types/image05.png"> |
|||
|
|||
بدون نوع‌ها، رسیدن به این تقریباً غیرممکنه. |
|||
|
|||
توجه کن که متغیر `item` یکی از عناصر توی لیست `items` هست. |
|||
|
|||
و با این حال، ویرایشگر می‌دونه که یه `str` هست و براش پشتیبانی می‌ده. |
|||
|
|||
#### تاپل و ست |
|||
|
|||
برای تعریف `tuple`ها و `set`ها هم همین کار رو می‌کنی: |
|||
|
|||
//// tab | Python 3.9+ |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../docs_src/python_types/tutorial007_py39.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.8+ |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../docs_src/python_types/tutorial007.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
یعنی: |
|||
|
|||
* متغیر `items_t` یه `tuple` با 3 تا آیتمه، یه `int`، یه `int` دیگه، و یه `str`. |
|||
* متغیر `items_s` یه `set` هست، و هر کدوم از آیتم‌هاش از نوع `bytes` هستن. |
|||
|
|||
#### دیکشنری |
|||
|
|||
برای تعریف یه `dict`، 2 تا پارامتر نوع می‌دی، که با کاما از هم جدا شدن. |
|||
|
|||
پارامتر نوع اول برای کلیدهای `dict` هست. |
|||
|
|||
پارامتر نوع دوم برای مقدارهای `dict` هست: |
|||
|
|||
//// tab | Python 3.9+ |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../docs_src/python_types/tutorial008_py39.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.8+ |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../docs_src/python_types/tutorial008.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
یعنی: |
|||
|
|||
* متغیر `prices` یه `dict` هست: |
|||
* کلیدهای این `dict` از نوع `str` هستن (مثلاً اسم هر آیتم). |
|||
* مقدارهای این `dict` از نوع `float` هستن (مثلاً قیمت هر آیتم). |
|||
|
|||
#### اتحادیه |
|||
|
|||
می‌تونی تعریف کنی که یه متغیر می‌تونه هر کدوم از **چند تا نوع** باشه، مثلاً یه `int` یا یه `str`. |
|||
|
|||
توی پایتون 3.6 و بالاتر (از جمله پایتون 3.10) می‌تونی از نوع `Union` توی `typing` استفاده کنی و نوع‌های ممکن رو توی کروشه‌ها بذاری. |
|||
|
|||
توی پایتون 3.10 یه **سینتکس جدید** هم هست که می‌تونی نوع‌های ممکن رو با یه <abbr title="بهش 'عملگر بیتی یا' هم می‌گن، ولی اینجا معنی‌ش مهم نیست">خط عمودی (`|`)</abbr> جدا کنی. |
|||
|
|||
//// tab | Python 3.10+ |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../docs_src/python_types/tutorial008b_py310.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.8+ |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../docs_src/python_types/tutorial008b.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
توی هر دو حالت یعنی `item` می‌تونه یه `int` یا یه `str` باشه. |
|||
|
|||
#### شاید `None` |
|||
|
|||
می‌تونی تعریف کنی که یه مقدار می‌تونه یه نوع باشه، مثلاً `str`، ولی می‌تونه `None` هم باشه. |
|||
|
|||
توی پایتون 3.6 و بالاتر (از جمله پایتون 3.10) می‌تونی با وارد کردن و استفاده از `Optional` از ماژول `typing` اینو تعریف کنی. |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!../../docs_src/python_types/tutorial009.py!} |
|||
``` |
|||
|
|||
استفاده از `Optional[str]` به جای فقط `str` به ویرایشگر کمک می‌کنه خطاهایی که ممکنه فکر کنی یه مقدار همیشه `str` هست رو پیدا کنه، در حالی که می‌تونه `None` هم باشه. |
|||
|
|||
`Optional[Something]` در واقع میان‌بر برای `Union[Something, None]` هست، این دو تا معادلن. |
|||
|
|||
یعنی توی پایتون 3.10، می‌تونی از `Something | None` استفاده کنی: |
|||
|
|||
//// tab | Python 3.10+ |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../docs_src/python_types/tutorial009_py310.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.8+ |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../docs_src/python_types/tutorial009.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.8+ جایگزین |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../docs_src/python_types/tutorial009b.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
#### استفاده از `Union` یا `Optional` |
|||
|
|||
اگه از نسخه پایتون زیر 3.10 استفاده می‌کنی، یه نکته از دید خیلی **شخصی** خودم: |
|||
|
|||
* 🚨 از `Optional[SomeType]` استفاده نکن |
|||
* به جاش ✨ **از `Union[SomeType, None]` استفاده کن** ✨. |
|||
|
|||
هر دو معادلن و زیر پوسته یکی‌ان، ولی من `Union` رو به `Optional` ترجیح می‌دم چون کلمه "**اختیاری**" انگار暗示 می‌کنه که مقدار اختیاریه، در حالی که در واقع یعنی "می‌تونه `None` باشه"، حتی اگه اختیاری نباشه و هنوز لازم باشه. |
|||
|
|||
فکر می‌کنم `Union[SomeType, None]` واضح‌تر نشون می‌ده چی معنی می‌ده. |
|||
|
|||
فقط بحث کلمات و اسم‌هاست. ولی این کلمات می‌تونن رو طرز فکر تو و تیمت نسبت به کد تأثیر بذارن. |
|||
|
|||
به‌عنوان مثال، این تابع رو ببین: |
|||
|
|||
{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *} |
|||
|
|||
پارامتر `name` به‌عنوان `Optional[str]` تعریف شده، ولی **اختیاری نیست**، نمی‌تونی تابع رو بدون پارامتر صدا کنی: |
|||
|
|||
```Python |
|||
say_hi() # اوه نه، این خطا می‌ده! 😱 |
|||
``` |
|||
|
|||
پارامتر `name` **هنوز لازمه** (نه *اختیاری*) چون مقدار پیش‌فرض نداره. با این حال، `name` مقدار `None` رو قبول می‌کنه: |
|||
|
|||
```Python |
|||
say_hi(name=None) # این کار می‌کنه، None معتبره 🎉 |
|||
``` |
|||
|
|||
خبر خوب اینه که وقتی رو پایتون 3.10 باشی، لازم نیست نگران این باشی، چون می‌تونی به‌سادگی از `|` برای تعریف اتحادیه نوع‌ها استفاده کنی: |
|||
|
|||
{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *} |
|||
|
|||
اون موقع دیگه لازم نیست نگران اسم‌هایی مثل `Optional` و `Union` باشی. 😎 |
|||
|
|||
#### نوع‌های عمومی |
|||
|
|||
این نوع‌هایی که پارامترهای نوع رو توی کروشه‌ها می‌گیرن بهشون **نوع‌های عمومی** یا **Generics** می‌گن، مثلاً: |
|||
|
|||
//// tab | Python 3.10+ |
|||
|
|||
می‌تونی از همون نوع‌های داخلی به‌عنوان نوع‌های عمومی استفاده کنی (با کروشه‌ها و نوع‌ها داخلشون): |
|||
|
|||
* `list` |
|||
* `tuple` |
|||
* `set` |
|||
* `dict` |
|||
|
|||
و همون‌طور که توی پایتون 3.8 بود، از ماژول `typing`: |
|||
|
|||
* `Union` |
|||
* `Optional` (همون‌طور که توی پایتون 3.8 بود) |
|||
* ...و بقیه. |
|||
|
|||
توی پایتون 3.10، به‌عنوان جایگزین برای استفاده از نوع‌های عمومی `Union` و `Optional`، می‌تونی از <abbr title="بهش 'عملگر بیتی یا' هم می‌گن، ولی اینجا معنی‌ش مهم نیست">خط عمودی (`|`)</abbr> برای تعریف اتحادیه نوع‌ها استفاده کنی، که خیلی بهتر و ساده‌تره. |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.9+ |
|||
|
|||
می‌تونی از همون نوع‌های داخلی به‌عنوان نوع‌های عمومی استفاده کنی (با کروشه‌ها و نوع‌ها داخلشون): |
|||
|
|||
* `list` |
|||
* `tuple` |
|||
* `set` |
|||
* `dict` |
|||
|
|||
و همون‌طور که توی پایتون 3.8 بود، از ماژول `typing`: |
|||
|
|||
* `Union` |
|||
* `Optional` |
|||
* ...و بقیه. |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.8+ |
|||
|
|||
* `List` |
|||
* `Tuple` |
|||
* `Set` |
|||
* `Dict` |
|||
* `Union` |
|||
* `Optional` |
|||
* ...و بقیه. |
|||
|
|||
//// |
|||
|
|||
### کلاس‌ها به‌عنوان نوع |
|||
|
|||
می‌تونی یه کلاس رو هم به‌عنوان نوع یه متغیر تعریف کنی. |
|||
|
|||
فرض کن یه کلاس `Person` داری، با یه نام: |
|||
|
|||
{* ../../docs_src/python_types/tutorial010.py hl[1:3] *} |
|||
|
|||
بعد می‌تونی یه متغیر رو از نوع `Person` تعریف کنی: |
|||
|
|||
{* ../../docs_src/python_types/tutorial010.py hl[6] *} |
|||
|
|||
و بعد، دوباره، همه پشتیبانی ویرایشگر رو داری: |
|||
|
|||
<img src="/img/python-types/image06.png"> |
|||
|
|||
توجه کن که این یعنی "`one_person` یه **نمونه** از کلاس `Person` هست". |
|||
|
|||
یعنی "`one_person` خود **کلاس** به اسم `Person` نیست". |
|||
|
|||
## مدل‌های Pydantic |
|||
|
|||
<a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> یه کتابخونه پایتونه برای اعتبارسنجی داده‌ها. |
|||
|
|||
"شکل" داده‌ها رو به‌عنوان کلاس‌هایی با ویژگی‌ها تعریف می‌کنی. |
|||
|
|||
و هر ویژگی یه نوع داره. |
|||
|
|||
بعد یه نمونه از اون کلاس رو با یه سری مقدار می‌سازی و اون مقدارها رو اعتبارسنجی می‌کنه، به نوع مناسب تبدیلشون می‌کنه (اگه لازم باشه) و یه شیء با همه داده‌ها بهت می‌ده. |
|||
|
|||
و با اون شیء نهایی همه پشتیبانی ویرایشگر رو می‌گیری. |
|||
|
|||
یه مثال از مستندات رسمی Pydantic: |
|||
|
|||
//// tab | Python 3.10+ |
|||
|
|||
```Python |
|||
{!> ../../docs_src/python_types/tutorial011_py310.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.9+ |
|||
|
|||
```Python |
|||
{!> ../../docs_src/python_types/tutorial011_py39.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.8+ |
|||
|
|||
```Python |
|||
{!> ../../docs_src/python_types/tutorial011.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
/// info |
|||
|
|||
برای اطلاعات بیشتر در مورد <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic، مستنداتش رو چک کن</a>. |
|||
|
|||
/// |
|||
|
|||
**FastAPI** کاملاً بر پایه Pydantic هست. |
|||
|
|||
توی [آموزش - راهنمای کاربر](tutorial/index.md){.internal-link target=_blank} خیلی بیشتر از اینا رو توی عمل می‌بینی. |
|||
|
|||
/// tip |
|||
|
|||
Pydantic یه رفتار خاص داره وقتی از `Optional` یا `Union[Something, None]` بدون مقدار پیش‌فرض استفاده می‌کنی، می‌تونی توی مستندات Pydantic در مورد <a href="https://docs.pydantic.dev/2.3/usage/models/#required-fields" class="external-link" target="_blank">فیلدهای اختیاری لازم</a> بیشتر بخونی. |
|||
|
|||
/// |
|||
|
|||
## نوع‌نماها با Annotationهای متادیتا |
|||
|
|||
پایتون یه قابلیت هم داره که بهت اجازه می‌ده **<abbr title="داده در مورد داده، اینجا یعنی اطلاعات در مورد نوع، مثلاً یه توضیح">متادیتا</abbr> اضافی** رو توی این نوع‌نماها بذاری با استفاده از `Annotated`. |
|||
|
|||
//// tab | Python 3.9+ |
|||
|
|||
توی پایتون 3.9، `Annotated` بخشی از کتابخونه استاندارده، پس می‌تونی از `typing` واردش کنی. |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../docs_src/python_types/tutorial013_py39.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
//// tab | Python 3.8+ |
|||
|
|||
توی نسخه‌های زیر پایتون 3.9، `Annotated` رو از `typing_extensions` وارد می‌کنی. |
|||
|
|||
با **FastAPI** از قبل نصب شده. |
|||
|
|||
```Python hl_lines="1 4" |
|||
{!> ../../docs_src/python_types/tutorial013.py!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
خود پایتون با این `Annotated` کاری نمی‌کنه. و برای ویرایشگرها و ابزارهای دیگه، نوع هنوز `str` هست. |
|||
|
|||
ولی می‌تونی از این فضا توی `Annotated` استفاده کنی تا به **FastAPI** متادیتای اضافی در مورد اینکه چطور می‌خوای برنامه‌ات رفتار کنه بدی. |
|||
|
|||
نکته مهم اینه که **اولین *پارامتر نوع*** که به `Annotated` می‌دی، **نوع واقعی** هست. بقیش فقط متادیتا برای ابزارهای دیگه‌ست. |
|||
|
|||
الان فقط باید بدونی که `Annotated` وجود داره، و اینکه پایتون استاندارده. 😎 |
|||
|
|||
بعداً می‌بینی که چقدر **قوی** می‌تونه باشه. |
|||
|
|||
/// tip |
|||
|
|||
اینکه این **پایتون استاندارده** یعنی هنوز **بهترین تجربه توسعه‌دهنده** رو توی ویرایشگرت، با ابزارهایی که برای تحلیل و بازسازی کدت استفاده می‌کنی و غیره می‌گیری. ✨ |
|||
|
|||
و همین‌طور کدت با خیلی از ابزارها و کتابخونه‌های دیگه پایتون خیلی سازگار می‌مونه. 🚀 |
|||
|
|||
/// |
|||
|
|||
## نوع‌نماها توی **FastAPI** |
|||
|
|||
**FastAPI** از این نوع‌نماها استفاده می‌کنه تا چند تا کار بکنه. |
|||
|
|||
با **FastAPI** پارامترها رو با نوع‌نماها تعریف می‌کنی و اینا رو می‌گیری: |
|||
|
|||
* **پشتیبانی ویرایشگر**. |
|||
* **چک نوع‌ها**. |
|||
|
|||
...و **FastAPI** از همون تعریف‌ها برای اینا استفاده می‌کنه: |
|||
|
|||
* **تعریف نیازها**: از پارامترهای مسیر درخواست، پارامترهای کوئری، هدرها، بدنه‌ها، وابستگی‌ها و غیره. |
|||
* **تبدیل داده**: از درخواست به نوع مورد نیاز. |
|||
* **اعتبارسنجی داده**: که از هر درخواست میاد: |
|||
* تولید **خطاهای خودکار** که به کلاینت برمی‌گرده وقتی داده نامعتبره. |
|||
* **مستندسازی** API با استفاده از OpenAPI: |
|||
* که بعدش توسط رابط‌های کاربری مستندات تعاملی خودکار استفاده می‌شه. |
|||
|
|||
اینا شاید همه‌ش انتزاعی به نظر بیاد. نگران نباش. همه اینا رو توی عمل توی [آموزش - راهنمای کاربر](tutorial/index.md){.internal-link target=_blank} می‌بینی. |
|||
|
|||
نکته مهم اینه که با استفاده از نوع‌های استاندارد پایتون، توی یه جا (به جای اضافه کردن کلاس‌های بیشتر، دکوراتورها و غیره)، **FastAPI** کلی از کار رو برات انجام می‌ده. |
|||
|
|||
/// info |
|||
|
|||
اگه همه آموزش رو گذروندی و برگشتی که بیشتر در مورد نوع‌ها ببینی، یه منبع خوب <a href="https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html" class="external-link" target="_blank">"تقلب‌نامه" از `mypy`</a> هست. |
|||
|
|||
/// |
|||
@ -1,84 +1,28 @@ |
|||
# Geração de Projetos - Modelo |
|||
|
|||
Você pode usar um gerador de projetos para começar, por já incluir configurações iniciais, segurança, banco de dados e os primeiros _endpoints_ API já feitos para você. |
|||
|
|||
Um gerador de projetos sempre terá uma pré-configuração que você pode atualizar e adaptar para suas próprias necessidades, mas pode ser um bom ponto de partida para seu projeto. |
|||
|
|||
## Full Stack FastAPI PostgreSQL |
|||
|
|||
GitHub: <a href="https://github.com/tiangolo/full-stack-fastapi-postgresql" class="external-link" target="_blank">https://github.com/tiangolo/full-stack-fastapi-postgresql</a> |
|||
|
|||
### Full Stack FastAPI PostgreSQL - Recursos |
|||
|
|||
* Integração completa **Docker**. |
|||
* Modo de implantação Docker Swarm. |
|||
* Integração e otimização **Docker Compose** para desenvolvimento local. |
|||
* **Pronto para Produção** com servidor _web_ usando Uvicorn e Gunicorn. |
|||
* _Backend_ <a href="https://github.com/fastapi/fastapi" class="external-link" target="_blank">**FastAPI**</a> Python: |
|||
* **Rápido**: Alta performance, no nível de **NodeJS** e **Go** (graças ao Starlette e Pydantic). |
|||
* **Intuitivo**: Ótimo suporte de editor. <abbr title="também conhecido como auto-complete, auto completação, IntelliSense">_Auto-Complete_</abbr> em todo lugar. Menos tempo _debugando_. |
|||
* **Fácil**: Projetado para ser fácil de usar e aprender. Menos tempo lendo documentações. |
|||
* **Curto**: Minimize duplicação de código. Múltiplos recursos para cada declaração de parâmetro. |
|||
* **Robusto**: Tenha código pronto para produção. Com documentação interativa automática. |
|||
* **Baseado em Padrões**: Baseado em (e completamente compatível com) padrões abertos para APIs: <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> e <a href="http://json-schema.org/" class="external-link" target="_blank">JSON Schema</a>. |
|||
* <a href="https://fastapi.tiangolo.com/features/" class="external-link" target="_blank">**Muitos outros recursos**</a> incluindo validação automática, serialização, documentação interativa, autenticação com _tokens_ OAuth2 JWT etc. |
|||
* **Senha segura** _hashing_ por padrão. |
|||
* Autenticação **Token JWT**. |
|||
* Modelos **SQLAlchemy** (independente de extensões Flask, para que eles possam ser usados com _workers_ Celery diretamente). |
|||
* Modelos básicos para usuários (modifique e remova conforme suas necessidades). |
|||
* Migrações **Alembic**. |
|||
* **CORS** (_Cross Origin Resource Sharing_ - Compartilhamento de Recursos Entre Origens). |
|||
* _Worker_ **Celery** que pode importar e usar modelos e códigos do resto do _backend_ seletivamente. |
|||
* Testes _backend_ _REST_ baseados no **Pytest**, integrados com Docker, então você pode testar a interação completa da API, independente do banco de dados. Como roda no Docker, ele pode construir um novo repositório de dados do zero toda vez (assim você pode usar ElasticSearch, MongoDB, CouchDB, ou o que quiser, e apenas testar que a API esteja funcionando). |
|||
* Fácil integração com Python através dos **Kernels Jupyter** para desenvolvimento remoto ou no Docker com extensões como Atom Hydrogen ou Visual Studio Code Jupyter. |
|||
* _Frontend_ **Vue**: |
|||
* Gerado com Vue CLI. |
|||
* Controle de **Autenticação JWT**. |
|||
* Visualização de _login_. |
|||
* Após o _login_, visualização do painel de controle principal. |
|||
* Painel de controle principal com criação e edição de usuário. |
|||
* Edição do próprio usuário. |
|||
* **Vuex**. |
|||
* **Vue-router**. |
|||
* **Vuetify** para belos componentes _material design_. |
|||
* **TypeScript**. |
|||
* Servidor Docker baseado em **Nginx** (configurado para rodar "lindamente" com Vue-router). |
|||
* Construção multi-estágio Docker, então você não precisa salvar ou _commitar_ código compilado. |
|||
* Testes _frontend_ rodados na hora da construção (pode ser desabilitado também). |
|||
* Feito tão modular quanto possível, então ele funciona fora da caixa, mas você pode gerar novamente com Vue CLI ou criar conforme você queira, e reutilizar o que quiser. |
|||
* **PGAdmin** para banco de dados PostgreSQL, você pode modificar para usar PHPMyAdmin e MySQL facilmente. |
|||
* **Flower** para monitoração de tarefas Celery. |
|||
* Balanceamento de carga entre _frontend_ e _backend_ com **Traefik**, então você pode ter ambos sob o mesmo domínio, separados por rota, mas servidos por diferentes containers. |
|||
* Integração Traefik, incluindo geração automática de certificados **HTTPS** Let's Encrypt. |
|||
* GitLab **CI** (integração contínua), incluindo testes _frontend_ e _backend_. |
|||
|
|||
## Full Stack FastAPI Couchbase |
|||
|
|||
GitHub: <a href="https://github.com/tiangolo/full-stack-fastapi-couchbase" class="external-link" target="_blank">https://github.com/tiangolo/full-stack-fastapi-couchbase</a> |
|||
|
|||
⚠️ **WARNING** ⚠️ |
|||
|
|||
Se você está iniciando um novo projeto do zero, verifique as alternativas aqui. |
|||
|
|||
Por exemplo, o gerador de projetos <a href="https://github.com/tiangolo/full-stack-fastapi-postgresql" class="external-link" target="_blank">Full Stack FastAPI PostgreSQL</a> pode ser uma alternativa melhor, como ele é ativamente mantido e utilizado. E ele inclui todos os novos recursos e melhorias. |
|||
|
|||
Você ainda é livre para utilizar o gerador baseado em Couchbase se quiser, ele provavelmente ainda funciona bem, e você já tem um projeto gerado com ele que roda bem também (e você provavelmente já atualizou ele para encaixar nas suas necessidades). |
|||
|
|||
Você pode ler mais sobre nas documentaçãoes do repositório. |
|||
|
|||
## Full Stack FastAPI MongoDB |
|||
|
|||
...pode demorar, dependendo do meu tempo disponível e outros fatores. 😅 🎉 |
|||
|
|||
## Modelos de Aprendizado de Máquina com spaCy e FastAPI |
|||
|
|||
GitHub: <a href="https://github.com/microsoft/cookiecutter-spacy-fastapi" class="external-link" target="_blank">https://github.com/microsoft/cookiecutter-spacy-fastapi</a> |
|||
|
|||
### Modelos de Aprendizado de Máquina com spaCy e FastAPI - Recursos |
|||
|
|||
* Integração com modelo NER **spaCy**. |
|||
* Formato de requisição **Busca Cognitiva Azure** acoplado. |
|||
* Servidor Python _web_ **Pronto para Produção** usando Uvicorn e Gunicorn. |
|||
* Implantação **Azure DevOps** Kubernetes (AKS) CI/CD acoplada. |
|||
* **Multilingual** facilmente escolhido como uma das linguagens spaCy acopladas durante a configuração do projeto. |
|||
* **Facilmente extensível** para outros modelos de _frameworks_ (Pytorch, Tensorflow), não apenas spaCy. |
|||
# Full Stack FastAPI Template |
|||
|
|||
_Templates_, embora tipicamente venham com alguma configuração específica, são desenhados para serem flexíveis e customizáveis. Isso permite que você os modifique e adapte para as especificações do seu projeto, fazendo-os um excelente ponto de partida. 🏁 |
|||
|
|||
Você pode usar esse _template_ para começar, já que ele inclui várias configurações iniciais, segurança, banco de dados, e alguns _endpoints_ de API já feitos para você. |
|||
|
|||
Repositório GitHub: <a href="https://github.com/tiangolo/full-stack-fastapi-template" class="external-link" target="_blank">Full Stack FastAPI Template</a> |
|||
|
|||
## Full Stack FastAPI Template - Pilha de Tecnologias e Recursos |
|||
|
|||
- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) para a API do backend em Python. |
|||
- 🧰 [SQLModel](https://sqlmodel.tiangolo.com) para as interações do Python com bancos de dados SQL (ORM). |
|||
- 🔍 [Pydantic](https://docs.pydantic.dev), usado pelo FastAPI, para validação de dados e gerenciamento de configurações. |
|||
- 💾 [PostgreSQL](https://www.postgresql.org) como banco de dados SQL. |
|||
- 🚀 [React](https://react.dev) para o frontend. |
|||
- 💃 Usando TypeScript, hooks, [Vite](https://vitejs.dev), e outras partes de uma _stack_ frontend moderna. |
|||
- 🎨 [Chakra UI](https://chakra-ui.com) para os componentes de frontend. |
|||
- 🤖 Um cliente frontend automaticamente gerado. |
|||
- 🧪 [Playwright](https://playwright.dev) para testes Ponta-a-Ponta. |
|||
- 🦇 Suporte para modo escuro. |
|||
- 🐋 [Docker Compose](https://www.docker.com) para desenvolvimento e produção. |
|||
- 🔒 _Hash_ seguro de senhas por padrão. |
|||
- 🔑 Autenticação por token JWT. |
|||
- 📫 Recuperação de senhas baseada em email. |
|||
- ✅ Testes com [Pytest](https://pytest.org). |
|||
- 📞 [Traefik](https://traefik.io) como proxy reverso / balanceador de carga. |
|||
- 🚢 Instruções de _deployment_ usando Docker Compose, incluindo como configurar um proxy frontend com Traefik para gerenciar automaticamente certificados HTTPS. |
|||
- 🏭 CI (Integração Contínua) e CD (_Deploy_ Contínuo) baseado em GitHub Actions. |
|||
|
|||
Loading…
Reference in new issue