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

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

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

Многократное использование имеет значение

Разработка, создание, тестирование и сопровождение веб-приложения — это большая работа. Многие проекты 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 в Учебнике 2, и 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::
   
       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='http://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.2',
           'Programming Language :: Python :: 3.3',
           '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, каждая со своей копией библиотек и пространства имён пакетов.