Django 2.0.1 官方文档翻译: 高级教程：如何编写可重用的app （page 13）

高级教程：如何编写可重用的app （page 13）

本节教程上接第七部分（Page 12）。我们会把我们的 web-poll应用转换成一个独立的python包，你可以在新的项目中重用或者把它分享给其他人。

如果你没有学习完1-7部分的教程，我们建议你回顾这些教程，以便你的实例项目匹配下面的描述。

可重用性问题

设计、构建、测试和维护一个web应用需要做很多工作。许多python和django项目都有共同的问题。如果我们保存一些重复性的工作，不是会更好么？

可重用性是python中的一种常见方式。 The Python Package Index (PyPI)中有大量可以在你自己的python程序中使用的包。 Django Packages 中已有的可重用的app你都可以结合到你的项目中。Django自己也是一个python包。也就是说，你可以使用一个已有的python包或者django app，把他们融合到你自己的web项目中。你只需要编写你项目中独有的部分。

假设你已经启动了一个需要使用一个类似我们前面编写的polls app的新项目。你要如何重用这个app呢？幸运的是，你已经拥有正确的方法了。在第三部分（page 8）中，我们看到了我们是如何使用include从项目级的URLconf中解耦出polls应用。在本节教程中，我们会进一步是app易于在新项目中使用，并为他们安装和使用做准备。

Package? App? 包？ 应用？

python package提供一种把有相关性的代码分成一组以易于重用的方式。一个package包含一个或多个python代码文件（也成为“模块”）。

包可以通过import foo.bar或 from foo import bar的方式被导入。一个目录要形成一个包，它必须包含一个特殊的init.py文件，即使这个文件是空的。

一个django应用就是一个专门供django项目使用的python package。一个应用可以使用通用的django约定，例如包含models, tests, urls, 和 views子模块。

稍后，我们使用打包这个术语去描述让python package易于其他人安装的过程。这可能会有点让人迷惑。

你的项目和你的可重用app

经过学习前面的教程，我们的项目看起来会像下面一样：

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

你在第七部分（page 12）中创建了mysite/templates，在第三部分（page 8）中创建了polls/templates。现在你可能清楚了为什么我们要给项目和应用选择单独的模板目录：polls应用中的部分都在 polls中，这使应用自成一体并更容易放入新项目中。polls目录现在可以被复制到一个新的django项目中，并立刻重用。尽管还没做好发布它的准备。为此，我们需要打包这个app，让它方便其他人安装。

安装一些先决条件（prerequisites）

因为使用多种工具，现在的打包状态有一点混乱。对本节教程来说，我们会使用setuptools工具去构建我们的包。它是一个推荐的打包工具（已经和distribute分支合并）。我们还会使用pip去安装和卸载它。现在你应该安装这两个包。如果你需要帮助，你可以参考how to install Django with pip.你可以使用相同的方式来安装setuptools。

打包你的app

python打包是指以特定的格式编写应用程序，这种格式可以很容易被安装和使用。Django就是类似这样方式被打包的。对于像polls这样的小应用，处理过程不会太困难。

1. 首先，在你的django项目之外，为polls创建一个父目录。这个目录是django-polls。

为你的app选择一个名字

当为你的app选择名字时，检查类似PyPI的源，避免和已存在的包有命名冲突。当创建一个包的来分发时，将django-作为模块名的开头通常会很有用。这会帮助其他人寻找django app时，分辨出你的app是专门用于django的

应用标签（也就是应用程序包的点分路径的最后一部分）在INSTALLED_APPS（少一个链接）中必须是唯一的，避免和任何django contrib packages少一个链接）使用相同的标签，例如auth, admin, 或 messages。

1. 把polls目录移动到django-polls目录。

2. 创建一个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.
   

3. 创建一个django-polls/LICENSE文件,选择许可证超出了本教程的范围，但值得一提的是，未经许可发布的代码是无用的。django和许多兼容django的app都以BSD许可证发布。不管怎么说，你可以*选择你的许可证。需要注意你选择的许可证会影响到谁可以使用你的代码。

4. 下一步，我们会创建一个setup.py文件，它可以提供关于如何构建和安装app的细节，关于这个文件的完整解释超出了本教程的范围，但setup.py有一个很好的解释。使用下面的内容创建一个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='[e-mail]',
       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',
       ],
   )
   
   

5. 默认情况下只有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 *
   

6. 在app中包含详细的文档是可选的，但建议你这么做。创建一个django-polls/docs空目录，用于以后保存文档。在django-polls/MANIFEST.in中添加额外的一行：

   recursive-include docs *
   

   注意docs目录不会被打包进你的包，除非你在它下面添加一些文件。许多Django app都会通过类似readthedocs.org这样的站点提供他们的文档。

7. 尝试使用 python setup.py sdist 构建你的包(在django-polls运行)。这样会创建一个名字是dist的目录，并构建一个新的包：django-polls-0.1.tar.gz。

更多关于打包的信息，请看Tutorial on Packaging and Distributing Projects

使用你自己的package(包)

从我们将polls目录从项目中移出后，它就不再工作了。现在我们通过安装django-polls包来修复这个问题。

安装成用户库

下面步骤是把django-polls安装成用户的库。用户级安装相比系统级安装有很多优势，例如在没有管理员权限的系统上使用，以及防止包影响机器上的系统服务和其他用户。

注意用户级安装仍可以影响以该用户运行的系统工具，所以virtualenv是一个更可靠的方案。

1. 使用pip安装这个包（你已经把pip安装好了，对不对？参考本页上面安装先决条件的部分）

   pip install --user django-polls/dist/django-polls-0.1.tar.gz
   

2. 幸运的话，你的django项目现在应该再次正常工作了。运行服务器来确认。

3. 使用pip卸载这个包：

   pip uninstall django-polls
   

发布你的app

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

• 把这个包用Email发送给你的朋友
• 把这个包上传到你的站点上
• 把这个包提交到一个公共仓库，例如the Python Package Index (PyPI)。packaging.python.org上有很好的教程 告诉你如何操作。

使用virtualenv安装python包

前面，我们把polls app安装成了一个用户库。这样做有一些缺点：

• 修改用户库可能会影响你系统中的其他python软件。
• 你将不能运行该包的多个版本（或者具有相同名称的其他版本）

通常，一旦你维护多个django项目时，这种情况就会出现。当出现这种情况，最好的解决方案就是使用 virtualenv。这个工具允许你运行多个隔离的python环境，每个环境都有它自己的库和包的命名空间。