Django 5.1.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项目的Python包。应用程序可以使用常见的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 在里面 Tutorial 7 和 polls/templates 在里面 Tutorial 3 . 现在，也许我们选择为项目和应用程序设置单独的模板目录的原因更清楚了：作为投票应用程序一部分的所有内容都在 polls . 它使应用程序独立，并且更容易进入新项目。

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

安装某些必备组件¶

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

打包应用程序¶

Python 包装指以特定格式准备应用程序，以便轻松安装和使用。 Django 本身就是这样包装的。对于像应用程序这样的小投票来说，这个过程并不太困难。

首先，为创建父目录 polls 在你的Django项目之外。调用此目录 django-polls .

为应用程序选择名称

为包选择名称时，请检查诸如pypi之类的资源，以避免与现有包发生命名冲突。提前准备通常很有用 django- 创建要分发的包时使用模块名。这有助于寻找Django应用程序的其他人将您的应用程序标识为Django特有的。

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

创建文件 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.

创建一个 django-polls/LICENSE 文件。选择一个许可证超出了本教程的范围，但只要说公开发布的没有许可证的代码就是 无用的 . Django和许多与Django兼容的应用程序都是根据BSD许可证分发的；但是，您可以自由选择自己的许可证。请注意，您的许可选择将影响谁可以使用您的代码。

接下来，我们将创建 pyproject.toml ， setup.cfg ，以及 setup.py 详细说明如何构建和安装该应用程序的文件。对这些文件的完整解释超出了本教程的范围，但是 setuptools documentation 有一个很好的解释。创建 django-polls/pyproject.toml ， django-polls/setup.cfg ，以及 django-polls/setup.py 具有以下内容的文件：

django-polls/pyproject.toml¶

[build-system]
requires = ['setuptools>=40.8.0']
build-backend = 'setuptools.build_meta'

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.10
    Programming Language :: Python :: 3.11
    Programming Language :: Python :: 3.12
    Topic :: Internet :: WWW/HTTP
    Topic :: Internet :: WWW/HTTP :: Dynamic Content

[options]
include_package_data = true
packages = find:
python_requires = >=3.10
install_requires =
    Django >= X.Y  # Replace "X.Y" as appropriate

django-polls/setup.py¶

from setuptools import setup

setup()

默认情况下，包中只包含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 *
```
这是可选的，但建议您在应用程序中包含详细的文档。创建空目录 django-polls/docs 以获取未来的文档。向…添加额外一行 django-polls/MANIFEST.in ：
```
recursive-include docs *
```
请注意 docs 除非向包中添加一些文件，否则目录不会包含在包中。许多django应用程序还通过以下网站在线提供文档： readthedocs.org .
尝试用创建包 python setup.py sdist （从内部运行 django-polls ）这将创建一个名为 dist 建立你的新包， django-polls-0.1.tar.gz .

有关打包的详细信息，请参见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

幸运的是，您的Django项目现在应该可以正常工作了。再次运行服务器以确认这一点。
要卸载该程序包，请使用pip：
```
python -m pip uninstall django-polls
```

发布应用程序¶

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

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

在虚拟环境中安装Python包¶

早些时候，我们将投票应用程序安装为用户库。这有一些缺点：

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

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