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

这个高级教程从Tutorial 7停止的地方开始。 我们将把我们的Web调查变成一个独立的Python包,您可以在新项目中重复使用并与其他人共享。

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

可重用性很重要

设计,构建,测试和维护Web应用程序有很多工作要做。 许多Python和Django项目都有共同的问题。 如果我们能挽救这些重复的工作,这不是很好吗?

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

比方说,你正在开始一个新项目,需要一个民意调查应用程序,像我们一直在努力。 你如何使这个应用程序可重用? 幸运的是,你已经很好了。 Tutorial 3中,我们看到了如何使用include从项目级URLconf中解耦轮询。 在本教程中,我们将采取进一步措施,使应用程序易于在新项目中使用,并准备发布给其他人进行安装和使用。

包? 应用程序?

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

一个包可以从导入 foo.barfoo t5 > 导入 对于形成一个包的目录(比如polls),它必须包含一个特殊的文件__init__.py,即使这个文件是空的。

Django 应用程序只是专门用于Django项目的Python包。 应用程序可以使用普通的Django惯例,比如具有modelstestsurlsviews子模块。

稍后我们使用术语包装来描述使得其他人可以轻松安装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 . 现在也许更清楚为什么我们选择为项目和应用程序分开模板目录:属于民意测验应用程序的一切都在polls中。 它使应用程序独立,更容易放入一个新的项目。

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

安装一些先决条件

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

打包你的app

Python 包装是指以特定格式准备应用程序,可以轻松安装和使用。 Django本身就是这样打包的。 对于民意调查这样的小应用来说,这个过程并不难。

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

    为您的应用选择一个名称

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

    应用程序标签(即,应用程序包的虚线路径的最后一部分) 必须INSTALLED_APPS中是唯一的. 避免使用与任何Django contrib packages相同的标签,例如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::
    
        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.py文件,其中提供了有关如何构建和安装应用程序的详细信息。 这个文件的完整解释超出了本教程的范围,但是setuptools docs有一个很好的解释。 使用以下内容创建一个文件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',
            'Programming Language :: Python :: 3.5',
            'Programming Language :: Python :: 3.6',
            '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(您已经installed it,对不对?):

    pip install --user django-polls/dist/django-polls-0.1.tar.gz
    
  2. 幸运的是,您的Django项目现在应该再次正常工作。 再次运行服务器以确认这一点。

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

    pip uninstall django-polls
    

发布您的应用

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

用virtualenv 安装Python包

早些时候,我们安装了民意调查应用程序作为用户库。 这有一些缺点:

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

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