# Django 4.2.9.dev20231204082947 - dokumentacja

# Pisanie pierwszej aplikacji Django, część 1.

Nauczmy się na przykładzie.

Z pomocą tego tutoriala przeprowadzimy cię przez stworzenie prostej aplikacji ankietowej.

Będzie się ona składać z dwóch części:

- Publicznej strony, która pozwala ludziom obejrzeć ankiety i głosować w nich.
- Panelu administracyjnego, który pozwala ci dodawać, zmieniać i usuwać ankiety.

Będziemy zakładać, że masz już zainstalowane Django. Możesz sprawdzić, czy Django jest zainstalowane i w jakiej wersji uruchamiając następującą komendę w prompcie powłoki (wskazywanym przez prefix $):

/ 

    $ python -m django --version

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

Jeśli Django jest zainstalowane, powinieneś zobaczyć wersję swojej instalacji. Jeśli nie jest, dostaniesz błąd „No module named django”.

Ten tutorial jest napisany dla Django 4.2, które wspiera Pythona 3.8 i wyższe. Jeśli wersja Django się nie zgadza, możesz przełączyć się na swoją wersję Django używając przełącznika wersji w prawym dolnym rogu tej strony lub możesz zaktualizować Django do najnowszej wersji. Jeśli używasz starszej wersji Pythona, sprawdź Której wersji Pythona mogę użyć z Django?, aby znaleźć kompatybilną wersję Django.

Zobacz Jak zainstalować Django, by znaleźć wskazówki jak usunąć stare wersje Django i zainstalować nową.

Gdzie szukać pomocy:

Jeśli masz trudności w przejściu tego tutorialu, przejdź do sekcji Uzyskiwanie pomocy często zadawanych pytań.

## Tworzenie projektu

Jeśli po raz pierwszy korzystasz z Django, będziesz musiał zająć się wstępną konfiguracją. Konkretnie, będziesz potrzebował wygenerować trochę kodu, który stworzy projekt Django – zbiór ustawień dla instacji Django, wliczając konfigurację bazy danych, ustawienia specyficzne dla Django i specyficzne dla aplikacji.

Z linii komend, wejdź `cd` do katalogu, gdzie chciałbyś przechowywać swój kod, następnie uruchom następującą komendę:

/ 

    $ django-admin startproject mysite

    ...\> django-admin startproject mysite

Stworzy ona katalog `mysite` w twoim bieżącym katalogu. Jeśli nie zadziałała, zobacz Problemy z uruchomieniem django-admin.

Informacja

Musisz unikać nazywania projektów tak samo jak wbudowane w Pythona albo Django komponenty. W szczególności znaczy to, że powinieneś unikać używania nazw jak `django` (co wejdzie w konflikt z samym Django) lub `test` (wejdzie w konflikt z wbudowanym pakietem Pythona).

Gdzie powinien żyć ten kod?

Jeśli w przeszłości używałeś zwykłego starego PHP (bez użycia nowoczesnych frameworków), prawdopodobnie zwykłeś umieszczać kod w głównym katalogu serwera WWW (takim jak `/var/www`). W Django nie robi się w ten sposób. Nie jest dobrym pomysłem umieszczać jakiegokolwiek z tego kodu Pythona w katalogu głównym serwera WWW, ponieważ stwarza to ryzyko pojawienia się możliwości, aby ktoś był w stanie widzieć twój kod w Internecie. Nie jest to bezpieczne.

Umieść swój kod w jakimś katalogu poza katalogiem głównym, na przykład w `/home/mycode`.

Spójrzmy co stworzyło `startproject`:

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

Te pliki to:

- Zewnętrzny katalog główny `mysite/` jest pojemnikiem na twój projekt. Jego nazwa nie ma znaczenia dla Django; możesz zmienić jego nazwę na dowolną, jaką chcesz.
- `manage.py`: Narzędzie linii komend, które pozwala ci oddziaływać z tym projektem Django na wiele sposobów. Możesz przeczytać szczegóły na temat `manage.py` w django-admin and manage.py.
- Wewnętrzny katalog `mysite/` jest właściwym pakietem Pythona dla twojego projektu. Jego nazwa jest nazwą pakietu Pythona, którą musisz używać, aby zaimportować cokolwiek w tym pakiecie (np. `mysite.urls`).
- `mysite/__init__.py`: Pusty plik, który mówi Pythonowi, że ten katalog powinien być uważany za pakiet Pythona. Jeśli jesteś początkujący w Pythonie, przeczytaj więcej o pakietach w oficjalnej dokumentacji Pythona.
- `mysite/settings.py`: Ustawienia/konfiguracja dla tego projektu Django. Django settings powie ci wszystko o tym, jak działają ustawienia.
- `mysite/urls.py`: Deklaracje URL-i dla tego projektu Django; „spis treści” twojej strony opartej na Django. Możesz przeczytać więcej o URL-ach w URL dispatcher.
- `mysite/asgi.py`: Punkt wejściowy dla serwerów WWW kompatybilnych z ASGI do serwowania twojego projektu. Zobacz Jak wdrażać z ASGI po więcej szczegółów.
- `mysite/wsgi.py`: Punkt wejściowy dla serwerów WWW kompatybilnych z WSGI do serwowania twojego projektu. Zobacz Jak wdrażać z WSGI dla większej ilości szczegółów.

## Serwer deweloperski

Zweryfikujmy czy twój projekt Django działa. Przejdź do zewnętrzenego katalogu `mysite`, jeśli jeszcze tego nie zrobiłeś, i uruchom następujące polecenia:

/ 

    $ python manage.py runserver

    ...\> py manage.py runserver

Zobaczysz następujące wyjście w linii komend:

    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.

    grudnia 04, 2023 - 15:50:53
    Django version 4.2, using settings 'mysite.settings'
    Starting development server at http://127.0.0.1:8000/
    Quit the server with CONTROL-C.

Informacja

Zignoruj na razie ostrzeżenie o niezastosowanych migracjach bazy danych; zajmiemy się bazą danych za chwilę.

Wystartowałeś serwer deweloperski Django, lekki web-serwer napisany w całości w Pythonie. Zawarliśmy go w Django, abyś mógł dewelopować rzeczy błyskawicznie, nie musząc zajmować się konfiguracją produkcyjnego serwera – jak na przykład Apache – dopóki nie będziesz gotowy na produkcję.

Teraz jest dobry moment, by zwrócić na to uwagę: nie używaj tego serwera w czymkolwiek podobnym do produkcyjnego środowiska. Jest on przewidziany tylko do użytku podczas dewelopmentu. (Jesteśmy w świecie tworzenia web-frameworków, nie web-serwerów.)

Kiedy serwer jest już uruchomiony, odwiedź http://127.0.0.1:8000/ w swojej przeglądarce internetowej. Zobaczysz stronę „Gratulacje!” ze startującą rakietą. Zadziałało!

Zmiana portu

Domyślnie komenda `runserver` uruchamia serwer deweloperski na wewnętrznym IP na porcie 8000.

Jeśli chcesz zmienić port serwera, podaj go jako argument w linii komend. Na przykład, to polecenie uruchamia serwer na porcie 8080:

/ 

    $ python manage.py runserver 8080

    ...\> py manage.py runserver 8080

Jeśli chcesz zmienić IP serwera, podaj je razem z portem. Na przykład aby nasłuchiwać na wszystkich dostępnych publicznych IP (przydatne, jeśli używasz Vagranta lub chcesz zaprezentować swoją pracę na innych komputerach w sieci), użyj:

/ 

    $ python manage.py runserver 0.0.0.0:8000

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

Pełną dokumentację serwera deweloperskiego można znaleźć w dokumentacji `runserver`.

Automatyczne przeładowywanie `runserver`

Serwer deweloperski automatycznie przeładowuje kod Pythona dla każdego żądania, wedle potrzeby. Nie musisz restartować serwera, aby zmiany w kodzie miały efekt. Jednakże niektóre działania, jak dodawanie plików, nie powodują restartu, więc będziesz musiał zrestartować serwer w tych przypadkach.

## Tworzenie aplikacji Ankiety

Teraz, kiedy twoje środowisko – „projekt” – jest uruchomione, jesteś gotowy zabrać się do pracy.

Każda aplikacjia, którą piszesz w Django, składa się z pakietu Pythona, który realizuję pewną konwencję. Django zawiera narzędzie, które automatycznie generuje podstawową strukturę katalogów aplikacji, abyś mógł skupić się na pisaniu kodu zamiast na tworzeniu katalogów.

Projekty versus aplikacje

Jaka jest różnica pomiędzy projektem a aplikacją? Aplikacja jest aplikacją webową, która coś robi – na przykład system blogowy, baza danych publicznych wpisów lub mała aplikacja ankietowa. Projekt jest zbiorem konfiguracji i aplikacji dla konkretnej witryny. Projekt może zawierać wiele aplikacji. Aplikacja może być w wielu projektach.

Twoje aplikacje mogą żyć gdziekolwiek na twojej ścieżce Pythona. W tym tutorialu stworzymy aplikację ankietową w tym samym katalogu co twój plik `manage.py`, aby mogła być zaimportowana jako jego własny moduł najwyższego poziomu, zamiast podmodułu `mysite`.

Aby stworzyć swoją aplikację, upewnij się, że jesteś w tym samym katalogu co `manage.py` i wpisz tę komendę:

/ 

    $ python manage.py startapp polls

    ...\> py manage.py startapp polls

Stworzy ona katalog `polls`, który jest tak rozplanowany:

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

Ta struktora katalogów będzie domem dla aplikacji ankietowej.

## Napisz swój pierwszy widok

Napiszmy pierwszy widok. Otwórz plik `polls/views.py` i umieść tam następujący pythonowy kod:

`polls/views.py`

    from django.http import HttpResponse

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

To jest najprostszy widok, jaki jest możliwy w Django. Aby go wywołać, potrzebujemy zmapować go na URL – i do tego potrzebujemy URLconf.

Aby stworzyć URLconf w katalogu ankiet, stwórzmy plik o nazwie `urls.py`. Katalog twojej aplikacji powinien teraz wyglądać tak:

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

W pliku `polls/urls.py` zawrzyj następujący kod:

`polls/urls.py`

    from django.urls import path

    from . import views

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

Następnym krokiem jest wskazanie URLconfowi w korzeniu na moduł `polls.urls`. W `mysite/urls.py` dodaj import dla `django.urls.include` i wstaw `include()` na listę `urlpatterns`, aby mieć:

`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),
    ]

Funkcja `include()` function pozwala na odniesienia do innych URLconfów. Kiedykolwiek Django napotyka `include()`, odcina tę część URL-a, która została dopasowana do tego punktu i wysyła pozostłą część ciągu znaków do zaincludowanego URLconfa, do dalszego przetworzenia.

Pomysłem leżącym za `include()` jest ułatwienie podłączania URL-i. Skoro ankiety są w swoim własnym URLconfie (`polls/urls.py`), mogą być umieszczone pod „/polls/” lub pod „/fun_polls/” lub pod „/content/polls/” lub dowolnym innym początkiem ścieżki i aplikacja wciąż będzie działać.

Kiedy używać `include()`

Powinieneś używać `include()` zawsze, gdy uwzględniasz inne wzorce URL. `admin.site.urls` jest jedynym wyjątkiem od tej reguły.

Podłączyłeś właśnie widok `index` do URLconf. Zweryfikuj, czy działa, uruchamiając następujące polecenie:

/ 

    $ python manage.py runserver

    ...\> py manage.py runserver

Przejdź do http://localhost:8000/polls/ w swojej przeglądarce. Powinieneś zobaczyć napis „Hello, world. You’re at the polls index.”, który zdefiniowałeś w widoku `index`.

Strona nie została znaleziona?

Jeśli dostajesz tutaj stronę błędu, upewnij się, że wchodzisz na http://localhost:8000/polls/, a nie na http://localhost:8000/.

Do funkcji `path()` są przekazane cztery argumenty, dwa wymagane: `route` i `view` oraz dwa opcjonalne: `kwargs` i `name`. Warto w tym momencie dowiedzieć się, do czego służą.

### Argument `path()`: `route`

`route` jest ciągiem znaków, który zawiera wzorzec URL. Django zaczyna od pierwszego wzorca i idzie w dół listy, porównując zażądany URL z wszystkimi wzorcami aż odnajdzie taki, który pasuje.

Wzorce nie przeszukują parametrów GET i POST lub nazwy domeny. Na przykład, w żądaniu do `https://www.example.com/myapp/`, URLconf będzie szukał `myapp/`. W żądaniu do `https://www.example.com/myapp/?page=3`, URLconf też będzie szukał `myapp/`.

### Argument `path()`: `view`

Kiedy Django znajdzie pasujący wzorzec, wywołuje podaną funkcję widoku z obiektem `HttpRequest` jako pierwszym argumentem i dowolnymi „złapanymi” wartościami ze ścieżki jako argumentami nazwanymi. Za chwilę damy tego przykład.

### Argument `path()`: `kwargs`

Arbitralne argumenty słownikowe mogą być przekazane w słowniku do docelowego widoku. Nie będziemy używać tej funkcjonalności Django w tym tutorialu.

### Argument `path()`: `name`

Nazwanie twojego URL-a pozwala odwołać się do niego jednoznacznie z każdego miejsca w Django, szczególnie z wnętrza szablonów. Ta potężna cecha pozwala ci na robienie globalnych zmian we wzorcach URL projektu przez zmianę w pojedynczym pliku.

Jeśli czujesz się dobrze z przepływem żądań i odpowiedzi, przeczytaj drugą część tego tutoriala, aby zacząć pracę z bazą danych.