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

Этот углубленный учебник продолжает то, что было начато в Учебнике 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 packages, например 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::
   
       url(r'^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',
           # Replace these appropriately if you are stuck on Python 2.
           'Programming Language :: Python :: 3',
           'Programming Language :: Python :: 3.4',
           'Programming Language :: Python :: 3.5',
           'Topic :: Internet :: WWW/HTTP',
           'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
       ],
   )
   

6. По умолчанию в пакет включаются только модули и пакеты Python. Чтобы включить дополнительные файлы, нам нужно создать файл MANIFEST.in. В документации setuptools, о которой говорилось в предыдущем шаге, этот файл обсуждается более подробно. Чтобы включить шаблоны, файлы README.rst и LICENSE, создайте файл 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, каждая со своей копией библиотек и пространства имен пакетов.