Django 5.2.dev 文档

Home | Table of contents | Index | Modules

« previous | up | next »

高级教程：如何编写可重用应用程序¶

本高级教程从以下位置开始 Tutorial 8 停下来了。我们将把我们的网络投票变成一个独立的Python包，你可以在新的项目中重复使用，并与其他人分享。

如果您最近尚未完成第1-7课程，我们鼓励您复习这些课程，以便您的示例项目与下面描述的项目相匹配。

可重复使用性很重要¶

设计、构建、测试和维护Web应用程序需要大量工作。许多Python和Django项目都有共同的问题。如果我们能节省一些重复的工作，那不是很棒吗？

可重用性是Python的生活方式。 The Python Package Index (PyPI) 拥有大量的包，您可以在自己的Python程序中使用。看看 Django Packages 对于您可以将其整合到项目中的现有可重复使用应用程序。Django本身也是一个普通的Python包。这意味着您可以将现有的Python包或Django应用程序组合到您自己的Web项目中。您只需要编写使您的项目独特的部分。

假设您正在启动一个新项目，需要一个像我们一直在开发的民意调查应用程序一样的民意调查应用程序。如何使此应用程序可重复使用？幸运的是，你已经在路上了。在 Tutorial 1 ，我们看到了如何使用 include .在本教程中，我们将采取进一步措施，使该应用程序易于在新项目中使用，并准备好发布供其他人安装和使用。

包裹？应用程序？

一个Python package 提供了一种对相关Python代码进行分组以易于重复使用的方法。包包含一个或多个Python代码文件（也称为“模块”）。

一个包裹可以用 import foo.bar 或 from foo import bar .对于目录（例如 polls ）要形成包，它必须包含特殊文件 __init__.py ，即使该文件为空。

一个Django application 是一个专门用于Django项目的Python包。应用程序可能使用常见的Django约定，例如 models ， tests ， urls ，以及 views 子模块。

稍后我们使用这个术语 packaging 描述让其他人易于安装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.png
                style.css
        templates/
            polls/
                detail.html
                index.html
                results.html
        tests.py
        urls.py
        views.py
    templates/
        admin/
            base_site.html

你创造 mysite/templates 在……里面 Tutorial 7 ，以及 polls/templates 在……里面 Tutorial 3 .现在也许更清楚了为什么我们选择为项目和应用程序设置单独的模板目录：民意调查应用程序的所有内容都在 polls .它使应用程序自成一体，并且更容易放入新项目。

这个 polls 目录现在可以复制到新的Django项目中并立即重复使用。不过，它还没有完全准备好出版。为此，我们需要对应用程序进行打包，以便其他人轻松安装。

安装一些先决条件¶

当前的Python打包状态与各种工具混杂在一起。在本教程中，我们将使用 setuptools 来建造我们的包裹。它是推荐的打包工具(与 distribute Fork)。我们还将使用 pip 来安装和卸载它。您现在应该安装这两个包。如果您需要帮助，您可以参考 how to install Django with pip 。您可以安装 setuptools 同样的方式。

打包您的应用程序¶

Python packaging refers to preparing your app in a specific format that can be easily installed and used. Django itself is packaged very much like this. For a small app like polls, this process isn't too difficult.

首先，在Django项目之外为包创建一个父目录。给这个目录打电话 django-polls 。

为您的应用程序选择名称

在为您的包选择名称时，请检查PYPI以避免与现有包的命名冲突。我们建议您使用 django- 包名的前缀，用于将您的包标识为特定于Django的包，以及对应的 django_ 模块名称的前缀。例如， django-ratelimit 包中包含 django_ratelimit 模块。

应用程序标签（即应用程序包虚线路径的最后一部分） must 独一无二 INSTALLED_APPS .避免使用与任何Django相同的标签 contrib packages 例如， auth ， admin ，或 messages 。
移动 polls 目录到 django-polls 目录，并将其重命名为 django_polls 。

编辑 django_polls/apps.py 所以 name 引用新的模块名称并添加 label 要为这款应用程序起一个简短的名称：

django-polls/django_polls/apps.py¶

from django.apps import AppConfig


class PollsConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "django_polls"
    label = "polls"

创建文件 django-polls/README.rst 内容如下：

django-polls/README.rst¶

============
django-polls
============

django-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 = [
        ...,
        "django_polls",
    ]

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

    path("polls/", include("django_polls.urls")),

3. Run ``python manage.py migrate`` to create the models.

4. Start the development server and visit the admin to create a poll.

5. Visit the ``/polls/`` URL to participate in the poll.

创建 django-polls/LICENSE 文件.选择许可证超出了本教程的范围，但只要说在没有许可证的情况下公开发布的代码就足够了 useless . Django和许多与Django兼容的应用程序都是在BDS许可证下分发的;但是，您可以自由选择自己的许可证。请注意，您的许可选择将影响谁能够使用您的代码。

接下来，我们将创建 pyproject.toml 详细说明如何构建和安装该应用程序的文件。对此文件的完整解释超出了本教程的范围，但是 Python Packaging User Guide 有一个很好的解释。创建 django-polls/pyproject.toml 包含以下内容的文件：

django-polls/pyproject.toml¶

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "django-polls"
version = "0.1"
dependencies = [
    "django>=X.Y",  # Replace "X.Y" as appropriate
]
description = "A Django app to conduct web-based polls."
readme = "README.rst"
requires-python = ">= 3.10"
authors = [
    {name = "Your Name", email = "yourname@example.com"},
]
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.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Internet :: WWW/HTTP",
    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
]

[project.urls]
Homepage = "https://www.example.com/"

默认情况下，包中包含许多常见文件以及Python模块和包。要包括其他文件，我们需要创建一个 MANIFEST.in 文件。要包括模板和静态文件，请创建一个文件 django-polls/MANIFEST.in 内容如下：
django-polls/MANIFEST.in¶
```
recursive-include django_polls/static *
recursive-include django_polls/templates *
```
这是可选的，但建议您在应用程序中包含详细的文档。创建空目录 django-polls/docs 以获取未来的文档。

请注意， docs 除非您向其中添加一些文件，否则目录不会包含在您的包中。许多Django应用程序还通过以下网站在线提供文档 readthedocs.org 。
检查是否有 build 已安装程序包 (python -m pip install build )，并尝试通过运行以下命令构建包 python -m build 里边 django-polls 。这将创建一个名为 dist 并将您的新包构建为源代码和二进制格式， django-polls-0.1.tar.gz 和 django_polls-0.1-py3-none-any.whl 。

有关打包的更多信息，请参阅Python的 Tutorial on Packaging and Distributing Projects 。

使用您自己的包¶

自从我们搬家以来 polls 目录退出项目，则不再工作。我们现在将通过安装新的 django-polls 包裹。

作为用户库安装

以下步骤安装 django-polls 作为用户库。与在系统范围内安装包相比，按用户安装有很多优势，例如可在您没有管理员访问权限的系统上使用，以及防止包影响系统服务和机器的其他用户。

请注意，按用户安装仍然会影响以该用户身份运行的系统工具的行为，因此使用虚拟环境是一个更强大的解决方案（见下文）。

要安装该程序包，请使用pip(您已经 installed it ，对吧？)：

python -m pip install --user django-polls/dist/django-polls-0.1.tar.gz

更新 mysite/settings.py 要指向新模块名称：：

INSTALLED_APPS = [
    "django_polls.apps.PollsConfig",
    ...,
]

更新 mysite/urls.py 要指向新模块名称：：

urlpatterns = [
    path("polls/", include("django_polls.urls")),
    ...,
]

运行开发服务器以确认项目继续工作。

发布您的应用程序¶

现在我们已经打包和测试了 django-polls ，准备与世界分享！如果这不仅仅是一个例子，您现在可以：

将包裹通过电子邮件发送给朋友。
将包上传到您的网站上。
将包发布到公共存储库上，例如 the Python Package Index (PyPI) 。 packaging.python.org 有 a good tutorial 为了这样做。

在虚拟环境中安装Python包¶

早些时候，我们安装了 django-polls 作为用户库。这有一些缺点：

修改用户库可能会影响系统上的其他Python软件。
您将无法运行此包的多个版本（或同名的其他版本）。

通常，这些情况只有在您维护多个Django项目时才会出现。当他们这样做时，最好的解决方案是使用 venv .该工具允许您维护多个隔离的Python环境，每个环境都有自己的库副本和包命名空间。