با Flask 3.0 شروع کنید

با این آموزش شروع سریع، ابتدا وارد یکی از محبوب ترین و همه کاره ترین چارچوب های وب برای پایتون شوید.

• راه اندازی فلاسک
• یک برنامه اصلی Flask
• مسیرها و متغیرهای مسیر در Flask
• روش‌های مسیریابی در Flask
• درخواست داده در Flask
• بازگرداندن پاسخ‌ها در Flask
• قالب‌ها در فلاسک
• کنترل کننده خطا در Flask
• اجرا و رفع اشکال فلاسک در حال تولید
• استفاده از ناهمگام در فلاسک

یکی از دلایلی که Python یک انتخاب اصلی برای توسعه وب است، گستردگی چارچوب‌های وب موجود در این زبان است. یکی از محبوب‌ترین و مفیدترین آن‌ها Flask است که به شما امکان می‌دهد ساده شروع کنید (“یک قطره در یک زمان”) اما با برنامه شما رشد می‌کند تا تقریباً تمام عملکردهای مورد نیاز خود را اضافه کند.

در این مقاله، راه‌اندازی و استفاده از Flask 3.0 برای برنامه‌های اصلی وب را بررسی می‌کنیم. همچنین استفاده از Jinja2 را برای الگوسازی و رسیدگی به مسائل رایج مانند تغییر انواع پاسخ‌ها و مدیریت تغییرمسیرها لمس خواهیم کرد.

راه اندازی فلاسک

تنظیم Flask 3.0 آسان است. از pip install flask برای نصب Flask و همه وابستگی‌های آن از جمله سیستم قالب‌بندی Jinja2.

همانند هر فریم ورک پایتون، بهتر است یک پروژه با استفاده از Flask در یک محیط مجازی پایتون ایجاد کنید. این پروژه شما را از نصب اصلی پایتون و پروژه‌های دیگری که ممکن است از Flask و وابستگی‌های آن استفاده کنند جدا می‌کند (زیرا ممکن است نسخه‌های مختلفی را برای پروژه‌های مختلف حفظ کنید).

توجه داشته باشید که اگر می‌خواهید Flask را با پشتیبانی از توابع یا برنامه‌های ناهمزمان نصب کنید، از pip install flask[async] استفاده کنید. به زودی اطلاعات بیشتری در مورد استفاده از Flask with async خواهم داشت.

یک برنامه اصلی Flask

یک برنامه ساده و یک مسیره Flask را می توان تنها در چند خط کد نوشت. برنامه مثال ساده زیر را در فایلی با نام app.py ذخیره کنید:

from flask import Flask

app = Flask(__name__)

@app.route("/")
def home():
    return "Hello, world"

این برنامه کار زیادی انجام نمی‌دهد—فقط یک وب‌سایت با یک مسیر ایجاد می‌کند که «سلام، دنیا» را در مرورگر نمایش می‌دهد.

این چیزی است که هر عنصر انجام می دهد:

• خط app = Flask(__name__) یک نمونه جدید از یک برنامه Flask به نام app ایجاد می کند. کلاس Flask یک آرگومان می گیرد که نام ماژول یا بسته برنامه است. ارسال آن __name__ (نام ماژول فعلی) راهی سریع برای استفاده از ماژول فعلی به عنوان نقطه شروع برنامه است. در تئوری، می توانید از هر نامی استفاده کنید، اما مرسوم است که از نام ماژول به عنوان پیش فرض استفاده کنید.
• تزیین کننده app.route برای بسته بندی یک تابع و نشان دادن عملکرد مورد استفاده برای ارائه پاسخ برای یک مسیر مشخص استفاده می شود. در این مورد، مسیر، ریشه سایت ("/") و پاسخ رشته "سلام، دنیا" است.

برای اجرای برنامه، از python -m flask run در همان دایرکتوری app.py استفاده کنید. شما باید چیزی شبیه به زیر را در کنسول ببینید:

 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

اگر مرورگر وب را به http://127.0.0.1:5000/ باز کنید، باید کلمات “سلام، دنیا” را ببینید.

توجه داشته باشید که می‌توانید فایل اصلی برنامه Flask خود را هر چیزی نامگذاری کنید، اما نامگذاری آن app.py به Flask اجازه می‌دهد آن را به طور خودکار تشخیص دهد. برای استفاده از نام دیگری، ابتدا باید متغیر محیطی FLASK_APP را به نام فایل جدید منهای پسوند آن تنظیم کنید (به عنوان مثال، hello برای hello.py ).

همچنین توجه داشته باشید که وقتی یک برنامه Flask را به این روش اجرا می کنید، آن را با استفاده از سرور تست داخلی Flask اجرا می کنید، که برای استقرار تولید مناسب نیست. به زودی درباره نحوه استقرار Flask در تولید بحث خواهیم کرد.

مسیرها و متغیرهای مسیر در Flask

برنامه های وب معمولاً از اجزای مسیر به عنوان متغیرهایی استفاده می کنند که به تابع مسیر ارسال می شوند. Flask به شما امکان می دهد این کار را از طریق یک نحو تعریف مسیر خاص انجام دهید.

در این مثال، جایی که ما یک مسیر به فرمت /hi/ و به دنبال آن نام کاربری داریم، نام استخراج شده و به عنوان نام کاربری متغیر به تابع منتقل می‌شود.

@app.route("/hi/<username>")
def greet(username):
    return f"Hello, {username}"

از این مسیر با /hi/Serdar دیدن کنید و «سلام سردار» را در مرورگر مشاهده خواهید کرد.

انواع متغیرهای مسیر Flask

متغیرهای مسیر همچنین می‌توانند با افزودن اطلاعات نوع به آنها محدودیت نوع داشته باشند.

به عنوان مثال، اگر از استفاده می کنید، مطمئن می شوید که userid فقط یک عدد صحیح خواهد بود. اگر از استفاده می کنید، بخشی از URL از آن موقعیت به جلو در متغیر datapath استخراج می شود. برای این منظور، اگر مسیری مانند /show/ داشته باشیم و از URL /show/main/info استفاده کنیم، سپس main/ info در متغیر datapath ارسال می‌شود. (برای اطلاعات بیشتر در مورد متغیرهای مسیر با محدودیت نوع، مستندات Flask را ببینید. )

توجه داشته باشید که باید مراقب استفاده از مسیرهای متعدد و مشابه با انواع داده های مختلف باشید. اگر مسیر /data/ و مسیر /data/ را دارید، هر عنصری در موقعیت دوم که نمی‌تواند باشد مطابق با یک عدد صحیح به عنوان یک رشته مطابقت داده می شود. اگر می توانید از این نوع ساختارهای مسیر اجتناب کنید، زیرا ممکن است گیج کننده و اشکال زدایی آنها دشوار باشد. در مسیرهای خود تا جایی که می توانید بدون ابهام باشید.

روش‌های مسیریابی در Flask

دکوراتورهای مسیر همچنین می‌توانند روش‌های مورد استفاده برای دسترسی به مسیر را مشخص کنند. می‌توانید چندین تابع برای مدیریت یک مسیر واحد با روش‌های مختلف ایجاد کنید، مانند:

@app.route('/post', methods=['GET'])
def post_message_route_get():
    return show_post_message_form()

@app.route('/post', methods=['POST'])
def post_message_route_post():
    return post_message_to_site()

یا، می‌توانید مسیرها را در یک تابع واحد ادغام کنید و بر اساس روش داخلی تصمیم بگیرید:

from flask import request

@app.route('/post', methods=['GET', 'POST'])
def post_message_route():
    if request.method == 'POST':
        return post_message_to_site()
    # defaults to GET if not POST
    return show_post_message_form()

توجه داشته باشید که برای دسترسی به ویژگی متد، باید شی request جهانی را وارد کنیم. بعداً این را با جزئیات بررسی خواهیم کرد.

Flask 3.0 همچنین به شما امکان می دهد از app.get و app.post به عنوان میانبر استفاده کنید. مسیرهای فوق را می توان به صورت زیر نیز بیان کرد:

@app.get('/post')
def post_message_route_get():
    return show_post_message_form()

@app.post('/post')
def post_message_route_post():
    return post_message_to_site()

درخواست داده در Flask

در بخش آخر، روش مورد استفاده برای فراخوانی یک مسیر از شی درخواست جهانی را به دست آوردیم. درخواست نمونه ای از شیء درخواست، که از طریق آن می‌توانیم بسیاری از جزئیات دیگر را در مورد درخواست به دست آوریم – سرصفحه‌ها، کوکی‌ها، داده‌های فرم، آپلود فایل‌ها و غیره.

برخی از ویژگی های رایج یک شی درخواست عبارتند از:

• .args: فرهنگ لغتی که پارامترهای URL را در خود نگه می دارد. به عنوان مثال، یک URL با آرگومان هایی مانند ?id=1 به عنوان فرهنگ لغت {"id": 1} بیان می شود.
• .cookies: فرهنگ لغتی که کوکی های ارسال شده در درخواست را در خود نگه می دارد.
• .files: فرهنگ لغتی که حاوی هر فایلی است که با درخواست آپلود شده است و کلید هر عنصر نام فایل است.
• .form: فرهنگ لغت حاوی داده‌های فرم درخواست، در صورت وجود.
• .headers: سرصفحه های خام برای درخواست.
• .method: روش استفاده شده توسط درخواست (به عنوان مثال، GET، POST).

بازگرداندن پاسخ‌ها در Flask

وقتی یک تابع مسیر داده‌ها را برمی‌گرداند، Flask بهترین حدس را انجام می‌دهد برای تفسیر آنچه برگردانده شده است:

• اشیاء پاسخ همانطور که هست برگردانده می‌شوند. ایجاد یک شیء پاسخ به شما کنترل دقیقی بر آنچه که به مشتری برمی گردانید می دهد، اما برای بیشتر موارد استفاده می توانید از یکی از موارد زیر استفاده کنید.
• رشته‌ها، از جمله خروجی قالب‌های Jinja2 (در ادامه بیشتر توضیح خواهیم داد)، با کد وضعیت ۲۰۰ OK و نوع MIME Response تبدیل می‌شوند. code>text/html.
• لغت نامه ها به JSON تبدیل می شوند.
• تکل ها می توانند یکی از موارد زیر باشند:
  • (پاسخ، کد وضعیت [int])
  • (پاسخ، سرصفحه ها [list/dict])
  • (پاسخ، کد وضعیت [int]، سرصفحه ها [list/dict])

• (پاسخ، کد وضعیت [int])
• (پاسخ، سرصفحه ها [list/dict])
• (پاسخ، کد وضعیت [int]، سرصفحه ها [list/dict])

به طور کلی، بهتر است هر چیزی که کار عملکرد مسیر را واضح‌تر نشان می‌دهد، برگردانید. به عنوان مثال، یک کنترل کننده خطای ۴۰۴ می تواند یک کد ۲ تایی – کد خطای ۴۰۴ و جزئیات پیام خطا را برگرداند. این عملکرد مسیر را بی نظم نگه می دارد.

قالب‌ها در فلاسک

Flask شامل موتور قالب Jinja2 برای تولید خروجی HTML از داده‌ها به صورت برنامه‌ریزی شده است. شما از تابع render_template برای تولید HTML استفاده می‌کنید، سپس متغیرهایی را برای استفاده در الگو ارسال می‌کنید.

در اینجا مثالی از نحوه ظاهر آن در یک مسیر آمده است:

from flask import render_template

@app.route('/hi/<username>')
def greet(username=None):
    return render_template('hello.html', username=username)

الگوهایی که توسط render_template ارجاع می‌شوند به‌طور پیش‌فرض در زیرشاخه‌های فهرست پروژه Flask، به نام الگوها یافت می‌شوند. برای این منظور، فایل زیر در templates/hello.html خواهد بود:

<!doctype html>
<title>Hi there</title>
{% if username %}
  <h1>Hello {{ username }}!</h1>
{% else %}
  <h1>Hello, whoever you are!</h1>
{% endif %}

الگوهای Jinja2 برای خودشان چیزی شبیه به یک زبان هستند، اما این قطعه باید به شما ایده ای از نحوه کار آنها بدهد. بلوک های مشخص شده با {% %} حاوی منطق الگو هستند و بلوک های دارای {{ }} حاوی عباراتی هستند که باید در آن نقطه درج شوند. وقتی این الگو را با render_template در بالا فراخوانی کردیم، نام کاربری را به عنوان آرگومان کلمه کلیدی ارسال کردیم. همین کار را برای هر متغیر دیگری که استفاده می کنیم انجام می شود.

توجه داشته باشید که قالب‌های Jinja2 برای امنیت، محدودیت‌هایی روی کدهایی دارند که می‌توان آن‌ها را اجرا کرد. بنابراین، می‌خواهید تا حد ممکن پردازش را برای یک صفحه معین قبل از ارسال آن به یک الگو انجام دهید.

کنترل کننده خطا در Flask

برای ایجاد مسیری که کلاس خاصی از خطای سرور را کنترل می کند، از تزئین کننده errorhandler استفاده کنید:

@app.errorhandler(404)
def page_not_found(error):
    return f"error: {error}"

برای این برنامه، هر زمان که خطای ۴۰۴ ایجاد شود، نتیجه ای که به مشتری بازگردانده می شود توسط تابع page_not_found ایجاد می شود. خطا استثنای ایجاد شده توسط برنامه، بنابراین می توانید در صورت نیاز جزئیات بیشتری را از آن استخراج کنید و آنها را به مشتری بازگردانید.

اجرا و رفع اشکال فلاسک در حال تولید

سرور آزمایشی Flask که قبلاً در این مقاله ذکر شد برای استقرار Flask در تولید مناسب نیست. برای استقرار تولید، از یک سرور کامل سازگار با WSGI، با شی app ایجاد شده توسط Flask() به عنوان برنامه WSGI استفاده کنید.

مستندات Flask دارای جزئیاتی در مورد استقرار در اکثر گزینه‌های میزبانی رایج، و همچنین جزئیات نحوه میزبانی برنامه‌های Flask خود هستند – به عنوان مثال، از طریق mod_wsgi Apache یا از طریق uWSGI در Nginx.

استفاده از async در Flask

در اصل، Flask هیچ پشتیبانی صریحی از توابع ناهمزمان یا کوروتین ها نداشت. Coroutineها اکنون یک ویژگی استاندارد در پایتون هستند و از نسخه ۲.۰، Flask از روش‌های همگام‌سازی پشتیبانی می‌کند< /a> برای گردانندگان مسیر. با این حال، پشتیبانی async در Flask به عنوان یک افزونه ارائه می‌شود، بنابراین برای نصب این ویژگی باید از pip install flask[async] استفاده کنید.

@app.route("/embed/<embed_id>")
async def get_embed(embed_id):
    data = await async_render_embed(embed_id)
    return data

پشتیبانی async Flask این واقعیت را تغییر نمی دهد که به عنوان یک برنامه WSGI با یک کارگر برای رسیدگی به درخواست های دریافتی اجرا می شود. اگر می‌خواهید از درخواست‌های طولانی‌مدت مانند اتصالات WebSocket API پشتیبانی کنید، استفاده از async فقط در توابع مسیرتان کافی نخواهد بود. ممکن است بخواهید از فریمورک Quart استفاده کنید، که با API سازگار با Flask است اما از رابط ASGI برای درخواست های طولانی مدت و چندین درخواست همزمان را بهتر رسیدگی کند.