Skip to main content

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

这个高级教程开始于 教程7 停止。我们将把Web-poll转换成一个独立的Python包,你可以在新项目中重用,并与其他人分享。

如果您最近没有完成教程1-7,我们建议您查看这些内容,以便您的示例项目与下面描述的一致。

可重用性很重要

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

可重用性是Python中的生活方式。 Python包索引(PyPI) 有一个广泛的包可以在您自己的Python程序中使用。查看 Django包 的现有可重用的应用程序,您可以纳入您的项目。 Django本身也只是一个Python包。这意味着您可以使用现有的Python包或Django应用程序,并将它们组合到您自己的Web项目中。您只需要编写使您的项目独特的部分。

假设你开始一个新项目,需要一个投票应用程序,就像我们一直在做的一样。如何让这个应用程式可重复使用?幸运的是,你已经在路上了。在 教程3 中,我们看到了如何使用 include 将投票从项目级URLconf解耦。在本教程中,我们将采取进一步的步骤,使应用程序易于在新项目中使用,并准备发布供他人安装和使用。

包?应用程序?

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

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

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

稍后我们使用术语 packaging 来描述使Python包易于其他人安装的过程。这可能有点混乱,我们知道。

您的项目和可重复使用的应用程序

在上一个教程之后,我们的项目应该看起来像这样:

mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        wsgi.py
    polls/
        __init__.py
        admin.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。现在也许更清楚为什么我们选择为项目和应用程序具有单独的模板目录:作为poll应用程序的一部分的所有内容都在 polls 中。它使应用程序自包含,并更容易下降到一个新的项目。

polls 目录现在可以复制到一个新的Django项目,并立即重新使用。它还没有准备好发表。为此,我们需要打包应用程序,以方便别人安装。

安装一些先决条件

Python包装的当前状态有点混乱与各种工具。对于本教程,我们将使用 setuptools 来构建我们的包。它是推荐的包装工具(与 distribute fork合并)。我们还将使用 pip 来安装和卸载它。您应该立即安装这两个软件包。如果您需要帮助,您可以参考 how to install Django with pip。您可以以相同的方式安装 setuptools

打包您的应用程序

Python packaging 是指以可以轻松安装和使用的特定格式准备应用程序。 Django本身包装非常喜欢这样。对于像投票的小应用程序,这个过程不是太困难。

  1. 首先,在您的Django项目外部为 polls 创建一个父目录。调用此目录 django-polls

    为应用程式选择名称

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

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

  2. polls 目录移动到 django-polls 目录中。

  3. 创建具有以下内容的文件 django-polls/README.rst

    django-polls/README.rst
    =====
    Polls
    =====
    
    Polls is a simple 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::
    
        url(r'^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 文件。选择许可证超出了本教程的范围,但足以说明没有许可证公开发布的代码是 useless。 Django和许多Django兼容的应用程序是根据BSD许可证分发的;但是,您可以自由选择自己的许可证。请注意,您的许可选择将影响谁能够使用您的代码。

  5. 接下来,我们将创建一个 setup.py 文件,其中提供有关如何构建和安装应用程序的详细信息。这个文件的完整解释超出了本教程的范围,但是 setuptools文档 有一个很好的解释。创建具有以下内容的文件 django-polls/setup.py

    django-polls/setup.py
    import os
    from setuptools import find_packages, setup
    
    with open(os.path.join(os.path.dirname(__file__), 'README.rst')) as readme:
        README = readme.read()
    
    # allow setup.py to be run from any path
    os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))
    
    setup(
        name='django-polls',
        version='0.1',
        packages=find_packages(),
        include_package_data=True,
        license='BSD License',  # example license
        description='A simple Django app to conduct Web-based polls.',
        long_description=README,
        url='https://www.example.com/',
        author='Your Name',
        author_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',  # example license
            'Operating System :: OS Independent',
            'Programming Language :: Python',
            # Replace these appropriately if you are stuck on Python 2.
            'Programming Language :: Python :: 3',
            'Programming Language :: Python :: 3.4',
            'Programming Language :: Python :: 3.5',
            'Topic :: Internet :: WWW/HTTP',
            'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
        ],
    )
    
  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 安装为用户库。每用户安装比在整个系统上安装软件包有很多优点,例如在没有管理员访问权限的系统上使用,以及防止软件包影响系统服务和机器的其他用户。

请注意,每用户安装仍然可以影响作为该用户运行的系统工具的行为,因此 virtualenv 是一个更强大的解决方案(见下文)。

  1. 要安装软件包,使用pip(你已经是 安装它,对吧?):

    pip install --user django-polls/dist/django-polls-0.1.tar.gz
    
  2. 运气好的话,你的Django项目现在应该能正常工作了。再次运行服务器以确认此。

  3. 要卸载软件包,请使用pip:

    pip uninstall django-polls
    

发布应用程式

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

使用virtualenv安装Python软件包

以前,我们将polling应用程序安装为用户库。这有一些缺点:

  • 修改用户库可能会影响系统上的其他Python软件。

  • 您将无法运行此程序包的多个版本(或其他具有相同名称的程序包)。

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