Django4.0 開(kāi)始-編寫(xiě)可重用程序

可重用性很重要

設(shè)計(jì)，構(gòu)建，測(cè)試以及維護(hù)一個(gè) web 應(yīng)用要做很多的工作。很多 Python 以及 Django 項(xiàng)目都有一些常見(jiàn)問(wèn)題。如果我們能保存并利用這些重復(fù)的工作豈不是更好？
可重用性是 Python 的根本。The Python Package Index (PyPI) 有許多大量的包，都可被用在你自己的 Python 項(xiàng)目中。同樣可以在 Django Packages 中查找已發(fā)布的可重用應(yīng)用，也可將其引入到你的項(xiàng)目中。Django 本身也是一個(gè) Python 包，也就是說(shuō)你可以將已有的 Python 包或 Django 應(yīng)用并入你的項(xiàng)目。你只需要編寫(xiě)屬于你的那部分即可。
假設(shè)你現(xiàn)在創(chuàng)建了一個(gè)新的項(xiàng)目，并且需要一個(gè)類似我們之前做的投票應(yīng)用。你該如何復(fù)用這個(gè)應(yīng)用呢？慶幸的是，其實(shí)你已經(jīng)知道了一些。在 教程 1，我們使用過(guò) ?include ?從項(xiàng)目級(jí)別的 URLconf 分割出 polls。在本教程中，我們將進(jìn)一步使這個(gè)應(yīng)用易用于新的項(xiàng)目中，并發(fā)布給其他人安裝使用。

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

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

mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py
    polls/
        __init__.py
        admin.py
        apps.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

你在 教程 7 中創(chuàng)建了 ?mysite/templates?，在 教程 3 中創(chuàng)建了 ?polls/templates?。現(xiàn)在也許更清楚為什么我們選擇為項(xiàng)目和應(yīng)用程序設(shè)置單獨(dú)的模板目錄：所有屬于 ?polls ?應(yīng)用程序的部分都在 ?polls ?中。這使得應(yīng)用程序自成一體，更容易放到一個(gè)新項(xiàng)目中。
目錄 ?polls ?現(xiàn)在可以被拷貝至一個(gè)新的 Django 工程，且立刻被復(fù)用。不過(guò)現(xiàn)在還不是發(fā)布它的時(shí)候。為了這樣做，我們需要打包這個(gè)應(yīng)用，便于其他人安裝它。

安裝必須環(huán)境

目前，打包 Python 程序需要工具，有許多工具可以完成此項(xiàng)工作。在此教程中，我們將使用 setuptools 來(lái)打包我們的程序。這是推薦的打包工具（與 發(fā)布 分支合并）。我們?nèi)耘f使用 pip 來(lái)安裝和卸載這個(gè)工具。現(xiàn)在，你需要安裝這兩個(gè)包。

打包你的應(yīng)用

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

1、首先，在你的 Django 項(xiàng)目目錄外創(chuàng)建一個(gè)名為 ?django-polls? 的文件夾，用于盛放 ?polls?。

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

2、將 ?polls目錄移入 ?django-polls? 目錄。

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

=====
Polls
=====

Polls is a 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.

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

5、接下來(lái)我們將創(chuàng)建 ?pyproject.toml?、?setup.cfg? 和 ?setup.py? 文件，詳細(xì)說(shuō)明如何構(gòu)建和安裝該應(yīng)用程序。對(duì)這些文件的全面解釋超出了本教程的范圍，但 setuptools 文檔 有很好的解釋。創(chuàng)建 ?django-polls/pyproject.toml?、?django-polls/setup.cfg? 和 ?django-polls/setup.py? 文件，內(nèi)容如下：

[build-system]
requires = ['setuptools>=40.8.0', 'wheel']
build-backend = 'setuptools.build_meta:__legacy__'

[metadata]
name = django-polls
version = 0.1
description = A Django app to conduct web-based polls.
long_description = file: README.rst
url = https://www.example.com/
author = Your Name
author_email = yourname@example.com
license = BSD-3-Clause  # Example license
classifiers =
    Environment :: Web Environment
    Framework :: Django
    Framework :: Django :: X.Y  # Replace "X.Y" as appropriate
    Intended Audience :: Developers
    License :: OSI Approved :: BSD License
    Operating System :: OS Independent
    Programming Language :: Python
    Programming Language :: Python :: 3
    Programming Language :: Python :: 3 :: Only
    Programming Language :: Python :: 3.8
    Programming Language :: Python :: 3.9
    Topic :: Internet :: WWW/HTTP
    Topic :: Internet :: WWW/HTTP :: Dynamic Content

[options]
include_package_data = true
packages = find:
python_requires = >=3.8
install_requires =
    Django >= X.Y  # Replace "X.Y" as appropriate

from setuptools import setup

setup()

6、默認(rèn)情況下，包中僅包含 Python 模塊和包。 要包含其他文件，我們需要?jiǎng)?chuàng)建一個(gè) ?MANIFEST.in? 文件。 上一步中提到的 ?setuptools ?文檔更詳細(xì)地討論了這個(gè)文件。 要包含模板、?README.rst? 和我們的 ?LICENSE ?文件，創(chuàng)建一個(gè)文件 ?django-polls/MANIFEST.in? ，其內(nèi)容如下：

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

7、在應(yīng)用中包含詳細(xì)文檔是可選的，但我們推薦你這樣做。創(chuàng)建一個(gè)空目錄? django-polls/docs? 用于未來(lái)編寫(xiě)文檔。額外添加一行至 ?django-polls/MANIFEST.in?

recursive-include docs *

注意，現(xiàn)在 ?docs ?目錄不會(huì)被加入你的應(yīng)用包，除非你往這個(gè)目錄加幾個(gè)文件。許多 Django 應(yīng)用也提供他們的在線文檔通過(guò)類似 readthedocs.org 這樣的網(wǎng)站。

8、試著構(gòu)建你自己的應(yīng)用包通過(guò) ?ptyhon setup.py sdist? （在 ?django-polls``?目錄內(nèi)）。這將創(chuàng)建一個(gè)名為 ?``dist? 的目錄并構(gòu)建你自己的應(yīng)用包， ?django-polls-0.1.tar.gz?。

使用你自己的包名

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

以下步驟將 ?django-polls? 以用戶庫(kù)的形式安裝。與安裝整個(gè)系統(tǒng)的軟件包相比，用戶安裝具有許多優(yōu)點(diǎn)，例如可在沒(méi)有管理員訪問(wèn)權(quán)的系統(tǒng)上使用，以及防止應(yīng)用包影響系統(tǒng)服務(wù)和其他用戶。
請(qǐng)注意，按用戶安裝仍然會(huì)影響以該用戶身份運(yùn)行的系統(tǒng)工具的行為，因此使用虛擬環(huán)境是更可靠的解決方案（請(qǐng)參見(jiàn)下文）。

1、為了安裝這個(gè)包，使用 pip:

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

2、幸運(yùn)的話，你的 Django 項(xiàng)目應(yīng)該再一次正確運(yùn)行。啟動(dòng)服務(wù)器確認(rèn)這一點(diǎn)。

3、通過(guò) pip 卸載包：

python -m pip uninstall django-polls

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

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

• 通過(guò)郵件將你的包發(fā)送給朋友。
• 將這個(gè)包上傳至你的網(wǎng)站。
• 將你的包發(fā)布至公共倉(cāng)庫(kù)，比如 ?the Python Package Index? (?PyPI?)。 packaging.python.org 有一個(gè)不錯(cuò)的 教程 說(shuō)明如何發(fā)布至公共倉(cāng)庫(kù)。

通過(guò)虛擬環(huán)境安裝Python包

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

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

通常，只有在維護(hù)多個(gè) Django 項(xiàng)目時(shí)才會(huì)出現(xiàn)這些情況。當(dāng)這樣做時(shí)，最好的解決方法是使用 ?venv?。使用此工具，你可以維護(hù)多個(gè)隔離的 Python 環(huán)境，每個(gè)環(huán)境都有其自己的庫(kù)和包命名空間的副本。