如何编写可安装的 Django 应用程序

从头开始创建 Django 项目

示例项目和收据应用程序是使用 Djangoadmin命令和一些小的编辑创建的。首先，在干净的虚拟环境中运行以下代码：

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

这将创建sample_project项目目录结构和receipts应用程序子目录，其中包含您将用于创建可安装 Django 应用程序的模板文件。

接下来，该sample_project/settings.py文件需要进行一些修改：

• 添加'127.0.0.1'到ALLOWED_HOSTS设置中，以便您可以在本地进行测试。
• 添加'receipts'到INSTALLED_APPS列表中。

您还需要receipts在sample_project/urls.py文件中注册应用程序的 URL 。为此，请添加path('receipts/', include('receipts.urls'))到url_patterns列表中。

探索收据示例应用程序

该应用程序由两个 ORM 模型类组成：Item和Receipt. 本Item类包含了描述和成本数据库字段声明。成本包含在DecimalField. 使用浮点数来表示货币是危险的——在处理货币时你应该总是使用定点数。

该Receipt班是一个收集点Item的对象。这是一个实现ForeignKey在Item该点Receipt。Receipt还包括total()获取Item包含在 中的对象的总成本Receipt：

# 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})"

模型对象为您提供数据库内容。一个简短的 Django 视图返回一个JSON 字典，其中Receipt包含Item数据库中的所有对象及其对象：

# 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)

的receipt_json()视图遍历所有的Receipt目的，创建一对所述的Receipt对象和所述的列表Item的对象包含在。所有这些都放在字典中并通过 Django 的JsonResponse().

为了使模型在Django 管理界面中可用，您可以使用一个admin.py文件来注册模型：

# 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

此代码ModelAdmin为每个Receipt和Item类创建一个 Django ，并将它们注册到 Django 管理员。

最后，urls.py文件在应用程序中针对 URL 注册单个视图：

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

from receipts import views

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

您现在可以包含receipts/urls.py在您的项目url.py文件中，以便在您的网站上提供收据视图。

一切就绪后，可以运行./manage.py makemigrations receipts，使用Django admin添加数据，然后访问/receipts/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)"
            ]
        ]
    ]
}

在上面的块中，您使用curl访问receipt_json视图，从而产生包含Receipt对象及其对应Item对象的 JSON 响应。

制作可安装的 Django 应用

您的目标是在没有项目的情况下共享收据应用程序，并使其可被其他人重复使用。您可以压缩receipts/目录并将其分发出去，但这有些限制。相反，您希望将应用程序分成一个包，以便它可以安装。

创建可安装的 Django 应用程序的最大挑战是 Django 需要一个项目。没有项目的应用程序只是一个包含代码的目录。没有项目，Django 不知道如何处理您的代码，包括运行测试。

$ mv receipts ..

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()

使用可安装的 Django 应用程序运行管理命令

现在您有了boot_django.py，您可以使用一个非常短的脚本运行任何 Django 管理命令：

#!/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")

Django 允许您通过call_command(). 您现在可以通过导入和调用boot_django()后跟call_command().

你的应用程序现在在项目之外，允许你对它做各种各样的 Django-y 事情。我经常定义四个实用程序脚本：

1. load_tests.py 测试您的应用
2. makemigrations.py 创建迁移文件
3. migrate.py 执行表迁移
4. djangoshell.py 生成一个知道你的应用程序的 Django shell

测试可安装的 Django 应用

该load_test.py文件可以像makemigrations.py脚本一样简单，但它只能一次运行所有测试。通过添加几行，您可以将命令行参数传递给测试运行器，从而允许您运行选择性测试：

 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)

DjangoDiscoverRunner是一个测试发现类，与 Python 的unittest. 它负责设置测试环境、构建测试套件、设置数据库、运行测试，然后将其全部拆除。从第 11 行开始，get_suite()获取测试标签列表并直接调用DiscoverRunner它们。

该脚本类似于 Django 管理命令的test作用。该__main__块将任何命令行参数传递给get_suite()，如果没有，则它将传递到应用程序的测试套件中receipts.tests。您现在可以load_tests.py使用测试标签参数调用并运行单个测试。

第 19 行是一个特殊情况，可在使用tox. 您将tox在后面的部分中了解更多信息。您还可以DiscoverRunner在下面的可折叠部分中查看潜在的替代品。

定义您的可安装包 setup.cfg

要将可安装的 Django 应用程序放在 PyPI 上，您需要先将其放入一个包中。PyPI中期望一个egg，wheel或源分布。这些是使用setuptools. 为此，您需要在与目录相同的目录级别创建一个setup.cfg文件和一个setup.py文件receipts。

但是，在深入研究之前，您需要确保您有一些文档。您可以在 中包含项目描述setup.cfg，它会自动显示在 PyPI 项目页面上。确保写一个README.rst或类似的关于你的包的信息。

PyPI默认支持reStructuredText格式，但它也可以处理带有额外参数的Markdown：

 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文件。这使您不必在两个地方编写长描述。

第26 行的install_requires条目告诉任何安装程序，例如，您的应用程序具有的依赖项。您将始终希望将可安装的 Django 应用程序与其支持的最低 Django 版本联系起来。pip install

如果您的代码具有任何仅运行测试所需的依赖tests_require =项，则您可以添加一个条目。例如，在mock成为标准 Python 库的一部分之前，tests_require = mock>=2.0.0在setup.cfg.

pyproject.toml在你的包中包含一个文件被认为是最佳实践。布雷特·坎农 (Brett Cannon)关于该主题的出色文章可以让您了解详细信息。pyproject.toml示例代码中还包含一个文件。

您几乎已准备好为可安装的 Django 应用程序构建包。测试它的最简单方法是使用您的示例项目——另一个保留示例项目的好理由。该pip install命令支持本地定义的包。这可用于确保您的应用程序仍然适用于项目。但是，一个警告是setup.cfg在这种情况下它不会单独工作。您还必须创建一个 shim 版本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_projectDjango 开发服务器了。恭喜 - 您的应用程序现在已从示例项目中打包和引用！

发布到 PyPI

最后，是时候在 PyPI 上分享您的可安装 Django 应用程序了。有多种工具可用于上传包，但在本教程中您将重点介绍Twine。以下代码构建包并调用 Twine：

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

前两个命令构建包的源代码和二进制分发版。调用twine上传到 PyPI。如果您.pypirc的主目录中有一个文件，那么您可以预设您的用户名，这样系统只会提示您输入密码：

[disutils]
index-servers =
    pypi

[pypi]
username: <YOUR_USERNAME>

我经常使用一个小的shell脚本来grep从代码中获取版本号。然后我调用git tag用版本号标记repo，删除旧的build/和dist/目录，并调用上述三个命令。

有关使用 Twine 的更多详细信息，请参阅如何将开源 Python 包发布到 PyPI。Twine 的两个流行替代品是Poetry和Flit。Python 中的包管理正在迅速变化。PEP 517和PEP 518正在重新定义如何描述 Python 包和依赖项。

结论

Django 应用程序依赖于 Django 项目结构，因此单独打包它们需要额外的步骤。您已经了解了如何通过从项目中提取、打包并在 PyPI 上共享来制作可安装的 Django 应用程序。请务必从以下链接下载示例代码：