Django/docs/3.0.x/intro/reusable-apps

进阶教程：如何编写可重用的应用程序

本高级教程从 教程 7 停止的地方开始。 我们将把我们的网络投票变成一个独立的 Python 包，您可以在新项目中重用并与其他人共享。

如果您最近还没有完成教程 1-7，我们鼓励您查看这些内容，以便您的示例项目与下面描述的项目相匹配。

可重用性很重要

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

可重用性是 Python 的生活方式。 Python 包索引 (PyPI) 有大量的包，你可以在你自己的 Python 程序中使用。 查看 Django Packages，了解您可以在项目中合并的现有可重用应用程序。 Django 本身也是一个普通的 Python 包。 这意味着您可以使用现有的 Python 包或 Django 应用程序并将它们组合到您自己的 Web 项目中。 您只需要编写使您的项目独一无二的部分。

假设您要开始一个新项目，需要像我们一直在开发的那种民意调查应用程序。 你如何使这个应用程序可重用？ 幸运的是，你已经在路上了。 在 教程 1 中，我们看到了如何使用 include 将投票与项目级 URLconf 分离。 在本教程中，我们将采取进一步措施，使该应用程序易于在新项目中使用，并准备好发布供其他人安装和使用。

包裹？ 应用程序？

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

可以使用 import foo.bar 或 from foo import bar 导入包。 一个目录（如polls）要形成一个包，它必须包含一个特殊的文件__init__.py，即使这个文件是空的。

Django application 是一个 Python 包，专门用于 Django 项目。 应用程序可能使用常见的 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.gif
                style.css
        templates/
            polls/
                detail.html
                index.html
                results.html
        tests.py
        urls.py
        views.py
    templates/
        admin/
            base_site.html

您在 教程 7 中创建了 mysite/templates，在 教程 3 中创建了 polls/templates。 现在也许更清楚为什么我们选择为项目和应用程序使用单独的模板目录：民意调查应用程序的所有内容都在 polls 中。 它使应用程序自包含并且更容易放入新项目中。

polls 目录现在可以复制到新的 Django 项目中并立即重用。 不过还没有完全准备好发布。 为此，我们需要打包应用程序以方便其他人安装。

安装一些先决条件

Python 打包的当前状态与各种工具有点混乱。 在本教程中，我们将使用 setuptools 来构建我们的包。 它是推荐的打包工具（与 distribute fork 合并）。 我们还将使用 pip 来安装和卸载它。 您现在应该安装这两个软件包。 如果需要帮助，可以参考如何使用pip安装Django。 你可以用同样的方法安装setuptools。

打包您的应用程序

Python packaging 是指以易于安装和使用的特定格式准备您的应用程序。 Django 本身就是这样打包的。 对于像民意调查这样的小应用程序，这个过程并不太难。

1. 首先，在 Django 项目之外为 polls 创建一个父目录。 调用这个目录django-polls。

   为您的应用选择名称

   为包选择名称时，请检查 PyPI 等资源以避免与现有包发生命名冲突。 在创建要分发的包时，在模块名称前加上 django- 通常很有用。 这有助于其他寻找 Django 应用程序的人将您的应用程序识别为特定于 Django 的应用程序。

   应用程序标签（即应用程序包的虚线路径的最后一部分）必须 在 :setting:`INSTALLED_APPS` 中是唯一的。 避免使用与任何 Django contrib 包 相同的标签，例如 auth、admin 或 messages。

2. 将polls目录移动到django-polls目录下。

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. 接下来，我们将创建 setup.cfg 和 setup.py 文件，详细说明如何构建和安装应用程序。 对这些文件的完整解释超出了本教程的范围，但 setuptools 文档 有很好的解释。 使用以下内容创建文件 django-polls/setup.cfg 和 django-polls/setup.py：

   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:

   django-polls/setup.py

   from setuptools import setup
   
   setup()

6. 默认情况下，包中仅包含 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 *

7. 在您的应用程序中包含详细的文档是可选的，但建议您这样做。 为将来的文档创建一个空目录 django-polls/docs。 向 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。

有关打包的更多信息，请参阅 Python 的 打包和分发项目教程 。

使用你自己的包

由于我们将 polls 目录移出项目，它不再起作用。 我们现在将通过安装我们新的 django-polls 包来解决这个问题。

安装为用户库

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

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

1. 要安装该软件包，请使用 pip（您已经 安装了它 ，对吗？）：

   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-polls，它已经准备好与世界分享了！ 如果这不仅仅是一个例子，你现在可以：

• 将包裹通过电子邮件发送给朋友。
• 将包上传到您的网站。
• 将包发布到公共存储库上，例如 Python 包索引 (PyPI)。 packaging.python.org 有 一个很好的教程 来做这件事。

使用虚拟环境安装 Python 包

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

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

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