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

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

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

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

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

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

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

Теперь каталог 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 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 со следующим содержимым:

   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. По умолчанию в пакет включаются только модули и пакеты 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 (вы уже установили его, верно?):

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