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

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

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

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

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

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