Углублённый учебник: Как создавать повторно используемые приложения

Этот углублённый учебник продолжает там, где закончился Учебник 8. Мы превратим наш веб-опрос в автономный пакет Python, который вы сможете повторно использовать в новых проектах и делиться им с другими людьми.

Если вы недавно не выполнили Учебники 1–7, мы рекомендуем вам их пересмотреть, чтобы ваш примерный проект соответствовал описанному ниже.

Повторное использование имеет значение

Разработка, создание, тестирование и сопровождение веб-приложения — это большая работа. Многие проекты Python и Django сталкиваются с общими проблемами. Разве не здорово было бы сохранить часть этой повторяющейся работы?

Повторное использование — неотъемлемая часть Python. Индекс пакетов Python (PyPI) содержит широкий спектр пакетов, которые вы можете использовать в собственных программах Python. Ознакомьтесь с пакетами Django, чтобы найти готовые повторно используемые приложения, которые можно включить в свой проект. Сам Django также является обычным пакетом Python. Это означает, что вы можете взять существующие пакеты Python или приложения Django и включить их в свой собственный веб-проект. Вам нужно будет написать только те части, которые делают ваш проект уникальным.

Предположим, вы начинаете новый проект, которому нужно приложение опросов, как то, над которым мы работали. Как сделать это приложение повторно используемым? К счастью, вы уже почти на пути. В Учебнике 1 мы увидели, как мы можем отделить приложение опросов от URLconf-конфигурации проекта с помощью include. В этом учебнике мы сделаем дальнейшие шаги, чтобы приложение было легко использовать в новых проектах и готово к публикации, чтобы другие могли установить и использовать его.

Ваш проект и ваше повторно используемое приложение

После предыдущих учебников наш проект должен выглядеть так:

mysite/
    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

Вы создали mysite/templates в Учебнике 7, и polls/templates в Учебнике 3. Теперь, возможно, становится понятнее, почему мы выбрали отдельные директории шаблонов для проекта и приложения: всё, что относится к приложению опросов, находится в polls. Это делает приложение автономным и более удобным для переноса в новый проект.

Директорию polls теперь можно скопировать в новый проект Django и сразу использовать повторно. Однако она ещё не совсем готова для публикации. Для этого нам нужно упаковать приложение, чтобы другим было легко его установить.

Установка необходимых компонентов

Текущее состояние упаковки Python несколько запутанно, с различными инструментами. В этом учебнике мы будем использовать setuptools для сборки нашего пакета. Это рекомендуемый инструмент для упаковки (слитый с веткой distribute). Мы также будем использовать pip для установки и удаления. Вам следует установить эти два пакета сейчас. Если вам нужна помощь, вы можете обратиться к инструкции по установке Django с помощью pip. Вы можете установить setuptools аналогичным образом.

Упаковывание вашего приложения

Упаковка Python относится к подготовке вашего приложения в определённом формате, который можно легко установить и использовать. Сам Django упаковывается аналогичным образом. Для небольшого приложения, как опросы, этот процесс не слишком сложен.

1. Сначала создайте родительскую директорию для пакета вне вашего проекта Django. Назовите эту директорию django-polls.

   Выбор имени для вашего приложения

   При выборе имени для вашего пакета проверьте PyPI, чтобы избежать конфликтов имён с существующими пакетами. Мы рекомендуем использовать префикс django- для имён пакетов, чтобы идентифицировать ваш пакет как специфичный для Django, и соответствующий префикс django_ для имени вашего модуля. Например, пакет django-ratelimit содержит модуль django_ratelimit.

   Метки приложений (то есть последняя часть составного пути до пакетов приложений) обязательно должны быть уникальными в INSTALLED_APPS. Избегайте использования той же метки, что и у каких-либо пакетов Django contrib-пакетов, например auth, admin, или messages.

2. Переместите директорию polls в директорию django-polls и переименуйте её в django_polls.

3. Отредактируйте django_polls/apps.py так, чтобы name ссылался на новое имя модуля, и добавьте label, чтобы указать короткое имя приложения:

   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"
   

4. Создайте файл django-polls/README.rst со следующим содержимым:

   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.
   

5. Создайте файл django-polls/LICENSE. Выбор лицензии выходит за рамки этого учебника, но достаточно сказать, что код, выпущенный публично без лицензии, бесполезен. Django и многие совместимые с Django приложения распространяются по лицензии BSD; однако, вы можете выбрать свою лицензию. Просто имейте в виду, что ваш выбор лицензии повлияет на то, кто сможет использовать ваш код.

6. Далее, мы создадим файл pyproject.toml, который описывает, как собрать и установить приложение. Полное объяснение этого файла выходит за рамки данного учебника, но Руководство пользователя по упаковке Python даёт хорошее объяснение. Создайте файл django-polls/pyproject.toml со следующим содержимым:

   django-polls/pyproject.toml

   [build-system]
   requires = ["setuptools>=61.0"]
   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",
       "Topic :: Internet :: WWW/HTTP",
       "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
   ]
   
   [project.urls]
   Homepage = "https://www.example.com/"
   

7. По умолчанию в пакет включаются многие общие файлы и модули Python. Для включения дополнительных файлов нам потребуется создать файл MANIFEST.in. Для включения шаблонов и статических файлов создайте файл django-polls/MANIFEST.in со следующим содержимым:

   django-polls/MANIFEST.in

   recursive-include django_polls/static *
   recursive-include django_polls/templates *
   

8. Необязательно, но рекомендуется включать подробную документацию к вашему приложению. Создайте пустую директорию django-polls/docs для будущей документации.

   Обратите внимание, что директория docs не будет включена в ваш пакет, если вы не добавите в неё какие-либо файлы. Многие приложения Django также предоставляют свою документацию онлайн через сайты, такие как readthedocs.org.

9. Проверьте, что пакет build установлен (python -m pip install build) и попробуйте собрать пакет, выполнив команду python -m build внутри django-polls. Это создаст директорию под названием dist и соберет ваш новый пакет в форматах исходного кода и бинарных файлов, django-polls-0.1.tar.gz и django_polls-0.1-py3-none-any.whl.

Дополнительную информацию об упаковке см. в учебнике Python по упаковке и распространению проектов.

Использование собственного пакета

Так как мы переместили директорию polls из проекта, она больше не работает. Теперь мы исправим это, установив наш новый пакет django-polls.

1. Для установки пакета используйте pip (вы уже установили его, верно?):

   python -m pip install --user django-polls/dist/django-polls-0.1.tar.gz
   

2. Обновите mysite/settings.py так, чтобы он указывал на новое имя модуля:

   INSTALLED_APPS = [
       "django_polls.apps.PollsConfig",
       ...,
   ]
   

3. Обновите mysite/urls.py так, чтобы он указывал на новое имя модуля:

   urlpatterns = [
       path("polls/", include("django_polls.urls")),
       ...,
   ]
   

4. Запустите сервер разработки, чтобы убедиться, что проект продолжает работать.

Публикация вашего приложения

Теперь, когда мы упаковали и протестировали django-polls, оно готово для публикации! Если это был не просто пример, вы теперь можете:

• Отправить пакет другу по электронной почте.
• Загрузить пакет на свой сайт.
• Опубликовать пакет в общедоступном репозитории, например, в Python Package Index (PyPI). packaging.python.org содержит хороший учебник по выполнению этой операции.

Установка пакетов Python с виртуальной средой

Ранее мы установили django-polls в качестве пользовательской библиотеки. Это имеет некоторые недостатки:

• Изменение пользовательских библиотек может повлиять на другие программы Python на вашей системе.
• Вы не сможете запустить несколько версий этого пакета (или других с таким же именем).

Как правило, такие ситуации возникают только при одновременном обслуживании нескольких проектов Django. В таких случаях лучшим решением является использование venv. Этот инструмент позволяет поддерживать несколько изолированных сред Python, каждая со своей копией библиотек и пространства имен пакетов.