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

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

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

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

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

Повторное использование – это неотъемлемая часть Python. Индекс пакетов Python (PyPI) содержит обширный набор пакетов, которые можно использовать в собственных программах Python. Ознакомьтесь с пакетами Django для поиска готовых повторно используемых приложений, которые можно включить в ваш проект. Сам 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.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 упакован примерно таким же образом. Для небольшого приложения, такого как опросы, этот процесс не слишком сложен.

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', 'wheel']
   build-backend = 'setuptools.build_meta:__legacy__'
   

   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 Package Index (PyPI). На сайте packaging.python.org есть хороший учебник по этому вопросу.

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

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

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

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