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

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

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

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

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

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

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

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

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

mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        wsgi.py
    polls/
        __init__.py
        admin.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. Это делает приложение самодостаточным и упрощает его добавление в новый проект.

Каталог 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 simple 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. Далее мы создадим файлы setup.cfg и setup.py, которые описывают, как создать и установить приложение. Полное объяснение этих файлов выходит за рамки этого учебника, но в документации setuptools есть хорошее объяснение. Создайте файлы django-polls/setup.cfg и django-polls/setup.py со следующим содержимым:

   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.6
       Programming Language :: Python :: 3.7
       Programming Language :: Python :: 3.8
       Topic :: Internet :: WWW/HTTP
       Topic :: Internet :: WWW/HTTP :: Dynamic Content
   
   [options]
   include_package_data = true
   packages = find:
   

   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 по упаковке и распространению проектов на packaging.python.org.

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

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

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

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

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

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

   pip uninstall django-polls
   

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

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

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

Установка пакетов Python с помощью virtualenv

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

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

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