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

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

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

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

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

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

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

Упаковка? Приложение?

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

Пакет можно импортировать с помощью или . Чтобы каталог (например, ) сформировал пакет, он должен содержать специальный файл , даже если этот файл пуст.import foo.barfrom foo import barpolls__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в Уроке 3 . Теперь, возможно, становится понятнее, почему мы выбрали отдельные каталоги шаблонов для проекта и приложения: все, что является частью приложения для опросов, находится внутри polls. Это делает приложение самодостаточным и упрощает его включение в новый проект.

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

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

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

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

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

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

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

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

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

  2. Переместите pollsкаталог в django-pollsкаталог.

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

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

    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 = [email protected]
    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.6
        Programming Language :: Python :: 3.7
        Programming Language :: Python :: 3.8
        Topic :: Internet :: WWW/HTTP
        Topic :: Internet :: WWW/HTTP :: Dynamic Content
    
    [options]
    include_package_data = true
    packages = find:
    python_requires = >=3.6
    install_requires =
        Django >= X.Y  # Replace "X.Y" as appropriate
    
    django-polls / setup.py
    from setuptools import setup
    
    setup()
    
  6. По умолчанию в пакет включены только модули и пакеты 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 *
    
  7. Необязательно, но рекомендуется включать подробную документацию в ваше приложение. Создайте пустой каталог django-polls/docsдля будущей документации. Добавьте дополнительную строку к django-polls/MANIFEST.in:

    recursive-include docs *
    

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

  8. Попробуйте собрать свой пакет с помощью (запускать изнутри ). Это создает каталог с именем и строит свой новый пакет, .python setup.py sdistdjango-pollsdistdjango-polls-0.1.tar.gz

Дополнительные сведения об упаковке см. В Руководстве Python по упаковке и распространению проектов .

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

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

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

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

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

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

    python -m pip install --user django-polls/dist/django-polls-0.1.tar.gz
    
  2. Если повезет, ваш проект Django теперь должен снова работать правильно. Снова запустите сервер, чтобы подтвердить это.

  3. Чтобы удалить пакет, используйте pip:

    python -m pip uninstall django-polls
    

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

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

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

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

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

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

Copyright ©2021 All rights reserved