Ten tutorial dla zaawansowanych zaczyna się, gdzie Tutorial 8 się skończył. Będziemy przerabiać naszą web-ankietę na samodzielny pakiet Pythona, który będziesz mógł wykorzystać w nowym projekcie i którym będziesz mógł podzielić się z innymi.
If you haven’t recently completed Tutorials 1–8, we encourage you to review these so that your example project matches the one described below.
Zaprojektować, zbudować, przetestować i utrzymywać aplikację webową to bardzo dużo pracy. Wiele projektów w Pythonie i Django napotyka wspólne problemy. Czy nie byłoby super, jeśli moglibyśmy oszczędzić części tej powtarzanej pracy?
Ponowne wykorzystanie to sposób na życie w Pythonie. Python Package Index (PyPI) zawiera obszerny zakres pakietów, które możesz wykorzystać w swoich własnych pythonowych programach. Sprawdź w Django Packages istniejące aplikacje gotowe do wykorzystania, które mógłbyś wcielić w swój projekt. Samo Django także jest normalnym pythonowym pakietem. To znaczy, że możesz wziąć istniejące pakiety Pythona lub aplikacje Django i złożyć z nich swój własny projekt webowy. Musisz jedynie napisać części, które uczynią twój projekt unikalnym.
Powiedzmy, że zaczynałeś nowy projekt, który potrzebował aplikacji z ankietą, takiej jak ta, nad którą pracowaliśmy. Jak uczynić tą aplikację gotową do wykorzystania przez innych? Na szczęście, jesteśmy już na dobrej drodze. W Tutorialu 1 widzieliśmy jak możemy wydzielić ankiety z URLconfa na poziomie projektu przez użycie include
. W tym tutorialu poczynimy dalsze kroki, aby uczynić aplikację łatwą do użycia w nowych projektach i gotową do publikacji, aby inni mogli ją zainstalować i używać.
Pakiet? Aplikacja?
Pythonowy package jest sposobem na zgrupowanie związanego kodu Pythona na potrzeby łatwego ponownego użycia. Pakiet zawiera jeden lub więcej plików z kodem Pythona (znane także jako „moduły”).
Pakiet można zaimportować przez import foo.bar
lub from foo import bar
. Aby katalog (jak polls
) stał się pakietem, musi zawierać specjalny plik __init__.py
, który może być pusty.
Aplikacja Django jest pakietem Pythona, który jest szczególnie przeznaczony do użycia w projekcie Django. Aplikacja może używać powszechnych w Django konwencji, jak posiadanie podmodułów models
, tests
, urls
i views
.
Dalej będziemy używać pojęcia pakietowanie, aby opisać proces robienia pakietu Pythona łatwego do instalacji dla innych. Mamy świadomość, że może to być nieco mylące.
Po poprzednich tutorialach, nasz projekt powinien wyglądać tak:
djangotutorial/
manage.py
mysite/
__init__.py
settings.py
urls.py
asgi.py
wsgi.py
polls/
__init__.py
admin.py
apps.py
migrations/
__init__.py
0001_initial.py
models.py
static/
polls/
images/
background.png
style.css
templates/
polls/
detail.html
index.html
results.html
tests.py
urls.py
views.py
templates/
admin/
base_site.html
You created djangotutorial/templates
in Tutorial 7, and polls/templates
in
Tutorial 3. Now perhaps it is clearer why we chose
to have separate template directories for the project and application:
everything that is part of the polls application is in polls
. It makes the
application self-contained and easier to drop into a new project.
Katalog polls
mógłby być teraz skopiowany do nowego projektu Django i od razu użyty. Ale nie jest zupełnie gotowy do bycia opublikowanym. Na tę potrzebę, musimy spakować naszą aplikację, aby ułatwić innym jej instalację.
Bieżący stan pakietowania w Pythonie jest nieco zagmatwany przez wiele narzędzi. Na potrzeby tego tutorialu, użyjemy setuptools, aby zbudować nasz pakiet. Są one zalecanym narzędziem pakietowania (zmergowane z forkiem distribute
). Będziemy też używać pip, aby go zainstalować i odinstalować. Powinieneś teraz zainstalować te dwa pakiety. Jeśli potrzebujesz pomocy, możesz zajrzeć do jak zainstalować Django używając pipa. W ten sam sposób możesz zainstalować setuptools
.
Pythonowe pakietowanie oznacza przygotowane twojej aplikacji w określonym formacie, który będzie mógł być prosto zainstalowany i użyty. Samo Django jest zapakowane właśnie w ten sposób. Dla małej aplikacji jak ankiety, ten proces nie jest zbyt skomplikowany.
First, create a parent directory for the package, outside of your Django
project. Call this directory django-polls
.
Wybór nazwy dla twojej aplikacji
When choosing a name for your package, check PyPI to avoid naming
conflicts with existing packages. We recommend using a django-
prefix for package names, to identify your package as specific to
Django, and a corresponding django_
prefix for your module name. For
example, the django-ratelimit
package contains the
django_ratelimit
module.
Etykiety aplikacji (czyli ostatnia część kropkowanej ścieżki do pakietów aplikacji) musi być unikalna w INSTALLED_APPS
. Unikaj używania takich samych etykiet jak którykolwiek z pakietów contrib, na przykład auth
, admin
lub messages
.
Move the polls
directory into django-polls
directory, and rename it
to django_polls
.
Edit django_polls/apps.py
so that name
refers to the
new module name and add label
to give a short name for
the app:
django-polls/django_polls/apps.py
¶from django.apps import AppConfig
class PollsConfig(AppConfig):
default_auto_field = "django.db.models.BigAutoField"
name = "django_polls"
label = "polls"
Stwórz plik django-polls/README.rst
o następującej treści:
django-polls/README.rst
¶============
django-polls
============
django-polls is a Django app to conduct web-based polls. For each
question, visitors can choose between a fixed number of answers.
Detailed documentation is in the "docs" directory.
Quick start
-----------
1. Add "polls" to your INSTALLED_APPS setting like this::
INSTALLED_APPS = [
...,
"django_polls",
]
2. Include the polls URLconf in your project urls.py like this::
path("polls/", include("django_polls.urls")),
3. Run ``python manage.py migrate`` to create the models.
4. Start the development server and visit the admin to create a poll.
5. Visit the ``/polls/`` URL to participate in the poll.
Stwórz plik django-polls/LICENSE
. Wybór licencji jest poza zakresem tego tutorialu, ale wystarczy powiedzieć, że kod wydany publicznie bez licencji jest bezużyteczny. Django i wiele kompatybilnych z Django aplikacji są rozpowszechniane na licencji BSD, aczkolwiek ty możesz wybrać swoją własną licencję. Bądź tylko świadom, że wybór licencji będzie miał wpływ na to, kto może używać twój kod.
Next we’ll create the pyproject.toml
file which details how to build and
install the app. A full explanation of this file is beyond the scope of this
tutorial, but the Python Packaging User Guide has a good
explanation. Create the django-polls/pyproject.toml
file with the
following contents:
django-polls/pyproject.toml
¶[build-system]
requires = ["setuptools>=69.3"]
build-backend = "setuptools.build_meta"
[project]
name = "django-polls"
version = "0.1"
dependencies = [
"django>=X.Y", # Replace "X.Y" as appropriate
]
description = "A Django app to conduct web-based polls."
readme = "README.rst"
requires-python = ">= 3.10"
authors = [
{name = "Your Name", email = "yourname@example.com"},
]
classifiers = [
"Environment :: Web Environment",
"Framework :: Django",
"Framework :: Django :: X.Y", # Replace "X.Y" as appropriate
"Intended Audience :: Developers",
"License :: OSI Approved :: BSD License",
"Operating System :: OS Independent",
"Programming Language :: Python",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3 :: Only",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Topic :: Internet :: WWW/HTTP",
"Topic :: Internet :: WWW/HTTP :: Dynamic Content",
]
[project.urls]
Homepage = "https://www.example.com/"
Many common files and Python modules and packages are included in the
package by default. To include additional files, we’ll need to create a
MANIFEST.in
file. To include the templates and static files, create a
file django-polls/MANIFEST.in
with the following contents:
django-polls/MANIFEST.in
¶recursive-include django_polls/static *
recursive-include django_polls/templates *
It’s optional, but recommended, to include detailed documentation with your
app. Create an empty directory django-polls/docs
for future
documentation.
Zwróć uwagę, że katalog docs
nie zostanie zawarty w twoim pakiecie dopóki nie dodasz do niego jakichś plików. Wiele aplikacji Django dostarcza swoją dokumentację online przez strony takie jak readthedocs.org.
Many Python projects, including Django and Python itself, use Sphinx to build
their documentation. If you choose to use Sphinx you can link back to the
Django documentation by configuring Intersphinx
and including a value for Django in your project’s intersphinx_mapping
value:
intersphinx_mapping = {
# ...
"django": (
"https://docs.djangoproject.com/en/stable/",
None,
),
}
With that in place, you can then cross-link to specific entries, in the
same way as in the Django docs, such as
„:attr:`django.test.TransactionTestCase.databases`
”.
Check that the build package is installed (python -m pip install
build
) and try building your package by running python -m build
inside
django-polls
. This creates a directory called dist
and builds your
new package into source and binary formats, django_polls-0.1.tar.gz
and
django_polls-0.1-py3-none-any.whl
.
Aby dowiedzieć się więcej na temat pakowania, zobacz tutorial Packaging Python Projects.
Odkąd przenieśliśmy katalog polls
poza projekt, nie działa. Naprawimy to teraz instalując nasz nowy pakiet django-polls
.
Instalowanie jako bibliotekę użytkownika
Poniższe kroki zainstalują django-polls
jako bibliotekę użytkownika. Instalacja bibliotek per użytkownik posiada sporo zalet w porównaniu do instalacji paczek per system jak np. możliwość instalacji bibliotek w systemie, w którym nie posiadasz uprawnień administracyjnych oraz zapobieganie wpływu biblioteki na system i innych jego użytkowników.
Pamiętaj, że instalacja per użytkownik nadal może wpłynąć na narzędzia systemowe uruchamiane przez tego samego użytkownika, więc używanie środowiska wirtualnego jest bardziej niezawodnym rozwiązaniem (patrz niżej).
Aby zainstalować pakiet, użyj pipa (już go zainstalowałeś, prawda?):
python -m pip install --user django-polls/dist/django_polls-0.1.tar.gz
Update mysite/settings.py
to point to the new module name:
INSTALLED_APPS = [
"django_polls.apps.PollsConfig",
...,
]
Update mysite/urls.py
to point to the new module name:
urlpatterns = [
path("polls/", include("django_polls.urls")),
...,
]
Run the development server to confirm the project continues to work.
Teraz, kiedy już spakowaliśmy i przetestowaliśmy django-polls
, są gotowe do podzielenia się ze światem! Gdyby to nie był tylko przykład, mógłbyś teraz:
Wyślij e-mail z pakietem do znajomego.
Załaduj pakiet na swoją stronę.
Opublikuj pakiet w publicznym repozytorium, takim jak Python Package Index (PyPI). packaging.python.org ma dobry tutorial na ten temat.
Earlier, we installed django-polls
as a user library. This has some
disadvantages:
Modyfikowanie bibliotek użytkownika może wpłynąć na inne oprogramowanie Python w twoim systemie.
Nie będziesz w stanie uruchamiać wielu wersji tego pakietu (lub innych o takiej samej nazwie).
Zazwyczaj takie sytuacje zdarzają się tylko kiedy utrzymujesz kilka projektów Django. W takiej sytuacji najlepszym rozwiązaniem jest venv <python:tutorial/venv>. To narzędzie pozwala utrzymywać wiele izolowanych środowisk Pythona, każdy ze swoimi własnymi kopiami bibliotek i przestrzeniami nazw dla pakietów.
cze 09, 2025