Смысл многократного использования¶

Большая часть работы уходит на проектирование, сборку, тестирование и конечно же поддержку веб приложения/компонента. У многих Python и Django проектов существуют схожие задачи и проблемы. Вот было бы здорово не повторять однажды проделанную работу, а сохранить её и использовать в будущем. Не правда ли?

Многократное использование - часть философии Python. К примеру, для тех кто ещё не знает что такое The Python Package Index (PyPI) - это громадное хранилище пакетов которые вы можете использовать в собственных Python программах. Посетите Django Packages и вы также увидите много приложений для Django, который были добавлены другими разработчиками. По-существу Django сам является обычным Python пакетом. Всё это означает простую истину: вы можете брать любые существующие решения(пакеты, не важно Python или Django) и использовать в своих проектах как угодно. Это даёт большое преимущество в скорости. Не надо придумывать то, что уже придумано другими, а значит можно посвятить всё время только разработке уникальной стороны своего проекта.

Скажем вы начали новый проект в котором используется приложение для голосования, подобно тому, которое мы разрабатывали в предыдущих уроках. Как же сделать наше приложение с голосованием многократно используемым и независимым от проекта к проекту? К счастью, мы уже на правильном пути и затрагивали эту тему в 3 части. Тогда мы уже смогли отделить приложение для голосования от проекта при помощи URLconf, используя include. В этом уроке мы продвинемся вперёд в решении этого вопроса. А именно, оформим приложение таким образом, чтобы его можно было легко подключать в наших новых проектах. А при желании приложение можно будет опубликовать, и тогда его смогут использовать и другие.

Ваш проект и ваши приложения¶

After the previous tutorials, our project should look like this:

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

You created mysite/templates in Tutorial 7, and polls/templates in Tutorial 3. Now perhaps it is clearer why we chose to have separate template directories for the project and application: everything that is part of the polls application is in polls. It makes the application self-contained and easier to drop into a new project.

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

Необходимые условия¶

The current state of Python packaging is a bit muddled with various tools. For this tutorial, we’re going to use setuptools to build our package. It’s the recommended packaging tool (merged with the distribute fork). We’ll also be using pip to install and uninstall it. You should install these two packages now. If you need help, you can refer to how to install Django with pip. You can install setuptools the same way.

Создание пакета с вашим приложением¶

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

1. Первым делом создайте родительский каталог для polls вне вашего Django проекта. Назовите его django-polls.

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

   When choosing a name for your package, check resources like PyPI to avoid naming conflicts with existing packages. It’s often useful to prepend django- to your module name when creating a package to distribute. This helps others looking for Django apps identify your app as Django specific.

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

2. Move the polls directory into the django-polls directory.

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. Next we’ll create setup.cfg and setup.py files which detail how to build and install the app. A full explanation of these files is beyond the scope of this tutorial, but the setuptools documentation has a good explanation. Create the files django-polls/setup.cfg and django-polls/setup.py with the following contents:

   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.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. Only Python modules and packages are included in the package by default. To include additional files, we’ll need to create a MANIFEST.in file. The setuptools docs referred to in the previous step discuss this file in more detail. To include the templates, the README.rst and our LICENSE file, create a file django-polls/MANIFEST.in with the following contents:

   django-polls/MANIFEST.in¶

   include LICENSE
   include README.rst
   recursive-include polls/static *
   recursive-include polls/templates *
   

7. It’s optional, but recommended, to include detailed documentation with your app. Create an empty directory django-polls/docs for future documentation. Add an additional line to 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.

Подробности о пакетах можно найти в Уроке по созданию и распространению пакетов.

Использование ваших пакетов¶

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

1. To install the package, use pip (you already installed it, right?):

   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! Если бы это был не просто пример, вы бы могли:

• Отправить пакет друзьям электронной почтой.

• Загрузить пакет на ваш сайт.

• Отправить пакет в публичный репозиторий, такой как The Python Package Index (PyPI). Это руководство поможет вам.

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

Earlier, we installed the polls app as a user library. This has some disadvantages:

• Изменение таких библиотек влияет на другие программы написанные на Python.

• Вы не сможете использовать разные версии пакета (или пакеты с одинаковым названием).

Обычно такое происходит при работе над несколькими Django проектами. В таком случае лучше всего использовать virtualenv. Этот инструмент позволяет использовать независимые Python окружения, каждое со своими пакетами.