“全能”選手—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='[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',
        # 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補丁

**待翻譯！**