Django 1.10文档中文版Part4

2023-08-11 22:23:40

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具有一种特殊的格式，使得它更容易被安装和使用。

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

为你的app选择一个合适的名字：
在取名前，去PYPI搜索一下是否有重名或冲突的包已经存在。建议给包名加上“django-”的前缀。名字中最后一个圆点的后面部分在INSTALLED_APPS中一定要独一无二，不能和任何Django的contrib packages中的重名，例如auth、admin、messages等等你。
拷贝polls目录到该目录内；
创建一个文件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.

创建一个django-polls/LICENSE版权申明文件。大多数Django相关的app都基于BSD版权。
接下来创建一个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',

    ],

)

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

    include LICENSE

    include README.rst

    recursive-include polls/static *

    recursive-include polls/templates *

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

2.10.5 使用你自己的包

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

使用pip安装：pip install --user django-polls/dist/django-polls-0.1.tar.gz
现在你可以在项目中使用这个包了
卸载：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补丁

**待翻译！**

码农公寓