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

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

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

Возможность повторного использования имеет значение¶

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

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

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

Пакет? Приложение?

В Python package предоставляет способ группировки кода Python для легкого повторного использования. Пакет содержит один или несколько файлов кода Python (также называемых «модулями»).

Пакет может быть импортирован с помощью import foo.bar или from foo import bar. Чтобы каталог (например, polls) сформировал пакет, он должен содержать специальный файл __init__.py, даже если этот файл пуст.

Приложение Django - это пакет Python, который специально предназначен для использования в проекте Django. Приложение может использовать общие соглашения Django, такие как субмодули models, tests, urls и views.

Позже мы будем использовать термин «упаковка», чтобы описать процесс создания пакета Python, который другие могут легко установить. Это может немного сбивать с толку, мы знаем.

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

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

mysite/
    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.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 в: doc: Руководстве 3 </intro/tutorial03>. Теперь, возможно, стало понятнее, почему мы выбрали отдельные каталоги шаблонов для проекта и приложения: все, что является частью приложения polls, находится в polls. Это делает приложение самодостаточным и позволяет легко перейти в новый проект.

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

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

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

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

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

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

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

При выборе имени для вашего пакета, проверьте ресурсы, такие как PyPI, чтобы избежать конфликтов имен с существующими пакетами. Часто полезно добавлять django- к имени вашего модуля при создании пакета для распространения. Это помогает другим, ищущим приложения Django, идентифицировать ваше приложение как специфическое для Django.

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

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

django-polls/README.rst¶

=====
Polls
=====

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 = [
        ...
        'polls',
    ]

2. Include the polls URLconf in your project urls.py like this::

    path('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.

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

Далее мы создадим файлы pyproject.toml, setup.cfg и setup.py, в которых подробно описано, как собрать и установить приложение. Полное объяснение этих файлов выходит за рамки данного руководства, но в setuptools documentation есть хорошее объяснение. Создайте файлы django-polls/pyproject.toml, django-polls/setup.cfg и django-polls/setup.py со следующим содержимым:

django-polls/pyproject.toml¶

[build-system]
requires = ['setuptools>=40.8.0', 'wheel']
build-backend = 'setuptools.build_meta:__legacy__'

django-polls/setup.cfg¶

[metadata]
name = django-polls
version = 0.1
description = A Django app to conduct web-based polls.
long_description = file: README.rst
url = https://www.example.com/
author = Your Name
author_email = yourname@example.com
license = BSD-3-Clause  # Example license
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.8
    Programming Language :: Python :: 3.9
    Topic :: Internet :: WWW/HTTP
    Topic :: Internet :: WWW/HTTP :: Dynamic Content

[options]
include_package_data = true
packages = find:
python_requires = >=3.8
install_requires =
    Django >= X.Y  # Replace "X.Y" as appropriate

django-polls/setup.py¶

from setuptools import setup

setup()

По умолчанию в пакет включаются только модули и пакеты Python. Чтобы включить дополнительные файлы, нам нужно создать файл MANIFEST.in. В документации setuptools, упомянутой в предыдущем шаге, этот файл обсуждается более подробно. Чтобы включить шаблоны, README.rst и наш файл LICENSE, создайте файл django-polls/MANIFEST.in со следующим содержимым:
django-polls/MANIFEST.in¶
```
include LICENSE
include README.rst
recursive-include polls/static *
recursive-include polls/templates *
```
Необязательно, но рекомендуется включать подробную документацию в ваше приложение. Создайте пустой каталог django-polls/docs для будущей документации. Добавьте дополнительную строку в django-polls/MANIFEST.in:
```
recursive-include docs *
```
Обратите внимание, что каталог docs не будет включен в ваш пакет, если вы не добавите в него некоторые файлы. Многие приложения Django также предоставляют свою документацию в Интернете через такие сайты, как readthedocs.org.
Попробуйте собрать свой пакет с помощью python setup.py sdist (запустите изнутри django-polls). Это создаст каталог с именем dist и соберет ваш новый пакет, django-polls-0.1.tar.gz.

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

Используя свой собственный пакет¶

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

Установка в качестве пользовательской библиотеки

Следующие шаги устанавливают django-polls в качестве пользовательской библиотеки. Индивидуальная установка имеет много преимуществ по сравнению с установкой пакета в масштабе всей системы, например, возможность использования в системах, где у вас нет прав администратора, а также предотвращение влияния пакета на системные службы и других пользователей компьютера.

Обратите внимание, что установка для каждого пользователя может по-прежнему влиять на поведение системных инструментов, запускаемых от имени этого пользователя, поэтому использование виртуальной среды является более надежным решением (смотрите ниже).

Чтобы установить пакет, используйте pip (вы уже установили его, верно?)
```
python -m pip install --user django-polls/dist/django-polls-0.1.tar.gz
```
Если повезет, ваш проект Django теперь снова должен работать правильно. Запустите сервер еще раз, чтобы подтвердить это.
Чтобы удалить пакет, используйте pip:
```
python -m pip uninstall django-polls
```

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

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

Отправьте пакет по электронной почте другу.
Загрузите пакет на свой сайт.
Разместите пакет в общедоступном репозитории, таком как Индекс пакетов Python (PyPI). packaging.python.org содержит `хороший учебник <https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives> `_ для этого.

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

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

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

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

Создание первого приложения на Django, часть 7

Что читать дальше

Вернуться на верх

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

Возможность повторного использования имеет значение¶

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

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

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

Используя свой собственный пакет¶

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

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

Django 4.1

Содержание

Дополнительно

Вы здесь: