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

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

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

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

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

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

Допустим, вы начинаете новый проект, которому нужно приложение опросов, подобное тому, над которым мы работаем. Как сделать это приложение повторно используемым? К счастью, вы уже на правильном пути. В Учебнике 3 мы увидели, как можно отделить приложение опросов от URLconf проекта, используя 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 теперь можно скопировать в новый проект Django и немедленно повторно использовать. Однако он ещё не готов к публикации. Для этого нам нужно упаковать приложение, чтобы упростить его установку другим.

Установка необходимых компонентов

Современное состояние упаковки Python несколько запутанно из-за различных инструментов. В этом учебнике мы будем использовать setuptools для создания нашего пакета. Это рекомендуемый инструмент упаковки (слит с веткой distribute). Мы также будем использовать pip для установки и удаления. Вам следует установить эти два пакета сейчас. Если вам нужна помощь, вы можете обратиться к инструкции по установке Django с помощью pip. Вы можете установить setuptools таким же образом.

Упаковка вашего приложения

Упаковка Python — это подготовка вашего приложения в определённом формате для лёгкой установки и использования. Сам Django упакован таким образом. Для небольшого приложения, такого как опросы, этот процесс не слишком сложен.

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 со следующим содержимым:

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

   import os
   from setuptools import find_packages, setup
   
   with open(os.path.join(os.path.dirname(__file__), 'README.rst')) as readme:
       README = readme.read()
   
   # allow setup.py to be run from any path
   os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))
   
   setup(
       name='django-polls',
       version='0.1',
       packages=find_packages(),
       include_package_data=True,
       license='BSD License',  # example license
       description='A simple Django app to conduct Web-based polls.',
       long_description=README,
       url='https://www.example.com/',
       author='Your Name',
       author_email='yourname@example.com',
       classifiers=[
           'Environment :: Web Environment',
           'Framework :: Django',
           'Framework :: Django :: X.Y',  # replace "X.Y" as appropriate
           'Intended Audience :: Developers',
           'License :: OSI Approved :: BSD License',  # example license
           'Operating System :: OS Independent',
           'Programming Language :: Python',
           'Programming Language :: Python :: 3.5',
           'Programming Language :: Python :: 3.6',
           'Topic :: Internet :: WWW/HTTP',
           'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
       ],
   )
   

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

   recursive-include docs *
   

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

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

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

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

Поскольку мы вынесли каталог 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

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

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

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