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

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

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

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

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

Многократное использование — это образ жизни в Python. Python Package Index (PyPI) содержит широкий спектр пакетов, которые вы можете использовать в своих собственных программах Python. Ознакомьтесь с Django Packages, чтобы найти готовые многократно используемые приложения, которые можно включить в свой проект. Сам 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 packages, например, 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, 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.10
       Programming Language :: Python :: 3.11
       Programming Language :: Python :: 3.12
       Topic :: Internet :: WWW/HTTP
       Topic :: Internet :: WWW/HTTP :: Dynamic Content
   
   [options]
   include_package_data = true
   packages = find:
   python_requires = >=3.10
   install_requires =
       Django >= X.Y  # Replace "X.Y" as appropriate
   

   django-polls/setup.py

   from setuptools import setup
   
   setup()
   

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

   django-polls/MANIFEST.in

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

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

   recursive-include docs *
   

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

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

Дополнительную информацию о упаковке можно найти в руководстве Python Tutorial on Packaging and Distributing Projects.

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

Поскольку мы переместили каталог 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, каждая со своей копией библиотек и пространства имен пакетов.