• В чем разница между написанием автономных приложений и написанием приложений внутри проектов
• Как создать файл setup.cfg для публикации вашего приложения Django
• Как загрузить Django вне проекта Django, чтобы вы могли протестировать свое приложение
• Как протестировать несколько версий Python и Django с помощью tox
• Как опубликовать устанавливаемое приложение Django в PyPI с помощью Twine

Даже если вы изначально намеревались сделать свое приложение Django доступным в виде пакета, вы, скорее всего, начнете внутри проекта. Чтобы продемонстрировать процесс перехода от проекта Django к устанавливаемому приложению Django, я сделал две ветки доступными в репозитории. Ветка проекта является начальным состоянием из приложения внутри проекта Django. Основная ветка — это готовое устанавливаемое приложение.

Вы также можете скачать готовое приложение на странице пакета PyPI realpython-django-чеков

Приложение в качестве примера - краткое представление позиций в квитанции. В ветке проекта вы найдете каталог с именем sample_project , содержащий рабочий проект Django. Каталог выглядит так:

sample_project/
│
├── receipts/
│   ├── fixtures/
│   │   └── receipts.json
│   │
│   ├── migrations/
│   │   ├── 0001_initial.py
│   │   └── __init__.py
│   │
│   ├── __init__.py
│   ├── admin.py
│   ├── apps.py
│   ├── models.py
│   ├── tests.py
│   ├── urls.py
│   └── views.py
│
├── sample_project/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
│
├── db.sqlite3
├── manage.py
├── resetdb.sh
└── runserver.sh

Самая последняя версия Django на момент написания этого руководства была 3.0.4, и все тестирование проводилось на Python 3.7. Ни один из шагов, описанных в этом руководстве, не должен быть несовместим с более ранними версиями Django - я использовал эти методы, начиная с Django 1.8. Однако некоторые изменения необходимы, если вы используете Python 2. Чтобы не усложнять примеры, я использовал Python 3.7 для всей базы кода.

Создание проекта Django с нуля

Пример проекта и приложение квитанций были созданы с помощью команды администратора Django с небольшими изменениями. Для начала запустите следующий код в чистой виртуальной среде:

$ python -m pip install Django
$ django-admin startproject sample_project
$ cd sample_project
$ ./manage.py startapp receipts

# receipts/models.py
from decimal import Decimal
from django.db import models

class Receipt(models.Model):
    created = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return f"Receipt(id={self.id})"

    def total(self) -> Decimal:
        return sum(item.cost for item in self.item_set.all())

class Item(models.Model):
    created = models.DateTimeField(auto_now_add=True)

    description = models.TextField()
    cost = models.DecimalField(max_digits=7, decimal_places=2)
    receipt = models.ForeignKey(Receipt, on_delete=models.CASCADE)

    def __str__(self):
        return f"Item(id={self.id}, description={self.description}, " \
            f"cost={self.cost})"

# receipts/views.py
from django.http import JsonResponse
from receipts.models import Receipt

def receipt_json(request):
    results = {
        "receipts":[],
    }

    for receipt in Receipt.objects.all():
        line = [str(receipt), []]
        for item in receipt.item_set.all():
            line[1].append(str(item))

        results["receipts"].append(line)

    return JsonResponse(results)

# receipts/admin.py
from django.contrib import admin

from receipts.models import Receipt, Item

@admin.register(Receipt)
class ReceiptAdmin(admin.ModelAdmin):
    pass

@admin.register(Item)
class ItemAdmin(admin.ModelAdmin):
    pass

# receipts/urls.py
from django.urls import path

from receipts import views

urlpatterns = [
    path("receipt_json/", views.receipt_json),
]

$ curl -sS http://127.0.0.1:8000/receipts/receipt_json/ | python3.8 -m json.tool
{
    "receipts": [
        [
            "Receipt(id=1)",
            [
                "Item(id=1, description=wine, cost=15.25)",
                "Item(id=2, description=pasta, cost=22.30)"
            ]
        ],
        [
            "Receipt(id=2)",
            [
                "Item(id=3, description=beer, cost=8.50)",
                "Item(id=4, description=pizza, cost=12.80)"
            ]
        ]
    ]
}
 

# receipts/tests.py
from decimal import Decimal
from django.test import TestCase
from receipts.models import Receipt

class ReceiptTest(TestCase):
    fixtures = ["receipts.json", ]

    def test_receipt(self):
        receipt = Receipt.objects.get(id=1)
        total = receipt.total()

        expected = Decimal("37.55")
        self.assertEqual(expected, total)

$ ./manage.py test
Creating test database for alias 'default'...
System check identified no issues (0 silenced).
.
----------------------------------------------------------------------
Ran 1 test in 0.013s

OK
Destroying test database for alias 'default'...

django-receipts/
│
├── receipts/
│   ├── fixtures/
│   │   └── receipts.json
│   │
│   ├── migrations/
│   │   ├── 0001_initial.py
│   │   └── __init__.py
│   │
│   ├── __init__.py
│   ├── models.py
│   ├── tests.py
│   ├── urls.py
│   ├── views.py
│   ├── admin.py
│   └── apps.py
│
├── sample_project/
│   ├── sample_project/
│   │   ├── __init__.py
│   │   ├── asgi.py
│   │   ├── settings.py
│   │   ├── urls.py
│   │   └── wsgi.py
│   │
│   ├── db.sqlite3
│   ├── manage.py
│   ├── resetdb.sh
│   └── runserver.sh
│
├── LICENSE
└── README.rst

 1# boot_django.py
 2#
 3# This file sets up and configures Django. It's used by scripts that need to
 4# execute as if running in a Django server.
 5import os
 6import django
 7from django.conf import settings
 8
 9BASE_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "receipts"))
10
11def boot_django():
12    settings.configure(
13        BASE_DIR=BASE_DIR,
14        DEBUG=True,
15        DATABASES={
16            "default":{
17                "ENGINE":"django.db.backends.sqlite3",
18                "NAME": os.path.join(BASE_DIR, "db.sqlite3"),
19            }
20        },
21        INSTALLED_APPS=(
22            "receipts",
23        ),
24        TIME_ZONE="UTC",
25        USE_TZ=True,
26    )
27    django.setup()

#!/usr/bin/env python
# makemigrations.py

from django.core.management import call_command
from boot_django import boot_django

boot_django()
call_command("makemigrations", "receipts")

 1#!/usr/bin/env python
 2# load_tests.py
 3import sys
 4from unittest import TestSuite
 5from boot_django import boot_django
 6
 7boot_django()
 8
 9default_labels = ["receipts.tests", ]
10
11def get_suite(labels=default_labels):
12    from django.test.runner import DiscoverRunner
13    runner = DiscoverRunner(verbosity=1)
14    failures = runner.run_tests(labels)
15    if failures:
16        sys.exit(failures)
17
18    # In case this is called from setuptools, return a test suite
19    return TestSuite()
20
21if __name__ == "__main__":
22    labels = default_labels
23    if len(sys.argv[1:]) > 0:
24        labels = sys.argv[1:]
25
26    get_suite(labels)

 1# setup.cfg
 2[metadata]
 3name = realpython-django-receipts
 4version = 1.0.3
 5description = Sample installable django app
 6long_description = file:README.rst
 7url = https://github.com/realpython/django-receipts
 8license = MIT
 9classifiers =
10    Development Status :: 4 - Beta
11    Environment :: Web Environment
12    Intended Audience :: Developers
13    License :: OSI Approved :: MIT License
14    Operating System :: OS Independent
15    Programming Language :: Python :: 3 :: Only
16    Programming Language :: Python :: 3.7
17    Programming Language :: Python :: Implementation :: CPython
18    Topic :: Software Development :: Libraries :: Application Frameworks
19    Topic :: Software Development :: Libraries :: Python Modules
20
21[options]
22include_package_data = true
23python_requires = >=3.6
24setup_requires =
25    setuptools >= 38.3.0
26install_requires =
27    Django>=2.2

setup.cfg описывает пакет, который вы создадите. Строка 6 использует директиву file: для чтения в вашем файле README.rst. Это избавляет вас от необходимости писать длинное описание в двух местах.

Запись install_requires в строке 26 сообщает любым установщикам, таким как pip install , о зависимостях вашего приложения. Вы всегда захотите привязать свое устанавливаемое приложение Django к его минимально поддерживаемой версии Django.

Если в вашем коде есть зависимости, которые необходимы только для запуска тестов, вы можете добавить запись tests_require = . Например, до того, как mock стал частью стандартной библиотеки Python, обычно можно было увидеть tests_require = mock> = 2.0.0 в setup.cfg .

Рекомендуется включать в пакет файл pyproject.toml . Прекрасная статья Бретта Кэннона на эту тему подробно расскажет об этом. Pyproject.toml файл также включен образец кода.

Вы почти готовы создать пакет для устанавливаемого приложения Django. Самый простой способ проверить это - использовать ваш образец проекта - еще одна веская причина сохранить образец проекта под рукой. Команда pip install поддерживает локально определенные пакеты. Это можно использовать, чтобы убедиться, что ваше приложение по-прежнему работает с проектом. Однако есть одно предостережение: в этом случае setup.cfg не будет работать сам по себе. Вам также необходимо создать версию с прокладкой для setup.py :

#!/usr/bin/env python

if __name__ == "__main__":
    import setuptools
    setuptools.setup()

Этот сценарий автоматически использует ваш файл setup.cfg . Теперь вы можете установить локальную редактируемую версию пакета, чтобы протестировать ее из sample_project . Чтобы быть уверенным вдвойне, лучше всего начать с совершенно новой виртуальной среды. Добавьте следующий requirements.txt файл внутри sample_project каталога:

# requirements.txt
-e ../../django-receipts

«-e» говорит pip, что это локальная редактируемая установка. Теперь вы готовы к установке:

$ pip install -r requirements.txt
Obtaining django-receipts (from -r requirements.txt (line 1))
Collecting Django>=3.0
  Using cached Django-3.0.4-py3-none-any.whl (7.5 MB)
Collecting asgiref~=3.2
  Using cached asgiref-3.2.7-py2.py3-none-any.whl (19 kB)
Collecting pytz
  Using cached pytz-2019.3-py2.py3-none-any.whl (509 kB)
Collecting sqlparse>=0.2.2
  Using cached sqlparse-0.3.1-py2.py3-none-any.whl (40 kB)
Installing collected packages: asgiref, pytz, sqlparse, Django, realpython-django-receipts
  Running setup.py develop for realpython-django-receipts
Successfully installed Django-3.0.4 asgiref-3.2.7 pytz-2019.3 realpython-django-receipts sqlparse-0.3.1

Список install_requires в setup.cfg сообщает pip install, что ему нужен Django. Django нуждается asgiref , pytz и sqlparse . Все зависимости учтены, и теперь вы можете запустить свой сервер sample_project Django dev. Поздравляем - теперь ваше приложение упаковано, и на него есть ссылки в образце проекта!

Тестирование нескольких версий с помощью tox

Django и Python постоянно развиваются. Если вы собираетесь поделиться своим устанавливаемым приложением Django со всем миром, вам, вероятно, придется протестировать его в нескольких средах . Инструменту tox требуется небольшая помощь, чтобы иметь возможность протестировать ваше приложение Django. Сделайте следующее изменение внутри setup.cfg :

 1# setup.cfg
 2[metadata]
 3name = realpython-django-receipts
 4version = 1.0.3
 5description = Sample installable django app
 6long_description = file:README.rst
 7url = https://github.com/realpython/django-receipts
 8license = MIT
 9classifiers =
10    Development Status :: 4 - Beta
11    Environment :: Web Environment
12    Intended Audience :: Developers
13    License :: OSI Approved :: MIT License
14    Operating System :: OS Independent
15    Programming Language :: Python :: 3 :: Only
16    Programming Language :: Python :: 3.7
17    Programming Language :: Python :: Implementation :: CPython
18    Topic :: Software Development :: Libraries :: Application Frameworks
19    Topic :: Software Development :: Libraries :: Python Modules
20
21[options]
22include_package_data = true
23python_requires = >=3.6
24setup_requires =
25    setuptools >= 38.3.0
26install_requires =
27    Django>=2.2
28test_suite = load_tests.get_suite

 1# Defined inside load_tests.py
 2def get_suite(labels=default_labels):
 3    from django.test.runner import DiscoverRunner
 4    runner = DiscoverRunner(verbosity=1)
 5    failures = runner.run_tests(labels)
 6    if failures:
 7        sys.exit(failures)
 8
 9    # If this is called from setuptools, then return a test suite
10    return TestSuite()

[tox]
envlist = py{36,37}-django220, py{36,37}-django300

[testenv]
deps =
    django220: Django>=2.2,<3
    django300: Django>=3
commands=
    python setup.py test

$ python -m pip install -U wheel twine setuptools
$ python setup.py sdist
$ python setup.py bdist_wheel
$ twine upload dist/*

[disutils]
index-servers =
    pypi

[pypi]
username: <YOUR_USERNAME>