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

Повторное использование — это важно

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

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

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

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

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

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

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

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

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

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

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

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

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

   Выбор имени для приложения

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

   Метки приложений (то есть последняя часть пути с точками к пакетам приложений) должны быть уникальными в INSTALLED_APPS. Не используйте те же метки, что и у пакетов contrib Django, например 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):
       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>=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.12"
   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.12",
       "Programming Language :: Python :: 3.13",
       "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.

   Многие проекты Python, в том числе Django и сам Python, используют Sphinx для сборки документации. Если вы решите использовать Sphinx, то сможете ссылаться на документацию Django, настроив Intersphinx и добавив значение Django в параметр intersphinx_mapping вашего проекта:

   intersphinx_mapping = {
       # ...
       "django": (
           "https://docs.djangoproject.com/en/stable/",
           None,
       ),
   }
   

   После этого можно будет создавать перекрёстные ссылки на конкретные элементы, как и в документации Django, например «:attr:`django.test.TransactionTestCase.databases`».

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 (PyPI). Для этого есть хороший учебник.

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

Ранее мы установили django-polls в пользовательскую библиотеку. У такого подхода есть некоторые недостатки:

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

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