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

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

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

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

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

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

Предположим, вы начинаете новый проект, которому необходимо приложение polls, подобное тому, над которым мы работаем. Как сделать это приложение повторно используемым? К счастью, вы уже многое сделали. В Учебнике 1 мы увидели, как мы можем отделить polls от 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.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, например, 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. Далее мы создадим файлы 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:
   python_requires = >=3.6
   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 с помощью виртуальной среды

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

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

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