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

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

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

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

Предположим, вы начинаете новый проект, которому необходимо приложение polls, подобное тому, над которым мы работаем. Как сделать это приложение многократно используемым? К счастью, вы уже на правильном пути. В Учебнике 1 мы увидели, как мы можем отделить polls от URLconf проекта на уровне проекта, используя include. В этом учебнике мы предпримем дальнейшие шаги, чтобы приложение было легко использовать в новых проектах и ​​готово к публикации для установки и использования другими.

Ваш проект и ваше многократно используемое приложение

После предыдущих учебников наш проект должен выглядеть следующим образом:

djangotutorial/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py
    polls/
        __init__.py
        admin.py
        apps.py
        migrations/
            __init__.py
            0001_initial.py
        models.py
        static/
            polls/
                images/
                    background.png
                style.css
        templates/
            polls/
                detail.html
                index.html
                results.html
        tests.py
        urls.py
        views.py
    templates/
        admin/
            base_site.html

Вы создали djangotutorial/templates в Учебнике 7 и polls/templates в Учебнике 3. Теперь, возможно, яснее, почему мы выбрали отдельные директории шаблонов для проекта и приложения: все, что является частью приложения polls, находится в polls. Это делает приложение автономным и более удобным для переноса в новый проект.

Директория polls теперь можно скопировать в новый проект Django и сразу же использовать повторно. Однако она еще не совсем готова к публикации. Для этого нам нужно упаковать приложение, чтобы сделать его простым для установки другими.

Установка необходимых компонентов

Текущее состояние упаковки Python немного запутанно из-за различных инструментов. В этом учебнике мы будем использовать setuptools для создания нашего пакета. Это рекомендуемый инструмент упаковки (объединенный с веткой distribute). Мы также будем использовать pip для установки и удаления. Вам следует установить эти два пакета сейчас. Если вам нужна помощь, вы можете обратиться к инструкции по установке Django с помощью pip. Вы можете установить setuptools аналогичным образом.

Упаковывание вашего приложения

Упаковкой Python приложения является подготовка приложения в определенном формате, который легко устанавливать и использовать. Сам Django упаковывается примерно так же. Для небольшого приложения, такого как polls, этот процесс не слишком сложен.

1. Сначала создайте родительскую директорию для пакета вне вашего проекта Django. Назовите эту директорию django-polls.

   Выбор имени для вашего приложения

   При выборе имени для пакета проверьте PyPI, чтобы избежать конфликтов имен с существующими пакетами. Мы рекомендуем использовать префикс django- для имен пакетов, чтобы определить ваш пакет как специфический для Django, и соответствующий префикс django_ для имени модуля. Например, пакет django-ratelimit содержит модуль django_ratelimit.

   Метки приложений (то есть конечная часть пунктирной ссылки на пакеты приложений) обязательно должны быть уникальными в INSTALLED_APPS. Избегайте использования той же метки, что и у любых пакетов Django contrib-пакетов, например, auth, admin или messages.

2. Переместите директорию polls в директорию django-polls и переименуйте ее в django_polls.

3. Измените django_polls/apps.py так, чтобы name ссылался на новое имя модуля, и добавьте label, чтобы дать короткое имя для приложения:

   django-polls/django_polls/apps.py

   from django.apps import AppConfig
   
   
   class PollsConfig(AppConfig):
       default_auto_field = "django.db.models.BigAutoField"
       name = "django_polls"
       label = "polls"
   

4. Создайте файл django-polls/README.rst со следующим содержимым:

   django-polls/README.rst

   ============
   django-polls
   ============
   
   django-polls is a 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 = [
           ...,
           "django_polls",
       ]
   
   2. Include the polls URLconf in your project urls.py like this::
   
       path("polls/", include("django_polls.urls")),
   
   3. Run ``python manage.py migrate`` to create the models.
   
   4. Start the development server and visit the admin to create a poll.
   
   5. Visit the ``/polls/`` URL to participate in the poll.
   

5. Создайте файл django-polls/LICENSE. Выбор лицензии выходит за рамки данного учебника, но достаточно сказать, что код, выпущенный публично без лицензии, бесполезен. Django и многие совместимые с Django приложения распространяются по лицензии BSD; однако вы можете выбрать свою лицензию. Просто имейте в виду, что ваш выбор лицензии повлияет на то, кто сможет использовать ваш код.

6. Далее мы создадим файл pyproject.toml, который содержит информацию о сборке и установке приложения. Полное объяснение этого файла выходит за рамки данного учебника, но Руководство по использованию Python Packaging содержит хорошее объяснение. Создайте файл django-polls/pyproject.toml со следующим содержимым:

   django-polls/pyproject.toml

   [build-system]
   requires = ["setuptools>=61.0"]
   build-backend = "setuptools.build_meta"
   
   [project]
   name = "django-polls"
   version = "0.1"
   dependencies = [
       "django>=X.Y",  # Replace "X.Y" as appropriate
   ]
   description = "A Django app to conduct web-based polls."
   readme = "README.rst"
   requires-python = ">= 3.10"
   authors = [
       {name = "Your Name", 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",
       "Operating System :: OS Independent",
       "Programming Language :: Python",
       "Programming Language :: Python :: 3",
       "Programming Language :: Python :: 3 :: Only",
       "Programming Language :: Python :: 3.10",
       "Programming Language :: Python :: 3.11",
       "Programming Language :: Python :: 3.12",
       "Programming Language :: Python :: 3.13",
       "Topic :: Internet :: WWW/HTTP",
       "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
   ]
   
   [project.urls]
   Homepage = "https://www.example.com/"
   

7. Многие общие файлы и модули Python и пакеты включены в пакет по умолчанию. Для включения дополнительных файлов нам потребуется создать файл MANIFEST.in. Для включения шаблонов и статических файлов создайте файл django-polls/MANIFEST.in со следующим содержимым:

   django-polls/MANIFEST.in

   recursive-include django_polls/static *
   recursive-include django_polls/templates *
   

8. Это необязательно, но рекомендуется включать подробную документацию с вашим приложением. Создайте пустую директорию django-polls/docs для будущей документации.

   Обратите внимание, что директория docs не будет включена в ваш пакет, если вы не добавите в нее какие-либо файлы. Многие приложения Django также предоставляют свою документацию онлайн на таких сайтах, как readthedocs.org.

9. Убедитесь, что пакет build установлен (python -m pip install build) и попробуйте собрать свой пакет, выполнив python -m build внутри django-polls. Это создает директорию под названием dist и собирает ваш новый пакет в форматы исходного кода и бинарных файлов, django-polls-0.1.tar.gz и django_polls-0.1-py3-none-any.whl.

Дополнительную информацию об упаковке см. в руководстве Python по упаковке и распространению проектов.

Использование собственного пакета

Так как мы переместили директорию polls из проекта, она больше не работает. Сейчас мы исправим это, установив наш новый пакет django-polls.

1. Для установки пакета используйте pip (вы уже установили его, верно?):

   python -m pip install --user django-polls/dist/django-polls-0.1.tar.gz
   

2. Обновите mysite/settings.py, чтобы указать на новое имя модуля:

   INSTALLED_APPS = [
       "django_polls.apps.PollsConfig",
       ...,
   ]
   

3. Обновите mysite/urls.py, чтобы указать на новое имя модуля:

   urlpatterns = [
       path("polls/", include("django_polls.urls")),
       ...,
   ]
   

4. Запустите сервер разработки, чтобы убедиться, что проект по-прежнему работает.

Публикация вашего приложения

Теперь, когда мы упаковали и протестировали django-polls, оно готово к публикации! Если это не просто пример, вы можете:

• Отправить архив по электронной почте другу.
• Загрузить архив на свой сайт.
• Опубликовать архив в общедоступном репозитории, таком как Python Package Index (PyPI). На packaging.python.org есть хороший учебник по этому процессу.

Установка пакетов Python с виртуальной средой

Ранее мы установили django-polls как библиотеку пользователя. Это имеет некоторые недостатки:

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

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