“全能”选手—Django 1.10文档中文版Part4

欢迎大家访问我的主页：www.liujiangblog.com

---

第一部分传送门

第二部分传送门

第三部分传送门

3.2 模型和数据库Models and databases

3.2.2 查询操作making queries

3.3.8 会话sessions

2.10 高级教程：如何编写可重用的apps

2.10.1 重用的概念

The Python Package Index (PyPI)有大量的现成可用的Python库。https://www.djangopackages.com
作为Django的app基地也有大量现成可用的apps。

包？App?
包是python重用代码的方式，以目录的形式体现，需要包含__init__.py文件，采用import的方式导入。
app则是Django专用的包，包含一些通用的Django组件，例如models、tests、urls和views等子模块。

2.10.2 你的项目和可重用的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

它已经具备的project和app分离的条件。但是还需要一个打包的过程。

2.10.3 安装一些必要工具

使用setuptools和pip来打包我们的app。请先安装他们。
https://pypi.python.org/pypi/setuptools
https://pypi.python.org/pypi/pip

2.10.4 打包你的app

打包的意思是让你的app具有一种特殊的格式，使得它更容易被安装和使用。

1. 首先，在Django项目外面，为你的polls应用，准备一个父目录，取名django-polls；

   为你的app选择一个合适的名字：
   在取名前，去PYPI搜索一下是否有重名或冲突的包已经存在。建议给包名加上“django-”的前缀。名字中最后一个圆点的后面部分在INSTALLED_APPS中一定要独一无二，不能和任何Django的contrib packages中的重名，例如auth、admin、messages等等你。

2. 拷贝polls目录到该目录内；

3. 创建一个文件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
-----------
64 Chapter 2. Getting started
Django Documentation, Release 1.10.2a1
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版权申明文件。大多数Django相关的app都基于BSD版权。
5. 接下来创建一个setup.py文件，用于编译和安装app。如何创建这个，请前往setuptools的官方文档获取详细的教程，本文不涉及。具体内容如下：

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的模块和包会被打包进我们的app内。为了包含一些附加的文件，需要创建一个MANIFEST.in文件。为了将静态文件，模板等等非python语言编写的文件打包入内，我们需要在django-polls/MANIFEST.in文件内写入：

    include LICENSE
    include README.rst
    recursive-include polls/static *
    recursive-include polls/templates *

7. 该步骤可选，但是强烈推荐，将详细的说明文档一起打包。创建一个空的目录django-polls/docs，用于放置你的app相关文档。同时不要忘了，在django-polls/MANIFEST.in文件内写入一行recursive-include docs *。需要注意的是，如果docs目录是空的，那么它不会被打包进去。当然，许多apps通过在线的网站提供文档阅读。
8. 在你的django-polls目录内，运行python setup.py sdist命令。这将会创建一个dist目录，并编译成功你的新包，django-polls-0.1.tar.gz。

2.10.5 使用你自己的包

在安装包的时候，最好是以个人身份安装，而不是全系统范围的身份。这样可以有效减少给别的用户带去的影响或被别的用户影响。当然，最好的方式是在virtualenv环境下，类似隔离的沙盒环境。

1. 使用pip安装：pip install --user django-polls/dist/django-polls-0.1.tar.gz
2. 现在你可以在项目中使用这个包了
3. 卸载：pip uninstall django-polls

2.10.6 发布你的app

你可以：

• 通过邮件的形式发送给朋友
• 上传包到你的网站
• 推送到一个公开的仓库，例如PyPI，github等

https://packaging.python.org/distributing/#uploading-your-project-to-pypi是如何上传到PyPI的教程。

2.10.7 如何在virtualenv中安装python的包

前面，我们安装polls应用作为一个用户库，它有一些缺点：

• 修改用户库会影响到你系统上的其它Python软件
• 你无法同时运行此包的多个版本

解决这个问题最好的办法就是使用virtualenv。详见https://virtualenv.pypa.io/en/stable/

2.11 接下来学什么

本节主要介绍Django文档的划分，各部分的侧重点，如何找到自己感兴趣的内容。
由于此部分和文档最前面的目录导航重复较多，并且比较简单，就不翻译了。

2.11.1 在文档中查找
2.11.2 文档是如何组织的
2.11.3 文档是如何更新的
2.11.4 从哪里获取文档
2.11.5 不同版本之间的区别

2.12 编写你的第一个Django补丁

**待翻译！**