نوشتن اولین برنامه جنگو، قسمت اول

بیایید با مثال [پروژه محور] یاد بگیریم.

در این آموزش، شما با ساخت یک برنامه نظرسنجی ساده آشنا می شوید.

این برنامه از دو قسمت تشکیل خواهد شد:

  • یک بخش عمومی وب سایت که به مردم این امکان را می دهد تا نظرسنجی ها را دیده و بتوانند رای دهند.
  • یک بخش مدیریت وب سایت که شما بتوانید در نظرسنجی ها مواردی تغییر را داده، اضافه و یا حذف کنید.
ما فرض می کنیم که شما نصب جنگو را قبلاً انجام داده اید.
با اجرای دستور زیر در یک shell prompt (که با پیشوند $ و یا <… نشان داده می شود) می توانید ببینید کدام نسخه جنگو نصب شده است:
$ python -m django --version

...\> py -m django --version

اگر جنگو نصب شده باشد، باید نسخه نصب خود را ببینید. در غیر اینصورت با خطای “No module named django” مواجه خواهید شد.

این آموزش برای جنگو 3.2 نوشته شده است که از پایتون 3.6 به بعد پشتیبانی می کند. اگر نسخه جنگو مطابقت ندارد، می توانید با استفاده از تغییر دهنده نسخه در گوشه سمت راست پایین این صفحه به آموزش نسخه جنگو خود مراجعه کنید یا جنگو را به جدیدترین نسخه به روز کنید. اگر از نسخه قدیمی تر پایتون استفاده می کنید What Python version can I use with Django? را بررسی کنید تا نسخه سازگار با جنگو را پیدا کنید.

برای راهنمایی در مورد نحوه حذف نسخه های قدیمی جنگو و نصب نسخه جدیدتر، به چگونه جنگو را نصب کنیم؟ مراجعه کنید.

از کجا کمک بگیریم؟

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

ساخت پروژه

اگر برای اولین بار است که از جنگو استفاده می کنید، باید مراقب نصب تنطیمات اولیه باشید. به عبارتی دیگر، شما باید project را بطور خودکار ایجاد کنید تا مجموعه ای تنظیمات از جمله پیکربندی پایگاه داده، گزینه های خاص جنگو و تنظیمات خاص برنامه جنگو را ایجاد کند.

در خط فرمان با زدن دستور cd و رفتن به دایرکتوری مورد نظر برای ایجاد پروژه خود، دستور زیر را اجرا کنید.

$ django-admin startproject mysite

...\> django-admin startproject mysite

این دستور پوشه ای به نام mysite در مسیر دایرکتوری اخیر ایجاد می کند. اگر دستور کار نکرد به Problems running django-admin مراجعه کنید.

نکته

شما باید از نامگذاری پروژه مشابه با اسامی موجود در پایتون یا جنگو خودداری کنید. بطور خاص، استفاده از نامهایی مثل django (که با نام خود جنگو مغایرت دارد) و یا test (که با پکیج های آماده پایتون مغایرت دارد) خودداری کنید.

کد ها کجا باید قرار بگیرند؟

اگر بخش پس زمینه وب سایت با PHP بصورت خام (بدون استفاده از هیچ گونه فریم ورک جدیدی) نوشته شده باشد، شما احتمالا نیاز دارید تا کد خود را در وب سرور و مسیر اصلی قرار دهید(بطور مثال مسیری مانند …). با جنگو، نیازی به این کار ندارید. ایده خوبی نیست کد های پایتون خود را در مسیر اصلی وب سرور قرار دهید چراکه احتمال دیده شدن کد های شما در وب برای مردم وجود داشته باشد. و این مورد خوبی برای امنیت وب سایت نیست.

کد خود را خارج از دایرکتوری اصلی مثلا /home/mycode قرار دهید.

بیایید ببینیم دستور startproject چه چیزی ایجاد کرده است:

mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py

این فایل ها عبارتند از:

  • دایرکتوری اصلی خارجی mysite/ فضایی برای پروژه ی شماست. نام این پوشه برای جنگو اهمیتی ندارد. شما هر زمان که بخواهید میتوانید نام آن را تغییر دهید.
  • فایل manage.py: یک ابزار خط فرمان است که به شما این امکان را می دهد تا به روش های مختلف با پروژه جنگو خود تعامل داشته باشید. می توانید تمام جزییات مربوط به این فایل را در django-admin and manage.py ببینید.
  • دایرکتوری داخلی mysite/ بسته اصلی پایتون برای پروژه شماست. نام آن نام پکیج پایتون است که باید از آن برای وارد کردن هر چیزی در داخل آن استفاده کنید (برای مثال mysite.urls).
  • فایل mysite/__init__.py : یک فایل خالی است که به پایتون می گوید این دایرکتوری باید یک پکیج پایتون در نظر گرفته شود. اگر در پایتون مبتدی هستید، more about packages را در مستندات اصلی پایتون مطالعه کنید.
  • فایل mysite/settings.py : برای تنظیمات/پیکربندی پروژه جنگو است. Django settings درباره تمامی تنظیمات و نحوه کار کردن آن را توضیح می دهد.
  • فایل mysite/urls.py : برای اعلام آدرس های اینترنتی برای پروژه جنگو است. به عبارتی یک فهرست قدرتمند از محتویات وب سایت جنگو شماست. برای مطالعه بیشتر میتوانید URL dispatcher را مطالعه کنید.
  • فایل mysite/asgi.py : برای سازگاری وب سایت جنگو با وب سرور های با قابلیت ASGI است. برای اطلاعات بیشتر How to deploy with ASGI را ببینید.
  • فایل mysite/wsgi.py : برای سازگاری وب سایت با وب سرورهای با قابلیت WSGI است. برای اطلاعات بیشتر How to deploy with WSGI را مطالعه کنید.

راه اندازی سرور

بیایید بررسی کنیم که آیا پروژه جنگو کار می کند یا خیر. به دایرکتوری خارجی mysite رفته و در صورت وجود دستور زیر را در آن مسیر اجرا کنید:

$ python manage.py runserver

...\> py manage.py runserver

با اجرای دستور بالا خروجی زیر را در خط فرمان خواهید دید:

Performing system checks...

System check identified no issues (0 silenced).

You have unapplied migrations; your app may not work properly until they are applied.
Run 'python manage.py migrate' to apply them.

July 27, 2022 - 15:50:53
Django version 3.2, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

نکته

هشدار در رابطه با unapplied database migrations را فعلا نادیده بگیرید. به زودی با پایگاه داده سر و کار خواهیم داشت.

شما سرور جنگو را راه اندازی کرده اید. یک وب سرور سبک که بطور کامل صرفا با پایتون نوشته شده است. ما این مورد را با جنگو تلفیق کرده ایم تا بتوانید بدون نیاز به پیکر بندی سرور - مانند آپاچی - تا زمانی که برای تولید نهایی آماده شوید همه چیز را به سرعت توسعه دهید.

اکنون زمان خوبی است که دقت کنید: از این سرور برای محیط تولید استفاده نکنید. این فقط برای استفاده هنگام توسعه در نظر گرفته شده است. (ما در ساخت فریم ورک های وب فعالیت میکنیم نه سرورهای وب)

اکنون که سرور در حال اجرا است، با مرور گر خود به آدرس http://127.0.0.1:8000/ مراجعه کنید. صفحه تبریک! با موشکی که در حال پرتاب است. درست کار کرد.

تغییر پورت

بصورت پیش فرض، دستور runserver توسعه سرور و وبسایت را روی IP داخلی سیستم و پورت 8000 شروع می کند.

اگر می خواهید پورت سرور خود را تغییر دهید، آن را بصورت آرگومان به خط فرمان بفرستید. برای نمونه، دستور زیر سرور را روی پورت 8080 شروع می کند:

$ python manage.py runserver 8080

...\> py manage.py runserver 8080

اگر می خواهید IP سرور را تغییر دهید، آن را همراه با پورت به عنوان آرگومان پاس دهید. برای مثال، برای گوش دادن به تمام IP های عمومی و قابل رویت (که اگر بصورت سرگردان در حال اجراست یا می خواهید وبسایت خود را روی کامپیوتر دیگری روی شبکه به نمایش بگذارید) از دستور زیر استفاده کنید:

$ python manage.py runserver 0:8000

...\> py manage.py runserver 0:8000

0 کوتاه شده عبارت 0.0.0.0 است. راهنما و مستندات کامل برای توسعه سرور را می توانید در runserver پیدا کرده و به آن مراجعه کنید.

بارگذاری مجدد خودکار runserver

سرور توسعه داده شده کدهای پایتون را بصورت خودکار با هر درخواست بسته به نیاز بارگذاری مجدد می کند. شما نیازی نیست که سرور را به ازای هر بار تغییرات مجددا راه اندازی کنید تا تغییرات خود را ببینید. هر چند یک سری عملیات ها مانند اضافه کردن فایل راه اندازی مجدد نمی شوند، پس شما باید سرور را در این موارد دوباره راه اندازی کنید.

ساخت برنامه نظرسنجی

حال، محیط شما – پروژه – نصب شده است، شما قرار است شروع به کار کنید.

هر برنامه ای که شما در جنگو می نویسید شامل یک پکیج پایتون است که از یک قرارداد خاص پیروی می کند. جنگو با ابزاری همراه است که بطور خودکار ساختار دایرکتوری اصلی یک برنامه را تولید می کند، بنابراین می توانید به جای ایجاد دایرکتوری ها، روی نوشتن کد تمرکز کنید.

پروژه ها در مقابل برنامه ها

تفاوت یک پروژه و یک برنامه در جنگو چیست؟ منظور از برنامه یک وب اپلیکیشن است که که کاری را انجام می دهد – به عنوان مثال ، یک سیستم وبلاگ، یک پایگاه داده از سوابق عمومی، یا یک برنامه نظرسنجی کوچک. پروژه به مجموعه ای از تنظیمات و برنامه ها برای برای یک وب سایت خاص است. در واقع یک پروژه می تواند شامل چندین برنامه باشد. همینطور یک برنامه می تواند در چندین پروژه باشد.

برنامه های شما در هرجایی از Python path می توانند وجود داشته و اجرا شوند. در این آموزش، ما برنامه نظرسنجی خود را در همان دایرکتوری فایل manage.py همانند شما ایجاد خواهیم کرد تا بتوان آن را به عنوان ماژول سطح بالای خود به جای زیر مجموعه mysite وارد کرد.

برای ساخت برنامه خود، ابتدا مطمئن باشید که در دایرکتوری manage.py مشابهی هستیم و سپس دستور زیر را وارد در خط فرمان وارد کنید:

$ python manage.py startapp polls

...\> py manage.py startapp polls

با این کار یک دایرکتوری به نام polls بصورت زیر ایجاد می شود:

polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py

این ساختار دایرکتوری برنامه نظرسنجی را در خود جای خواهد داد.

اولین view خود را بنویسید

بیایید اولین view وب سایت را بنویسیم. فایل polls/views.py را باز کنید و و کد پایتون زیر را در آن قرار دهید:

polls/views.py
from django.http import HttpResponse


def index(request):
    return HttpResponse("Hello, world. You're at the polls index.")

این ساده ترین view ممکن در جنگو است. برای فراخوانی view، باید آن را به URL متصل کنیم - برای این کار ما به URLconf نیاز داریم.

برای ساخت URLconf در دایرکتوری polls، فایلی بنام urls.py بسازید. دایرکتوری برنامه نظرسنجی شما باید بشکل زیر در بیاید:

polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    urls.py
    views.py

در فایل polls/urls.py کد زیر را قرار دهید:

polls/urls.py
from django.urls import path

from . import views

urlpatterns = [
    path('', views.index, name='index'),
]

مرحله بعد URLconf ساخته شده باید به ماژول polls.urls اشاره کند. در فایل mysite/urls.py باید django.urls.include را بالای فایل ایمپورت کرده و متد include() را در لیست urlpatterns اضافه کنید، بنابراین داریم:

mysite/urls.py
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path('polls/', include('polls.urls')),
    path('admin/', admin.site.urls),
]

متد include() اجازه ارجاع به بقیه ی URLconfs ها را می دهد. هر زمان که جنگو متد include() را فراخوانی کند، هر بخشی از URL که تا آن نقطه مطابقت داشته باشد را قطع کرده و رشته آدرس باقیمانده را برای پردازش بیشتر به URLconf موجود می فرستد.

ایده اصلی include() این است که اتصال-و-اجرای URLs هارا آسان کنیم. از آنجاییکه نظرسنجی ها در URLconf خودشان در (polls/urls.py) هستند، میتوانند در مسیر “/polls/”، یا در “/fun_polls/”، یا در مسیر “/content/polls/”، یا در هر مسیر اصلی دیگری در دایرکتوری جنگو قرار بگیرند، و برنامه همچنان قادر به کار کردن خواهد بود.

چه زمانی از include() استفاده کنیم؟

وقتی الگوهای دیگر URL را اضافه می کنید، باید همیشه از include() استفاده کنید. بجز admin.site.urls که تنها استثنا در این مورد است.

شما اکنون view ی index را به URLconf متصل کرده اید. با دستور زیر بررسی کنید که کار می کند یا خیر:

$ python manage.py runserver

...\> py manage.py runserver

در مرورگر خود به آدرس http://localhost:8000/polls/ رفته، و باید متن “Hello, world. You’re at the polls index.” را که در view ی index تعریف کرده بودید روی صفحه مشاهده کنید.

صفحه یافت نشد؟

اگر خطایی در صفحه مشاهده کردید، بررسی کنید که آدرس مرورگر شما با آدرس http://localhost:8000/polls/ مطابقت داشته باشد و http://localhost:8000/ نباشد.

به متد path() باید 4 آرگومان فرستاده شود، 2 آرگومان: route و view ضروری بوده، ولی دو آرگومان: kwargs و name اختیاری هستند. خوب است در اینجا بررسی کنیم که این آرگومان ها برای چه هستند.

آرگومان path() : route

route رشته ای است که حاوی یک الگوی URL است. جنگو هنگام پردازش یک درخواست، از اولین الگو در urlpatterns شروع کرده و تا پایین فهرست را می خواند و URL درخواستی را با هر الگویی که در لیست موجود است مقایسه می کند تا زمانیکه یک الگوی منطبق پیدا کند.

الگو ها پارامتر های GET و POST یا نام دامنه را جستجو نمی کنند. برای مثال، در یک درخواست به https://www.example.com/myapp/، URLconf به دنبال myapp/ می گردد. همچنین در یک درخواست به https://www.example.com/myapp/?page=3، URLconf به دنبال myapp/ نیز می گردد.

آرگومان path() : view

زمانیکه جنگو یک الگوی منطبق را پیدا می کند، تابع view مشخص شده را با شی HttpRequest به عنوان اولین آرگومان و هر مقدار “گرفته شده” از مسیر را به عنوان آرگومان کلیدی فراخوانی می کند. در ادامه مثالی از این موضوع خواهیم زد.

آرگومان path() : kwargs

آرگومان های کلیدی دلخواه را می توان در یک فرهنگ لغت به view هدف منتقل کرد. ما قرار نیست از این ویژگی جنگو در آموزش استفاده کنیم.

آرگومان path() : name

نام گذاری URL به شما امکان می دهد بدون ابهام از قسمت های دیگر جنگو، به ویژه درون قالب ها، به آن مراجعه کنید. این ویژگی قدرتمند به شما این امکان را می دهد که در حالیکه تنها یک فایل را لمس می کنید، تغییرات کلی در الگوهای URL پروژه خود ایجاد کنید.

هنگامی که اصول اولیه جریان درخواست و پاسخ را یاد گرفتید، برای شروع کار با پایگاه داده، part 2 of this tutorial را بخوانید.

Github repository