Django4.0 開始-編寫可重用程序

可重用性很重要

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

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

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

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

安裝必須環(huán)境

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

打包你的應(yīng)用

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

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

當(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?。

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

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

5、接下來我們將創(chuàng)建 ?pyproject.toml?、?setup.cfg? 和 ?setup.py? 文件，詳細說明如何構(gòu)建和安裝該應(yīng)用程序。對這些文件的全面解釋超出了本教程的范圍，但 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 模塊和包。 要包含其他文件，我們需要創(chuàng)建一個 ?MANIFEST.in? 文件。 上一步中提到的 ?setuptools ?文檔更詳細地討論了這個文件。 要包含模板、?README.rst? 和我們的 ?LICENSE ?文件，創(chuàng)建一個文件 ?django-polls/MANIFEST.in? ，其內(nèi)容如下：

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

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

recursive-include docs *

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

8、試著構(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?。

使用你自己的包名

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

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

1、為了安裝這個包，使用 pip:

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

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

3、通過 pip 卸載包：

python -m 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.python.org 有一個不錯的 教程 說明如何發(fā)布至公共倉庫。

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

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

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

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