7. 扩展 Distutils — Python 文档

7. 扩展 Distutils

笔记

本文档仅保留到 https://setuptools.readthedocs.io/en/latest/setuptools.html 上的 setuptools 文档独立涵盖当前包含在此处的所有相关信息之前。

Distutils 可以通过多种方式进行扩展。 大多数扩展采用新命令或替换现有命令的形式。 例如，可以编写新命令以支持新类型的特定于平台的包，而可以替换现有命令以修改命令如何对包进行操作的细节。

distutils 的大多数扩展是在想要修改现有命令的 setup.py 脚本中进行的； 为了方便，除了 .py 文件之外，许多人只是添加了一些应该复制到包中的文件扩展名。

大多数 distutils 命令实现是 distutils.cmd.Command 类的子类。 新命令可以直接从 Command 继承，而替换命令通常从 Command 间接继承，直接子类化它们正在替换的命令。 命令需要从 Command 派生。

7.1. 集成新命令

有不同的方法可以将新的命令实现集成到 distutils 中。 最困难的是游说将新功能包含在 distutils 本身中，并等待（并需要）提供该支持的 Python 版本。 这真的很难，原因有很多。

最常见的，也可能是大多数需求最合理的，是在你的 setup.py 脚本中包含新的实现，并让 distutils.core.setup() 函数使用它们：

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},
      ...)

如果必须使用新的实现来使用特定的包，这种方法是最有价值的，因为对包感兴趣的每个人都需要有新的命令实现。

从 Python 2.4 开始，提供了第三个选项，旨在允许添加新命令，这些命令可以支持现有的 setup.py 脚本，而无需修改 Python 安装。 预计这将允许第三方扩展为其他打包系统提供支持，但这些命令可用于 distutils 命令可用于的任何内容。 新的配置选项 command_packages（命令行选项 --command-packages）可用于指定要搜索的附加包以查找实现命令的模块。 像所有 distutils 选项一样，这可以在命令行或配置文件中指定。 此选项只能在配置文件的 [global] 部分中设置，或在命令行上的任何命令之前设置。 如果在配置文件中设置，则可以从命令行覆盖； 在命令行上将其设置为空字符串会导致使用默认值。 这不应在随包提供的配置文件中设置。

这个新选项可用于将任意数量的包添加到搜索命令实现的包列表中； 多个包名应该用逗号分隔。 如果未指定，则仅在 distutils.command 包中执行搜索。 但是，当 setup.py 与选项 --command-packages distcmds,buildcmds 一起运行时，将搜索包 distutils.command、distcmds 和 buildcmds以该顺序。 新命令预计将通过共享相同名称的类在与命令名称相同的模块中实现。 鉴于上面的示例命令行选项，命令 bdist_openpkg 可以由类 distcmds.bdist_openpkg.bdist_openpkg 或 buildcmds.bdist_openpkg.bdist_openpkg 实现。

7.2. 添加新的分发类型

创建发行版的命令（dist/ 目录下的文件）需要将 (command, filename) 对添加到 self.distribution.dist_files 以便 upload 可以将其上传到 PyPI。 该对中的 文件名 不包含路径信息，仅包含文件本身的名称。 在试运行模式下，仍应添加对以表示已创建的内容。