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

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

如果你最近没有完成教程 1-7,我们建议你回顾一下这些教程,以便你的示例项目与下面描述的项目相匹配。

可重用性很重要

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

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

假设你正在启动一个新项目,该项目需要一个类似于我们一直在使用的投票应用程序。如何使这个应用程序可重用?幸运的是,你已经走在了正确的道路上。在教程 1中,我们看到了如何使用include将投票与项目级 URLconf 解耦。在本教程中,我们将采取进一步的措施,使应用程序易于在新项目中使用,并准备好发布,以便其他人可以安装和使用。

包?应用?

Python 提供了一种将相关 Python 代码分组以方便重用的方法。一个包包含一个或多个 Python 代码文件(也称为“模块”)。

可以使用 import foo.barfrom foo import bar 导入包。对于要形成包的目录(如 polls),它必须包含一个特殊文件 __init__.py,即使此文件为空。

Django 应用 是一个专门用于 Django 项目的 Python 包。应用可以使用常见的 Django 约定,例如具有 modelstestsurlsviews 子模块。

稍后我们将使用术语打包来描述使 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

您在 教程 7 中创建了 mysite/templates,并在 教程 3 中创建了 polls/templates。现在,也许更清楚为什么我们选择为项目和应用创建单独的模板目录:所有属于 polls 应用的部分都在 polls 中。这使得应用自包含,并且更容易放入新项目中。

现在可以将 polls 目录复制到新的 Django 项目中并立即重用。但它还没有准备好发布。为此,我们需要打包应用,以便其他人更容易安装。

安装一些先决条件

目前 Python 包的管理工具比较混乱。在本教程中,我们将使用 setuptools 来构建我们的包。它是推荐的打包工具(与 distribute 分支合并)。我们还将使用 pip 来安装和卸载它。您现在应该安装这两个包。如果您需要帮助,可以参考 如何使用 pip 安装 Django。您可以用相同的方式安装 setuptools

打包您的应用程序

Python 的打包是指将您的应用程序准备成一种特定的格式,以便于安装和使用。Django 本身也是以这种方式打包的。对于像 polls 这样的小型应用程序,这个过程并不难。

  1. 首先,在您的 Django 项目之外创建一个包的父目录。将此目录命名为 django-polls

    选择应用程序的名称

    在选择包的名称时,请检查 PyPI 以避免与现有包发生命名冲突。我们建议使用 django- 前缀作为包名,以标识您的包是特定于 Django 的,并使用相应的 django_ 前缀作为模块名。例如,django-ratelimit 包包含 django_ratelimit 模块。

    应用程序标签(即应用程序包的点分路径的最后一部分)必须INSTALLED_APPS 中是唯一的。避免使用与任何 Django contrib 包 相同的标签,例如 authadminmessages

  2. polls 目录移动到 django-polls 目录中,并将其重命名为 django_polls

  3. 编辑 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"
    
  4. 创建一个名为 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.
    
  5. 创建一个名为 django-polls/LICENSE 的文件。选择许可证超出了本教程的范围,但可以肯定地说,公开发布的没有许可证的代码是无用的。Django 和许多与 Django 兼容的应用程序都在 BSD 许可证下发布;但是,您可以自由选择自己的许可证。请注意,您的许可证选择将影响谁能够使用您的代码。

  6. 接下来,我们将创建 pyproject.tomlsetup.cfgsetup.py 文件,这些文件详细说明了如何构建和安装应用程序。对这些文件的完整解释超出了本教程的范围,但 setuptools 文档 提供了很好的解释。创建 django-polls/pyproject.tomldjango-polls/setup.cfgdjango-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 = [email protected]
    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()
    
  7. 默认情况下,包中只包含 Python 模块和包。要包含其他文件,我们需要创建一个 MANIFEST.in 文件。上一步骤中提到的 setuptools 文档对该文件进行了更详细的讨论。要包含模板、README.rst 和我们的 LICENSE 文件,请创建一个名为 django-polls/MANIFEST.in 的文件,内容如下:

    django-polls/MANIFEST.in
    include LICENSE
    include README.rst
    recursive-include django_polls/static *
    recursive-include django_polls/templates *
    
  8. 包含详细的文档是可选的,但建议这样做。为将来的文档创建一个空目录 django-polls/docs。在 django-polls/MANIFEST.in 中添加一行:

    recursive-include docs *
    

    请注意,除非您在该目录中添加一些文件,否则 docs 目录不会包含在您的包中。许多 Django 应用程序还通过 readthedocs.org 等网站在线提供文档。

  9. 尝试通过在 django-polls 中运行 python setup.py sdist 来构建您的包。这将创建一个名为 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. 更新 mysite/settings.py 以指向新的模块名称。

    INSTALLED_APPS = [
        "django_polls.apps.PollsConfig",
        ...,
    ]
    
  3. 更新 mysite/urls.py 以指向新的模块名称。

    urlpatterns = [
        path("polls/", include("django_polls.urls")),
        ...,
    ]
    
  4. 运行开发服务器以确认项目继续工作。

发布您的应用程序

现在我们已经打包并测试了 django-polls,它已经可以与世界分享了!如果这不仅仅是一个例子,您现在可以

使用虚拟环境安装 Python 包

之前,我们将 django-polls 安装为用户库。这有一些缺点

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

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

返回顶部