進(jìn)階指南：如何編寫可重用程序 | Django 文檔 | Django

寧靜致遠(yuǎn)oj1kn5 2019-06-13

展開全文

進(jìn)階指南：如何編寫可重用程序?

這篇進(jìn)階指南從 Tutorial 7 結(jié)尾的地方繼續(xù)講起。我們將會把我們的 Web-poll 放進(jìn)一個獨立的 Python 包中，以便你在新的項目中重用它或?qū)⑺c他人分享。

如果你尚未完成教程 1-7，我們推薦你先瀏覽一遍教程，這樣你的樣例工程會和下面的一致。

可重用性很重要?

設(shè)計，構(gòu)建，測試以及維護(hù)一個 web 應(yīng)用要做很多的工作。很多 Python 以及 Django 項目都有一些常見問題。如果我們能保存并利用這些重復(fù)的工作豈不是更好？

可重用性是Python的生存方式。 Python軟件包索引（PyPI）有很多可以在你自己的Python程序中使用的軟件包。查看 Django Packages 以了解您可以整合到項目中的現(xiàn)有可重用應(yīng)用。Django本身也只是一個Python包。這意味著您可以將現(xiàn)有的Python包或Django應(yīng)用組合到您自己的Web項目中。您只需編寫您項目獨一無二的部分。

假設(shè)你現(xiàn)在創(chuàng)建了一個新的項目，并且需要一個類似我們之前做的投票應(yīng)用。你該如何復(fù)用這個應(yīng)用呢？慶幸的是，其實你已經(jīng)知道了一些。在教程 1，我們使用過 include 從項目級別的 URLconf 分割出 polls。在本教程中，我們將進(jìn)一步使這個應(yīng)用易用于新的項目中，并發(fā)布給其他人安裝使用。

包？應(yīng)用？

一個 package 提供了一組關(guān)聯(lián)的 Python 代碼的簡單復(fù)用方式。一個包（“模塊”）包含了一個或多個 Python 代碼文件。

一個包通過 import foo.bar 或 from foo import bar 的形式導(dǎo)入。一個目錄（例如 polls）要成為一個包，它必須包含一個特定的文件 __init__.py，即便這個文件是空的。

Django 應(yīng)用 僅僅是專用于 Django 項目的 Python 包。應(yīng)用會按照 Django 約定，創(chuàng)建好 models, tests, urls, 以及 views 等子模塊。

稍后，我們將解釋術(shù)語打包 ——為了方便其它人安裝 Python 包的處理流程。我知道，這可能會使你感到一點點迷惑。

你的項目和可復(fù)用應(yīng)用?

通過前面的教程，我們的工程應(yīng)該看起來像這樣:

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

目錄 polls 現(xiàn)在可以被拷貝至一個新的 Django 工程，且立刻被復(fù)用。不過現(xiàn)在還不是發(fā)布它的時候。為了這樣做，我們需要打包這個應(yīng)用，便于其他人安裝它。

安裝必須環(huán)境?

目前，打包 Python 程序需要工具，有許多工具可以完成此項工作。在此教程中，我們將使用 setuptools 來打包我們的程序。這是推薦的打包工具（與 發(fā)布 分支合并）。我們?nèi)耘f使用 pip 來安裝和卸載這個工具?，F(xiàn)在，你需要安裝這兩個包。如果你需要幫助，你可以參考如何通過 pip 安裝 Django，你可以通過相同的方式安裝 setuptools。

打包你的應(yīng)用?

Python 的打包將以一種特殊的格式組織你的應(yīng)用，意在方便安裝和使用這個應(yīng)用。Django 本身就被打包成類似的形式。對于一個小應(yīng)用，例如 polls，這不會太難。

首先，在你的 Django 項目目錄外創(chuàng)建一個名為 django-polls 的文件夾，用于盛放 polls。
為你的應(yīng)用選擇一個名字
當(dāng)為你的包選一個名字時，避免使用像 PyPI 這樣已存在的包名，否則會導(dǎo)致沖突。當(dāng)你創(chuàng)建你的發(fā)布包時，可以在模塊名前增加 django- 前綴，這是一個很常用也很有用的避免包名沖突的方法。同時也有助于他人在尋找 Django 應(yīng)用時確認(rèn)你的 app 是 Django 獨有的。
應(yīng)用標(biāo)簽（指用點分隔的包名的最后一部分）在 INSTALLED_APPS 中必須是獨一無二的。避免使用任何與 Django contrib packages 文檔中相同的標(biāo)簽名，比如 auth，admin，messages。
將 polls 目錄移入 django-polls 目錄。

創(chuàng)建一個名為 django-polls/README.rst 的文件，包含以下內(nèi)容：

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.

創(chuàng)建一個 django-polls/LICENSE 文件。選擇一個非本教程使用的授權(quán)協(xié)議，但是要足以說明發(fā)布代碼沒有授權(quán)證書是 不可能的 。Django 和很多兼容 Django 的應(yīng)用是以 BSD 授權(quán)協(xié)議發(fā)布的；不過，你可以自己選擇一個授權(quán)協(xié)議。只要確定你選擇的協(xié)議能夠限制未來會使用你的代碼的人。

下一步我們將創(chuàng)建 setup.py 用于說明如何構(gòu)建和安裝應(yīng)用的細(xì)節(jié)。關(guān)于此文件的完整介紹超出了此教程的范圍，但是 setuptools docs 有詳細(xì)的介紹。創(chuàng)建文件 django-polls/setup.py 包含以下內(nèi)容：

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./',
    author='Your Name',
    author_email='yourname@',
    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',
    ],
)

默認(rèn)包中只包含 Python 模塊和包。為了包含額外文件，我們需要創(chuàng)建一個名為 MANIFEST.in 的文件。上一步中關(guān)于 setuptools 的文檔詳細(xì)介紹了這個文件。為了包含模板、README.rst 和我們的 LICENSE 文件，創(chuàng)建文件 django-polls/MANIFEST.in 包含以下內(nèi)容：
django-polls/MANIFEST.in?
```
include LICENSE
include README.rst
recursive-include polls/static *
recursive-include polls/templates *
```
在應(yīng)用中包含詳細(xì)文檔是可選的，但我們推薦你這樣做。創(chuàng)建一個空目錄 django-polls/docs 用于未來編寫文檔。額外添加一行至 django-polls/MANIFEST.in
```
recursive-include docs *
```
注意，現(xiàn)在 docs 目錄不會被加入你的應(yīng)用包，除非你往這個目錄加幾個文件。許多 Django 應(yīng)用也提供他們的在線文檔通過類似這樣的網(wǎng)站。
試著構(gòu)建你自己的應(yīng)用包通過 ptyhon setup.py sdist （在 django-polls``目錄內(nèi)）。這將創(chuàng)建一個名為 ``dist 的目錄并構(gòu)建你自己的應(yīng)用包， django-polls-0.1.tar.gz。

更多關(guān)于打包的信息，見 Python 的關(guān)于打包和發(fā)布項目的教程。

使用你自己的包名?

由于我們把 polls 目錄移出了項目，所以它無法工作了。我們現(xiàn)在要通過安裝我們的新 django-polls 應(yīng)用來修復(fù)這個問題。

作為用戶庫安裝

以下步驟將 django-polls 以用戶庫的形式安裝。與安裝整個系統(tǒng)的軟件包相比，用戶安裝具有許多優(yōu)點，例如可在沒有管理員訪問權(quán)的系統(tǒng)上使用，以及防止應(yīng)用包影響系統(tǒng)服務(wù)和其他用戶。

注意，用戶安裝仍然會影響以這個用戶身份運(yùn)行的系統(tǒng)工具，所以 virtualenv 是一個更強(qiáng)大的解決方案（如下所示）。

為了安裝這個包，使用 pip (你早已安裝 pip, 對嗎？):
```
pip install --user django-polls/dist/django-polls-0.1.tar.gz
```
幸運(yùn)的話，你的 Django 項目應(yīng)該再一次正確運(yùn)行。啟動服務(wù)器確認(rèn)這一點。
通過 pip 卸載包:
```
pip uninstall django-polls
```

發(fā)布你的應(yīng)用?

現(xiàn)在，你已經(jīng)對 django-polls 完成了打包和測試，準(zhǔn)備好向世界分享它！如果這不是一個例子應(yīng)用，你現(xiàn)在就可以這樣做。

通過郵件將你的包發(fā)送給朋友。
將這個包上傳至你的網(wǎng)站。
將你的包發(fā)布至公共倉庫，比如 the Python Package Index (PyPI)。 packaging. 有一個不錯的教程說明如何發(fā)布至公共倉庫。

通過 virtualenv 安裝 Python 包?

早些時候，我們以用戶庫的形式安裝了投票應(yīng)用。這樣做有一些缺點。

修改用戶庫會影響你系統(tǒng)上的其他 Python 軟件。
你將不能運(yùn)行此包的多個版本（或者其它用有相同包名的包）。

一般來說，這些狀況只在你同時運(yùn)行多個 Django 項目時出現(xiàn)。當(dāng)這個問題出現(xiàn)時，最好的解決辦法是使用 virtualenv。這個工具允許你同時運(yùn)行多個相互獨立的Python環(huán)境，每個環(huán)境都有各自庫和應(yīng)用包命名空間的拷貝。