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

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

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

Многократное использование имеет значение

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

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

Допустим, вы начинаете новый проект, которому нужно приложение опросов, как то, над которым мы работаем. Как сделать это приложение многократно используемым? К счастью, вы уже на правильном пути. В Уроке 1 мы увидели, как мы можем отделить приложения опросов от конфигурации URL проекта, используя 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.gif
                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 упакован таким же образом. Для небольшого приложения, такого как polls, этот процесс не очень сложен.

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

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

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

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

2. Переместите каталог polls в каталог django-polls.

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

   django-polls/README.rst

   =====
   Polls
   =====
   
   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 = [
           ...,
           "polls",
       ]
   
   2. Include the polls URLconf in your project urls.py like this::
   
       path("polls/", include("polls.urls")),
   
   3. Run ``python manage.py migrate`` to create the polls models.
   
   4. Start the development server and visit http://127.0.0.1:8000/admin/
      to create a poll (you'll need the Admin app enabled).
   
   5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
   

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

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

   django-polls/pyproject.toml

   [build-system]
   requires = ['setuptools>=40.8.0']
   build-backend = 'setuptools.build_meta'
   

   django-polls/setup.cfg

   [metadata]
   name = django-polls
   version = 0.1
   description = A Django app to conduct web-based polls.
   long_description = file: README.rst
   url = https://www.example.com/
   author = Your Name
   author_email = yourname@example.com
   license = BSD-3-Clause  # Example license
   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.8
       Programming Language :: Python :: 3.9
       Topic :: Internet :: WWW/HTTP
       Topic :: Internet :: WWW/HTTP :: Dynamic Content
   
   [options]
   include_package_data = true
   packages = find:
   python_requires = >=3.8
   install_requires =
       Django >= X.Y  # Replace "X.Y" as appropriate
   

   django-polls/setup.py

   from setuptools import setup
   
   setup()
   

6. По умолчанию в пакет включаются только модули и пакеты Python. Чтобы включить дополнительные файлы, нам нужно создать файл MANIFEST.in. В документации setuptools, упомянутой на предыдущем шаге, подробно описывается этот файл. Чтобы включить шаблоны, файлы README.rst и LICENSE, создайте файл django-polls/MANIFEST.in со следующим содержимым:

   django-polls/MANIFEST.in

   include LICENSE
   include README.rst
   recursive-include polls/static *
   recursive-include polls/templates *
   

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

   recursive-include docs *
   

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

8. Попробуйте создать свой пакет с помощью python setup.py sdist (запустите изнутри django-polls). Это создаст каталог dist и создаст ваш новый пакет, django-polls-0.1.tar.gz.

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

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

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

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

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

2. Если всё прошло успешно, ваш проект Django должен снова работать правильно. Запустите сервер, чтобы подтвердить это.

3. Чтобы удалить пакет, используйте pip:

   python -m pip uninstall django-polls
   

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

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

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

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

Ранее мы устанавливали приложение опросов как библиотеку пользователя. Это имеет некоторые недостатки:

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

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