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

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

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

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

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

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

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

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::
   
       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

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

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

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