7. 擴(kuò)展 Distutils?

備注

這篇文檔是歷史遺留文檔，在 https://setuptools.readthedocs.io/en/latest/setuptools.html 上的 setuptools 文檔獨(dú)立涵蓋此處包含的所有相關(guān)信息之后，將不再單獨(dú)作為正式文檔保留。

Distutils 可以通過各種方式擴(kuò)展。 大多數(shù)擴(kuò)展都采用新命令或現(xiàn)有命令的替換形式。 例如，可以編寫新命令以支持新的特定于平臺(tái)的包格式，但是可以修改現(xiàn)有命令的替換，以修改命令在包上的操作細(xì)節(jié)。

distutils 的大多數(shù)擴(kuò)展都在想要修改現(xiàn)有命令的 setup.py 腳本中編寫；其中許多只是簡(jiǎn)單地在 .py 文件以外添加了一些應(yīng)當(dāng)被拷貝到包中的文件后綴以便使用。

大多部 distutils 命令的實(shí)現(xiàn)都是 distutils.cmd.Command 類的子類。 新增命令可直接繼承自 Command，而替換命令往往間接派生自 Command， 直接子類化它們所替換的命令。 所有命令都要求自 Command 派生。

7.1. 集成新的命令?

有多種方法可將新的命令實(shí)現(xiàn)集成到 distutils 中。 最困難的一種是鼓動(dòng)在 distutils 自身內(nèi)部包含新特性，并等待（以及要求）某個(gè) Python 版本提供該支持。 出于多種原因，這確實(shí)是相當(dāng)難的。

對(duì)于大多數(shù)需求來(lái)說最為常見并且可能最為合理的一種則是通過你自己的 setup.py 腳本來(lái)包含新的實(shí)現(xiàn)，然后讓 distutils.core.setup() 函數(shù)使用它們:

from distutils.command.build_py import build_py as _build_py
from distutils.core import setup

class build_py(_build_py):
    """Specialized Python source builder."""

    # implement whatever needs to be different...

setup(cmdclass={'build_py': build_py},
      ...)

如果新的實(shí)現(xiàn)必須通過特定的包來(lái)使用則此方式最為適宜，因?yàn)槊總€(gè)對(duì)這個(gè)包感興趣的人都將會(huì)需要有新的命令實(shí)現(xiàn)。

從 Python 2.4 開始，還有第三個(gè)選項(xiàng)可用，其目標(biāo)是允許添加支持現(xiàn)有 setup.py 腳本的新命令，而不需要修改 Python 安裝包。 這預(yù)計(jì)可允許第三方擴(kuò)展提供對(duì)附加打包系統(tǒng)的支持，而相應(yīng)命令又可用于任何 distutils 命令可被使用的地方。 新的配置選項(xiàng) command_packages (命令行選項(xiàng)為 --command-packages) 可用來(lái)指定附加包，以在其中查找實(shí)現(xiàn)新增命令的模塊。 像所有 distutils 選項(xiàng)一樣，這可以通過命令行或配置文件來(lái)指定。 此選項(xiàng)只能在配置文件的 [global] 小節(jié)之中或在命令行的任何命令之前設(shè)置。 如果是設(shè)置在配置文件中，則它可被命令行設(shè)置重載；如果在命令行中將其設(shè)為空字符串則將會(huì)使用默認(rèn)值。 此選項(xiàng)絕不應(yīng)當(dāng)在隨特定包提供的配置文件中設(shè)置。

這個(gè)新選項(xiàng)可被用來(lái)添加任意數(shù)量的包到查找命令實(shí)現(xiàn)的包列表；多個(gè)包名應(yīng)當(dāng)以逗號(hào)分隔。 當(dāng)未指明時(shí)，查找將只在 distutils.command 包中進(jìn)行。 但是當(dāng) setup.py 附帶 --command-packages distcmds,buildcmds 選項(xiàng)運(yùn)行時(shí)，distutils.command, distcmds 和 buildcmds 包將按此順序被查找。 新的命令應(yīng)當(dāng)在與命名同名的模塊中由同名的類來(lái)實(shí)現(xiàn)。 給定上述示例命令行選項(xiàng)，則命令 bdist_openpkg 可由類 distcmds.bdist_openpkg.bdist_openpkg 或 buildcmds.bdist_openpkg.bdist_openpkg 來(lái)實(shí)現(xiàn)。

7.2. 添加新的發(fā)布類型?

創(chuàng)建發(fā)布（在 dist/ 目錄中的文件）的命令需要將 (command, filename) 二元組添加到 self.distribution.dist_files 以便 upload 可以將其上傳到 PyPI。 二元組中的 filename 不包含路徑信息而只有文件名本身。 在 dry-run 模式下，二元組仍然應(yīng)當(dāng)被添加以表示必須創(chuàng)建的內(nèi)容。