9. API 参考 — Python 文档

9. API 参考

也可以看看

setuptools 中新增和更改的 setup.py 参数

setuptools 项目为 setup 函数和其他 API 添加了新功能，使 API 在不同 Python 版本之间保持一致，因此建议不要直接使用 distutils。

笔记

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

9.1. distutils.core — 核心 Distutils 功能

distutils.core 模块是唯一需要安装才能使用 Distutils 的模块。 它提供了 setup()（从安装脚本调用）。 间接提供了 distutils.dist.Distribution 和 distutils.cmd.Command 类。

distutils.core.setup(arguments)

基本的无所不能功能，可以完成您可能从 Distutils 方法中要求的大多数事情。

setup 函数接受大量参数。 这些在下表中列出。

参数名称	价值	类型
姓名	包名	一个字符串
版本	包的版本号； 见 distutils.version	一个字符串
描述	描述包的单行	一个字符串
详细描述	包的详细说明	一个字符串
作者	包作者的名字	一个字符串
author_email	包作者的电子邮件地址	一个字符串
维护者	当前维护者的姓名（如果与作者不同）。 注意，如果提供了维护者，distutils 会在 PKG-INFO 中以作者身份使用	一个字符串
维护者电子邮件	当前维护者的电子邮件地址，如果与作者不同	一个字符串
网址	包的 URL（主页）	一个字符串
下载地址	下载包的 URL	一个字符串
包裹	distutils 将操作的 Python 包列表	字符串列表
py_modules	distutils 将操作的 Python 模块列表	字符串列表
脚本	要构建和安装的独立脚本文件列表	字符串列表
ext_modules	要构建的 Python 扩展列表	distutils.core.Extension 的实例列表
分类器	包的类别列表	字符串列表； PyPI 上列出了有效的分类器。
分类	要使用的 Distribution 类	distutils.core.Distribution 的子类
脚本名称	setup.py 脚本的名称 - 默认为 sys.argv[0]	一个字符串
脚本参数	提供给安装脚本的参数	字符串列表
选项	安装脚本的默认选项	一本字典
执照	包的许可证	一个字符串
关键词	描述性元数据，参见 PEP 314	字符串列表或逗号分隔的字符串
平台		字符串列表或逗号分隔的字符串
cmd类	命令名称到 Command 子类的映射	一本字典
数据文件	要安装的数据文件列表	一个列表
包目录	包到目录名的映射	一本字典

distutils.core.run_setup(script_name[, script_args=None, stop_after='run'])

在稍微受控的环境中运行安装脚本，并返回驱动事物的 distutils.dist.Distribution 实例。 如果您需要找出分发元数据（作为关键字参数从 script 传递到 setup()），或者配置文件或命令行的内容，这很有用.

script_name 是一个将使用 exec() 读取和运行的文件。 sys.argv[0] 将在通话期间替换为 script。 script_args 是一个字符串列表； 如果提供，sys.argv[1:] 将在通话期间被 script_args 替换。

stop_after 告诉 setup() 何时停止处理； 可能的值：

价值	描述
在里面	在创建 Distribution 实例并使用 setup() 的关键字参数填充后停止
配置	在配置文件被解析后停止（并且它们的数据存储在 Distribution 实例中）
命令行	在命令行（sys.argv[1:] 或 script_args）被解析（以及存储在 Distribution 实例中的数据）后停止。
跑	在所有命令运行后停止（就像 setup() 以通常的方式被调用一样）。 这是默认值。

此外，distutils.core 模块公开了许多位于其他地方的类。

• Extension 来自 distutils.extension
• Command 来自 distutils.cmd
• Distribution 来自 distutils.dist

下面是对其中每一个的简短描述，但请参阅相关模块以获取完整参考。

class distutils.core.Extension

Extension 类在安装脚本中描述单个 C 或 C++ 扩展模块。 它在其构造函数中接受以下关键字参数：

参数名称	价值	类型
姓名	扩展的全名，包括任何包——即。 不是 文件名或路径名，而是 Python 点名	一个字符串
来源	源文件名列表，相对于分发根目录（安装脚本所在的位置），以 Unix 形式（斜杠分隔）以方便移植。 源文件可能是 C、C++、SWIG (.i)、特定于平台的资源文件，或任何其他被 build_ext 命令识别为 Python 扩展源的文件。	字符串列表
包含目录	用于搜索 C/C++ 头文件的目录列表（以 Unix 形式用于可移植性）	字符串列表
定义宏	要定义的宏列表； 每个宏都使用 2 元组 (name, value) 定义，其中 value 是定义它的字符串或 None 来定义它而没有特定值（相当于 [源代码中的 X201X] 或 Unix C 编译器命令行中的 -DFOO）	元组列表
undef_宏	要明确取消定义的宏列表	字符串列表
图书馆目录	在链接时搜索 C/C++ 库的目录列表	字符串列表
图书馆	要链接的库名称列表（不是文件名或路径）	字符串列表
runtime_library_dirs	在运行时搜索 C/C++ 库的目录列表（对于共享扩展，这是加载扩展时）	字符串列表
extra_objects	要链接的额外文件列表（例如。 “源”未隐含的目标文件、必须明确指定的静态库、二进制资源文件等）	字符串列表
extra_compile_args	在“源”中编译源文件时要使用的任何额外的特定于平台和编译器的信息。 对于命令行有意义的平台和编译器，这通常是命令行参数列表，但对于其他平台，它可以是任何内容。	字符串列表
extra_link_args	在将目标文件链接在一起以创建扩展（或创建新的静态 Python 解释器）时使用的任何额外的平台和编译器特定信息。 与“extra_compile_args”类似的解释。	字符串列表
export_symbols	要从共享扩展导出的符号列表。 并非在所有平台上都使用，并且通常不需要 Python 扩展，通常只导出一个符号：init + extension_name。	字符串列表
要看	扩展所依赖的文件列表	字符串列表
语	扩展语言（即 'c'、'c++'、'objc'）。 如果未提供，将从源扩展中检测到。	一个字符串
可选的	指定扩展中的构建失败不应中止构建过程，而只是跳过扩展。	一个布尔值

3.8 版更改： 在 Unix 上，除 Android 和 Cygwin 外，C 扩展不再链接到 libpython。

class distutils.core.Distribution

Distribution 描述了如何构建、安装和打包 Python 软件包。

有关 Distribution 构造函数接受的关键字参数列表，请参阅 setup() 函数。 setup() 创建一个分发实例。

3.7 版更改：分布 现在警告 classifiers、keywords 和 platforms 字段未指定为列表或细绳。

class distutils.core.Command

Command 类（或者更确切地说，它的一个子类的实例）实现了单个 distutils 命令。

9.2. distutils.ccompiler — CCompiler 基类

该模块为 CCompiler 类提供抽象基类。 CCompiler 实例可用于构建单个项目所需的所有编译和链接步骤。 提供了为编译器设置选项的方法——宏定义、包括目录、链接路径、库等。

该模块提供以下功能。

distutils.ccompiler.gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)

生成用于搜索库目录和链接特定库的链接器选项。 libraries 和 library_dirs 分别是库名（不是文件名！）和搜索目录的列表。 返回适用于某些编译器的命令行选项列表（取决于传入的两个格式字符串）。

distutils.ccompiler.gen_preprocess_options(macros, include_dirs)

生成至少两种编译器使用的 C 预处理器选项（-D、-U、-I）：典型的 Unix 编译器和 Visual C++。 macros 是常见的东西，一个 1 元组或 2 元组的列表，其中 (name,) 表示未定义 (-U) 宏 name，和 [ X130X] 表示定义 (-D) 宏 name 到 value。 include_dirs 只是要添加到头文件搜索路径（-I）的目录名称列表。 返回适用于 Unix 编译器或 Visual C++ 的命令行选项列表。

distutils.ccompiler.get_default_compiler(osname, platform)

确定用于给定平台的默认编译器。

osname 应该是标准的 Python 操作系统名称之一（即 os.name) 和 platform 返回的值是 sys.platform 为相关平台返回的公共值。

如果未给出参数，则默认值为 os.name 和 sys.platform。

distutils.ccompiler.new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)

为提供的平台/编译器组合生成某个 CCompiler 子类的实例的工厂函数。 plat 默认为 os.name（例如 'posix'、'nt') 和 compiler 默认为该平台的默认编译器。 目前仅支持 'posix' 和 'nt'，默认编译器为“传统 Unix 接口”（UnixCCompiler 类）和 Visual C++（MSVCCompiler 类）。 请注意，完全有可能在 Windows 下要求 Unix 编译器对象，在 Unix 下要求 Microsoft 编译器对象——如果您为 compiler 提供值，则忽略 plat。

distutils.ccompiler.show_compilers()

打印可用编译器列表（由 build、build_ext、build_clib 的 --help-compiler 选项使用）。

class distutils.ccompiler.CCompiler([verbose=0, dry_run=0, force=0])

抽象基类 CCompiler 定义了必须由真实编译器类实现的接口。 该类还有一些被多个编译器类使用的实用方法。

编译器抽象类背后的基本思想是每个实例都可以用于构建单个项目的所有编译/链接步骤。 因此，所有这些编译和链接步骤的共同属性——包括目录、要定义的宏、要链接的库等。 — 是编译器实例的属性。 为了考虑如何处理单个文件的可变性，大多数这些属性可能会在每个编译或每个链接的基础上发生变化。

每个子类的构造函数都会创建一个 Compiler 对象的实例。 标志是 verbose（显示详细输出）、dry_run（不实际执行这些步骤）和 force（重建一切，不考虑依赖关系）。 所有这些标志默认为 0（关闭）。 请注意，您可能不想直接实例化 CCompiler 或其子类之一 - 请改用 distutils.CCompiler.new_compiler() 工厂函数。

以下方法允许您手动更改 Compiler 类实例的编译器选项。

add_include_dir(dir)

将 dir 添加到将搜索头文件的目录列表中。 编译器被指示按照对 add_include_dir() 的连续调用提供的顺序搜索目录。

set_include_dirs(dirs)

将要搜索的目录列表设置为 dirs（字符串列表）。 覆盖之前对 add_include_dir() 的任何调用； 随后对 add_include_dir() 的调用添加到传递给 set_include_dirs() 的列表中。 这不会影响编译器默认搜索的任何标准包含目录列表。

add_library(libname)

将 libname 添加到将包含在此编译器对象驱动的所有链接中的库列表中。 请注意，libname 不应*是包含库的文件的名称，而是库本身的名称：实际文件名将由链接器、编译器或编译器类（取决于在平台上）。

将指示链接器按照提供给 add_library() 和/或 set_libraries() 的顺序链接库。 重复库名是完全有效的； 链接器将被指示多次链接库。

set_libraries(libnames)

将要包含在此编译器对象驱动的所有链接中的库列表设置为 libnames（字符串列表）。 这不会影响链接器默认可能包含的任何标准系统库。

add_library_dir(dir)

将 dir 添加到将搜索指定给 add_library() 和 set_libraries() 的库的目录列表。 将指示链接器按照提供给 add_library_dir() 和/或 set_library_dirs() 的顺序搜索库。

set_library_dirs(dirs)

将库搜索目录列表设置为 dirs（字符串列表）。 这不会影响链接器默认搜索的任何标准库搜索路径。

add_runtime_library_dir(dir)

将 dir 添加到将在运行时搜索共享库的目录列表。

set_runtime_library_dirs(dirs)

将在运行时搜索共享库的目录列表设置为 dirs（字符串列表）。 这不会影响运行时链接程序默认搜索的任何标准搜索路径。

define_macro(name[, value=None])

为由该编译器对象驱动的所有编译定义一个预处理器宏。 可选参数 value 应该是一个字符串； 如果未提供，则宏将在没有显式值的情况下定义，确切的结果取决于所使用的编译器。

undefine_macro(name)

为由该编译器对象驱动的所有编译取消定义预处理器宏。 如果相同的宏由 define_macro() 定义而由 undefine_macro() 未定义，则最后一个调用优先（包括多次重定义或未定义）。 如果在每次编译的基础上重新定义/未定义宏（即。 在对 compile()) 的调用中，则优先。

add_link_object(object)

将 object 添加到要包含在此编译器对象驱动的每个链接中的目标文件（或类似物，例如显式命名的库文件或“资源编译器”的输出）列表中。

set_link_objects(objects)

将目标文件（或类似物）列表设置为包含在每个指向 objects 的链接中。 这不会影响链接器默认可能包含的任何标准目标文件（例如系统库）。

以下方法实现了自动检测编译器选项的方法，提供了一些类似于 GNU autoconf 的功能。

detect_language(sources)

检测给定文件或文件列表的语言。 使用实例属性 language_map（字典）和 language_order（列表）来完成这项工作。

find_library_file(dirs, lib[, debug=0])

在指定的目录列表中搜索静态或共享库文件 lib 并返回该文件的完整路径。 如果 debug 为 true，请查找调试版本（如果这在当前平台上有意义）。 如果在任何指定目录中未找到 lib，则返回 None。

has_function(funcname[, includes=None, include_dirs=None, libraries=None, library_dirs=None])

返回一个布尔值，指示当前平台是否支持 [X36X]funcname。 可选参数可用于通过提供额外的包含文件和路径以及库和路径来增强编译环境。

library_dir_option(dir)

返回编译器选项以将 dir 添加到搜索库的目录列表中。

library_option(lib)

返回编译器选项以将 lib 添加到链接到共享库或可执行文件的库列表中。

runtime_library_dir_option(dir)

返回编译器选项以将 dir 添加到搜索运行时库的目录列表中。

set_executables(**args)

定义将运行以执行编译的各个阶段的可执行文件（及其选项）。 可以在此处指定的确切可执行文件集取决于编译器类（通过 'executables' 类属性），但大多数将具有：

属性	描述
编译器	C/C++ 编译器
链接器_so	用于创建共享对象和库的链接器
链接器_exe	用于创建二进制可执行文件的链接器
档案员	静态库创建者

在带有命令行的平台（Unix、DOS/Windows）上，每一个都是一个字符串，将被拆分为可执行名称和（可选）参数列表。 （拆分字符串的方式与 Unix shell 的操作方式类似：单词由空格分隔，但引号和反斜杠可以覆盖这一点。 参见 distutils.util.split_quoted()。）

以下方法调用构建过程中的阶段。

compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])

编译一个或多个源文件。 生成目标文件（例如 将 .c 文件转换为 .o 文件。）

sources 必须是文件名列表，最有可能是 C/C++ 文件，但实际上任何可以由特定编译器和编译器类（例如 MSVCCompiler 可以处理 sources 中的资源文件）。 返回一个目标文件名列表，sources 中的每个源文件名一个。 根据实现，不一定要编译所有源文件，但会返回所有相应的目标文件名。

如果给出 output_dir，则目标文件将放在其下，同时保留其原始路径组件。 也就是说，foo/bar.c 通常编译为 foo/bar.o（对于 Unix 实现）； 如果 output_dir 是 build，那么它会编译为 build/foo/bar.o。

macros，如果给定，必须是一个宏定义列表。 宏定义是 (name, value) 2 元组或 (name,) 1 元组。 前者定义了一个宏； 如果值为 None，则宏定义为没有显式值。 1 元组情况取消定义宏。 较晚的定义/重新定义/未定义优先。

include_dirs，如果给定，必须是一个字符串列表，这些目录仅添加到此编译的默认包含文件搜索路径中。

debug 是一个布尔值； 如果为真，编译器将被指示在目标文件中（或旁边）输出调试符号。

extra_preargs 和 extra_postargs 依赖于实现。 在具有命令行概念的平台上（例如 Unix、DOS/Windows），它们很可能是字符串列表：额外的命令行参数，用于在编译器命令行中添加/附加。 在其他平台上，请查阅实现类文档。 在任何情况下，当抽象编译器框架不切芥末时，它们都旨在作为逃生舱口。

depends 如果给定，则是所有目标所依赖的文件名列表。 如果源文件比depends 中的任何文件都旧，则将重新编译源文件。 这支持依赖性跟踪，但仅限于粗粒度。

失败时升高 CompileError。

create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])

将一堆东西链接在一起以创建一个静态库文件。 “一堆东西”包括作为 objects 提供的目标文件列表，提供给 add_link_object() 和/或 set_link_objects() 的额外目标文件，提供给 add_library() 和/或 set_libraries() 的库，以及作为 库 提供的库（如果有）。

output_libname 应该是库名，而不是文件名； 文件名将从库名中推断出来。 output_dir 是存放库文件的目录。

debug 是一个布尔值； 如果为 true，调试信息将包含在库中（请注意，在大多数平台上，重要的是编译步骤：此处包含 debug 标志只是为了保持一致性）。

target_lang 是编译给定对象的目标语言。 这允许对某些语言进行特定的链接时间处理。

失败时升高 LibError。

link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

将一堆东西链接在一起以创建可执行文件或共享库文件。

“一堆东西”由作为 objects 提供的目标文件列表组成。 output_filename 应该是一个文件名。 如果提供 output_dir，则 output_filename 是相对于它的（即 output_filename 可以根据需要提供目录组件）。

libraries 是要链接的库列表。 这些是库名，而不是文件名，因为它们以特定于平台的方式（例如 foo 在 Unix 上变成 libfoo.a，在 DOS/Windows 上变成 foo.lib）。 但是，它们可以包含目录组件，这意味着链接器将在该特定目录中查找，而不是搜索所有正常位置。

library_dirs，如果提供，应该是一个目录列表，用于搜索指定为裸库名称的库（即。 没有目录组件）。 这些位于系统默认值之上，并提供给 add_library_dir() 和/或 set_library_dirs()。 runtime_library_dirs 是一个目录列表，这些目录将嵌入到共享库中，用于搜索 *it* 在运行时依赖的其他共享库。 （这可能只与 Unix 相关。）

export_symbols 是共享库将导出的符号列表。 （这似乎只与 Windows 相关。）

debug 与 compile() 和 create_static_lib() 一样，略有不同，它在大多数平台上实际上很重要（与 create_static_lib( 相反） )，其中包括一个 debug 标志，主要是为了形式）。

extra_preargs 和 extra_postargs 与 compile() 相同（当然，它们为正在使用的特定链接器提供命令行参数除外）。

target_lang 是编译给定对象的目标语言。 这允许对某些语言进行特定的链接时间处理。

失败时升高 LinkError。

link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])

链接一个可执行文件。 output_progname 是可执行文件的名称，而 objects 是要链接的目标文件名列表。 其他参数与 link() 方法相同。

link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

链接共享库。 output_libname 是输出库的名称，而 objects 是要链接的对象文件名列表。 其他参数与 link() 方法相同。

link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

链接共享对象。 output_filename 是将要创建的共享对象的名称，而 objects 是要链接的对象文件名列表。 其他参数与 link() 方法相同。

preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])

预处理单个 C/C++ 源文件，命名为 source。 如果未提供 output_file，则输出将写入名为 output_file 或 stdout 的文件。 macros 是与 compile() 一样的宏定义列表，它将扩充用 define_macro() 和 undefine_macro() 设置的宏]。 include_dirs 是将添加到默认列表中的目录名称列表，与 add_include_dir() 相同。

失败时升高 PreprocessError。

以下实用方法由 CCompiler 类定义，供各种具体子类使用。

executable_filename(basename[, strip_dir=0, output_dir=])

返回给定 basename 的可执行文件的文件名。 通常对于非 Windows 平台，这与基本名称相同，而 Windows 将添加 .exe。

library_filename(libname[, lib_type='static', strip_dir=0, output_dir=])

返回当前平台上给定库名称的文件名。 在 Unix 上，具有 'static' 的 lib_type 的库通常采用 liblibname.a 的形式，而 'dynamic' 的 lib_type 将是形式为 liblibname.so。

object_filenames(source_filenames[, strip_dir=0, output_dir=])

返回给定源文件的目标文件的名称。 source_filenames 应该是文件名列表。

shared_object_filename(basename[, strip_dir=0, output_dir=])

返回给定文件名 basename 的共享对象文件的名称。

execute(func, args[, msg=None, level=1])

调用 distutils.util.execute()。 此方法在记录并考虑 dry_run 标志后，使用给定的参数 args 调用 Python 函数 func。

spawn(cmd)

调用 distutils.util.spawn()。 这会调用一个外部进程来运行给定的命令。

mkpath(name[, mode=511])

调用 distutils.dir_util.mkpath()。 这将创建一个目录和任何丢失的祖先目录。

move_file(src, dst)

调用 distutils.file_util.move_file()。 将 src 重命名为 dst。

announce(msg[, level=1])

使用 distutils.log.debug() 写一条消息。

warn(msg)

将警告消息 msg 写入标准错误。

debug_print(msg)

如果在 CCompiler 实例上设置了 debug 标志，则将 msg 打印到标准输出，否则什么都不做。

9.3. distutils.unixccompiler — Unix C 编译器

该模块提供了 UnixCCompiler 类，它是 CCompiler 的子类，用于处理典型的 Unix 风格的命令行 C 编译器：

• 用 -Dname[=value] 定义的宏
• 用 -Uname 未定义的宏
• 包括用 -Idir 指定的搜索目录
• 用 -llib 指定的库
• 用 -Ldir 指定的库搜索目录
• 编译由 cc（或类似）可执行文件处理，并带有 -c 选项：将 .c 编译为 .o
• 链接由 ar 命令处理的静态库（可能与 ranlib）
• 链接共享库由 cc -shared 处理

9.4. distutils.msvc 编译器 — 微软编译器

此模块提供 MSVCCompiler，这是 Microsoft Visual Studio 抽象 CCompiler 类的实现。 通常，扩展模块需要使用与编译 Python 相同的编译器进行编译。 对于 Python 2.3 及更早版本，编译器是 Visual Studio 6。 对于 Python 2.4 和 2.5，编译器是 Visual Studio .NET 2003。

MSVCCompiler 通常会选择正确的编译器、链接器等。 在其自己的。 要覆盖此选择，必须同时设置环境变量 DISTUTILS_USE_SDK 和 MSSdk。 MSSdk表示当前环境已经被SDK的SetEnv.Cmd脚本设置好，或者安装SDK时已经注册了环境变量； DISTUTILS_USE_SDK 表示 distutils 用户已明确选择通过 MSVCCompiler 覆盖编译器选择。

9.5. distutils.bcpp编译器 — Borland 编译器

该模块提供 BorlandCCompiler，这是 Borland C++ 编译器抽象 CCompiler 类的子类。

9.6. distutils.cygwincompiler— Cygwin 编译器

该模块提供了 CygwinCCompiler 类，它是 UnixCCompiler 的子类，用于处理 GNU C 编译器到 Windows 的 Cygwin 端口。 它还包含处理 GCC 的 mingw32 端口的 Mingw32CCompiler 类（与 no-cygwin 模式下的 cygwin 相同）。

9.7. distutils.archive_util — 归档实用程序

该模块提供了一些用于创建存档文件的功能，例如 tarball 或 zipfiles。

distutils.archive_util.make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])

创建一个存档文件（例如。 zip 或 tar）。 base_name 是要创建的文件的名称，减去任何特定于格式的扩展名； format 是存档格式：zip、tar、gztar、bztar、xztar之一，或ztar。 root_dir 是一个目录，它将成为存档的根目录； IE。 我们通常在创建存档之前 chdir 进入 root_dir。 base_dir 是我们开始归档的目录； IE。 base_dir 将是存档中所有文件和目录的公共前缀。 root_dir 和 base_dir 都默认为当前目录。 返回存档文件的名称。

3.5 版更改： 增加了对 xztar 格式的支持。

distutils.archive_util.make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])

'从 base_dir 中和下的所有文件创建一个（可选压缩）存档作为 tar 文件。 compress 必须是 'gzip'（默认值）、'bzip2'、'xz'、'compress' 或 None。 对于 'compress' 方法，由 compress 命名的压缩实用程序必须位于默认程序搜索路径上，因此这可能是特定于 Unix 的。 输出 tar 文件将命名为 base_dir.tar，可能加上适当的压缩扩展名（.gz、.bz2、.xz 或 .Z）。 返回输出文件名。

3.5 版更改： 增加了对 xz 压缩的支持。

distutils.archive_util.make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])

从 base_dir 中和下的所有文件创建一个 zip 文件。 输出 zip 文件将命名为 base_name + .zip。 使用 zipfile Python 模块（如果可用）或 InfoZIP zip 实用程序（如果已安装并在默认搜索路径中找到）。 如果两个工具都不可用，则升高 DistutilsExecError。 返回输出 zip 文件的名称。

9.8. distutils.dep_util — 依赖检查

该模块提供了执行简单的、基于时间戳的文件和文件组依赖的函数； 此外，功能完全基于这种时间戳依赖性分析。

distutils.dep_util.newer(source, target)

如果 source 存在并且比 target 修改得更近，或者如果 source 存在而 target 不存在，则返回 true。 如果两者都存在并且 target 与 source 年龄相同或更新，则返回 false。 如果 source 不存在，则提高 DistutilsFileError。

distutils.dep_util.newer_pairwise(sources, targets)

并行遍历两个文件名列表，测试每个源是否比其对应的目标新。 根据 newer() 的语义，返回一对列表 (sources, targets)，其中 source 比 target 新。

distutils.dep_util.newer_group(sources, target[, missing='error'])

如果 target 对于 sources 中列出的任何文件已过时，则返回 true。 换句话说，如果 target 存在并且比 sources 中的每个文件都新，则返回 false； 否则返回真。 missing 控制我们在源文件丢失时的处理方式； 默认 ('error') 是从 os.stat() 内部用 OSError 炸毁； 如果是 'ignore'，我们会默默地删除任何丢失的源文件； 如果是 'newer'，任何丢失的源文件都会让我们假设 target 已经过时（这在“试运行”模式下很方便：它会让你假装执行由于缺少输入而不起作用的命令，但这并不重要，因为您实际上并不打算运行这些命令）。

9.9. distutils.dir_util — 目录树操作

该模块提供对目录和目录树进行操作的功能。

distutils.dir_util.mkpath(name[, mode=0o777, verbose=0, dry_run=0])

创建一个目录和任何缺少的祖先目录。 如果目录已经存在（或者如果 name 是空字符串，表示当前目录，当然存在），那么什么都不做。 如果在此过程中无法创建某个目录（例如。 某些子路径存在，但它是一个文件而不是目录）。 如果 verbose 为真，则将每个 mkdir 的一行摘要打印到 stdout。 返回实际创建的目录列表。

distutils.dir_util.create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])

在 base_dir 下创建所有需要放置 文件 的空目录。 base_dir 只是一个目录的名称，它不一定存在； files 是相对于 base_dir 解释的文件名列表。 base_dir + files 中每个文件的目录部分，如果它不存在，将被创建。 mode、verbose 和 dry_run 标志与 mkpath() 相同。

distutils.dir_util.copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])

将整个目录树 src 复制到新位置 dst。 src 和 dst 都必须是目录名。 如果 src 不是目录，则引发 DistutilsFileError。 如果 dst 不存在，则使用 mkpath() 创建。 复制的最终结果是将src中的每个文件都复制到dst中，将src下的目录递归复制到dst . 使用其输出名称返回已复制或可能已复制的文件列表。 返回值不受 update 或 dry_run 的影响：它只是 src 下所有文件的列表，名称更改为 dst 下。

preserve_mode 和 preserve_times 与 distutils.file_util.copy_file() 相同； 请注意，它们仅适用于常规文件，不适用于目录。 如果 preserve_symlinks 为真，符号链接将被复制为符号链接（在支持它们的平台上！）； 否则（默认），符号链接的目的地将被复制。 update 和 verbose 与 copy_file() 相同。

src 中以 .nfs 开头的文件将被跳过（有关这些文件的更多信息可在 NFS 常见问题页面 的答案 D2 中找到）。

3.3.1 版更改：NFS 文件被忽略。

distutils.dir_util.remove_tree(directory[, verbose=0, dry_run=0])

递归删除 directory 及其下的所有文件和目录。 任何错误都将被忽略（如果 verbose 为真，则会向 sys.stdout 报告）。

9.10. distutils.file_util — 单文件操作

该模块包含一些用于操作单个文件的实用函数。

distutils.file_util.copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])

将文件 src 复制到 dst。 如果 dst 是目录，则将 src 复制到那里并使用相同的名称； 否则，它必须是文件名。 （如果文件存在，它将被无情地破坏。）如果 preserve_mode 为真（默认值），则文件的模式（类型和权限位，或当前平台上的类似内容）被复制。 如果 preserve_times 为真（默认），最后修改时间和最后访问时间也会被复制。 如果 update 为真，则 src 仅在 dst 不存在，或者 dst 确实存在但早于 [ X141X]src。

link 允许您制作硬链接（使用 os.link()）或符号链接（使用 os.symlink()）而不是复制：设置它至 'hard' 或 'sym'； 如果是None（默认），文件被复制。 不要在不支持它的系统上设置 link：copy_file() 不检查硬链接或符号链接是否可用。 它使用 _copy_file_contents() 来复制文件内容。

返回一个元组 (dest_name, copied)：dest_name 是输出文件的实际名称，如果文件被复制（或者本来会被复制，如果 [ X168X]dry_run 真）。

distutils.file_util.move_file(src, dst[, verbose, dry_run])

将文件 src 移动到 dst。 如果 dst 是目录，则文件将移入同名目录中； 否则，src 只是重命名为 dst。 返回文件的新全名。

警告

使用 copy_file() 处理 Unix 上的跨设备移动。 其他系统呢？

distutils.file_util.write_file(filename, contents)

创建一个名为 filename 的文件并将 contents（不带行终止符的字符串序列）写入其中。

9.11. distutils.util — 其他实用功能

该模块包含不适合任何其他实用程序模块的其他各种零碎。

distutils.util.get_platform()

返回标识当前平台的字符串。 这主要用于区分特定于平台的构建目录和特定于平台的构建发行版。 通常包括操作系统名称和版本以及体系结构（由“os.uname()”提供），尽管包含的确切信息取决于操作系统； 例如，在 Linux 上，内核版本并不是特别重要。

返回值示例：

• linux-i586

• linux-alpha

• solaris-2.6-sun4u

对于非 POSIX 平台，目前只返回 sys.platform。

对于 macOS 系统，操作系统版本反映的是运行二进制文件的最低版本（即 Python 构建期间 MACOSX_DEPLOYMENT_TARGET 的值），而不是当前系统的操作系统版本。

对于在 macOS 上构建的通用二进制文件，架构值反映的是通用二进制文件状态，而不是当前处理器的架构。 对于 32 位通用二进制文件，架构是 fat，对于 64 位通用二进制文件，架构是 fat64，对于 4 路通用二进制文件，架构是 universal。 从 Python 2.7 和 Python 3.2 开始，架构 fat3 用于 3 路通用构建（ppc、i386、x86_64），而 intel 用于 i386 和 x86_64 架构的通用构建

macOS 上的返回值示例：

• macosx-10.3-ppc

• macosx-10.3-fat

• macosx-10.5-universal

• macosx-10.6-intel

对于 AIX，Python 3.9 及更高版本返回一个以“aix”开头的字符串，后跟其他字段（由 '-' 分隔）表示 AIX 版本、发布和技术级别（第一个字段）、构建日期的组合值（第二个字段）和位大小（第三个字段）。 Python 3.8 及更早版本仅返回一个带有 AIX 版本和发行版的附加字段。

AIX 上的返回值示例：

• aix-5307-0747-32 # AIX 上的 32 位构建 oslevel -s: 5300-07-00-0000

• aix-7105-1731-64 # AIX 上的 64 位构建 oslevel -s: 7100-05-01-1731

• aix-7.2 # Python 3.8 及更早版本报告的遗留表单

3.9 版更改： AIX 平台字符串格式现在还包括技术级别、构建日期和 ABI 位大小。

distutils.util.convert_path(pathname)

返回 'pathname' 作为将在本机文件系统上工作的名称，即 将其拆分为“/”并使用当前目录分隔符将其重新组合在一起。 需要，因为安装脚本中的文件名总是以 Unix 样式提供，并且必须先转换为本地约定，然后才能在文件系统中实际使用它们。 如果 pathname 以斜杠开头或结尾，则在非 Unix-ish 系统上引发 ValueError。

distutils.util.change_root(new_root, pathname)

返回 路径名 和 new_root 前缀。 如果 pathname 是相对的，这相当于 os.path.join(new_root,pathname) 否则，它需要使 pathname 相对，然后将两者连接起来，这在 DOS/Windows 上很棘手。

distutils.util.check_environ()

确保“os.environ”具有我们保证用户可以在配置文件、命令行选项等中使用的所有环境变量。 目前这包括：

• HOME - 用户的主目录（仅限 Unix）
• PLAT - 当前平台的描述，包括硬件和操作系统（见 get_platform()）

distutils.util.subst_vars(s, local_vars)

对 s 执行 shell/Perl 样式的变量替换。 每次出现 $ 后跟一个名称都被认为是一个变量，并且变量被替换为在 local_vars 字典中找到的值，或者在 os.environ 中，如果它不在 [ X192X]local_vars。 os.environ 首先被检查/增强以保证它包含某些值：参见 check_environ()。 对于在 local_vars 或 os.environ 中找不到的任何变量，提高 ValueError。

请注意，这不是一个成熟的字符串插值函数。 有效的 $variable 只能由大小写字母、数字和下划线组成。 没有 { } 或 ( ) 样式引用可用。

distutils.util.split_quoted(s)

根据用于引号和反斜杠的类 Unix shell 规则拆分字符串。 简而言之：单词由空格分隔，只要这些空格没有被反斜杠或引号内的字符串转义。 单引号和双引号是等价的，引号字符可以用反斜杠转义。 反斜杠从任何两个字符的转义序列中删除，只留下转义字符。 引号字符从任何带引号的字符串中删除。 返回单词列表。

distutils.util.execute(func, args[, msg=None, verbose=0, dry_run=0])

执行一些影响外部世界的操作（例如，写入文件系统）。 此类操作很特殊，因为它们被 dry_run 标志禁用。 这种方法为您解决了所有官僚主义问题； 您所要做的就是提供要调用的函数和它的参数元组（以体现正在执行的“外部操作”），以及要打印的可选消息。

distutils.util.strtobool(val)

将真值的字符串表示形式转换为真 (1) 或假 (0)。

真值为 y、yes、t、true、on 和 1； 假值为 n、no、f、false、off 和 0。 如果 val 是其他任何东西，则引发 ValueError。

distutils.util.byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])

将 Python 源文件集合字节编译为 __pycache__ 子目录中的 .pyc 文件（参见 PEP 3147 和 [ X141X]PEP 488）。 py_files 是要编译的文件列表； 任何不以 .py 结尾的文件都会被悄悄跳过。 optimize 必须是以下之一：

• 0 - 不优化

• 1 - 正常优化（如 python -O）

• 2 - 额外优化（如 python -OO）

如果 force 为真，则无论时间戳如何，都会重新编译所有文件。

每个 bytecode 文件中编码的源文件名默认为 py_files 中列出的文件名； 您可以使用 prefix 和 basedir 修改这些。 prefix 是一个将从每个源文件名中剥离的字符串，base_dir 是一个将被添加的目录名（在 prefix 被剥离之后）。 您可以根据需要提供 prefix 和 base_dir 中的一个或两个（或两者都不提供）。

如果 dry_run 为真，则实际上不会做任何会影响文件系统的事情。

字节编译要么直接在这个解释器进程中使用标准的 py_compile 模块完成，要么通过编写一个临时脚本并执行它来间接完成。 通常，您应该让 byte_compile() 弄清楚是否使用直接编译（详细信息请参阅源代码）。 direct 标志被间接模式生成的脚本使用； 除非您知道自己在做什么，否则将其设置为 None。

在 3.2.3 版更改：在 __pycache__ 子目录中创建名称中带有 import 魔术标签 的 .pyc 文件，而不是没有标签的文件在当前目录中。

3.5 版更改： 根据 PEP 488 创建 .pyc 文件。

distutils.util.rfc822_escape(header)

通过确保每个换行符后有 8 个空格，返回转义的 header 版本以包含在 RFC 822 标头中。 请注意，它不会对字符串进行其他修改。

9.12. distutils.dist — 分发类

该模块提供了 Distribution 类，它代表正在构建/安装/分发的模块分发。

9.13. distutils.extension — 扩展类

该模块提供了 Extension 类，用于描述安装脚本中的 C/C++ 扩展模块。

9.14. distutils.debug — Distutils 调试模式

该模块提供了 DEBUG 标志。

9.15. distutils.errors — Distutils 异常

提供 Distutils 模块使用的异常。 请注意，Distutils 模块可能会引发标准异常； 特别是， SystemExit 通常是针对明显是最终用户的错误（例如。 错误的命令行参数）。

该模块在from ... import *模式下可以安全使用； 它只导出名称以 Distutils 开头并以 Error 结尾的符号。

9.16. distutils.fancy_getopt — 标准 getopt 模块的包装

该模块为标准 getopt 模块提供了一个包装器，该模块提供了以下附加功能：

• 短期和长期期权捆绑在一起
• 选项有帮助字符串，所以 fancy_getopt() 可能会创建一个完整的使用摘要
• 选项设置传入对象的属性
• 布尔选项可以有“负别名”——例如。 如果 --quiet 是 --verbose 的“否定别名”，则命令行中的 --quiet 将 verbose 设置为 false。

distutils.fancy_getopt.fancy_getopt(options, negative_opt, object, args)

包装功能。 options 是 (long_option, short_option, help_string) 三元组的列表，如 FancyGetopt 的构造函数中所述。 negative_opt 应该是一个将选项名称映射到选项名称的字典，键和值都应该在 options 列表中。 object 是一个将用于存储值的对象（参见 FancyGetopt 类的 getopt() 方法）。 args 是参数列表。 如果将 None 作为 args 传递，则将使用 sys.argv[1:]。

distutils.fancy_getopt.wrap_text(text, width)

将 text 包裹到小于 width 的宽度。

class distutils.fancy_getopt.FancyGetopt([option_table=None])

option_table 是一个三元组列表：(long_option, short_option, help_string)

如果一个选项接受一个参数，它的 long_option 应该附加 '='； short_option 应该只是一个字符，无论如何都不能 ':'。 short_option 应该是 None 如果 long_option 没有对应的 short_option。 所有选项元组都必须有长选项。

FancyGetopt 类提供以下方法：

FancyGetopt.getopt([args=None, object=None])

解析 args 中的命令行选项。 在 对象 上存储为属性。

如果 args 是 None 或未提供，则使用 sys.argv[1:]。 如果 object 是 None 或未提供，则创建一个新的 OptionDummy 实例，在那里存储选项值，并返回一个元组 (args, object)。 如果提供了 object，它会被修改，而 getopt() 只返回 args； 在这两种情况下，返回的 args 是传入的 args 列表的修改副本，它保持不变。

FancyGetopt.get_option_order()

返回由 getopt() 上次运行处理的 (option, value) 元组列表 如果 getopt() 尚未被调用，则引发 RuntimeError .

FancyGetopt.generate_help([header=None])

从此 FancyGetopt 对象的选项表生成帮助文本（字符串列表，每个建议的输出行一个）。

如果提供，在帮助顶部打印提供的 header。

9.17. distutils.filelist — FileList 类

该模块提供了 FileList 类，用于查看文件系统和构建文件列表。

9.19. distutils.spawn — 产生一个子进程

该模块提供了 spawn() 函数，它是各种平台特定函数的前端，用于在子进程中启动另一个程序。 还提供 find_executable() 来搜索给定可执行文件名称的路径。

9.20. distutils.sysconfig — 系统配置信息

distutils.sysconfig 模块提供对 Python 的低级配置信息的访问。 可用的特定配置变量在很大程度上取决于平台和配置。 具体变量取决于正在运行的特定 Python 版本的构建过程； 变量是在 Makefile 和在 Unix 系统上与 Python 一起安装的配置头文件中找到的变量。 从 2.2 开始的 Python 版本的配置头称为 pyconfig.h，早期版本的 Python 称为 config.h。

提供了一些附加功能，这些功能对 distutils 包的其他部分执行一些有用的操作。

distutils.sysconfig.PREFIX

os.path.normpath(sys.prefix) 的结果。

distutils.sysconfig.EXEC_PREFIX

os.path.normpath(sys.exec_prefix) 的结果。

distutils.sysconfig.get_config_var(name)

返回单个变量的值。 这相当于 get_config_vars().get(name)。

distutils.sysconfig.get_config_vars(...)

返回一组变量定义。 如果没有参数，则返回将配置变量的名称映射到值的字典。 如果提供了参数，它们应该是字符串，返回值将是一个给出关联值的序列。 如果给定的名称没有相应的值，则该变量将包含 None。

distutils.sysconfig.get_config_h_filename()

返回配置头的完整路径名。 对于 Unix，这将是由 configure 脚本生成的标头； 对于其他平台，头文件将由 Python 源代码分发直接提供。 该文件是特定于平台的文本文件。

distutils.sysconfig.get_makefile_filename()

返回用于构建 Python 的 Makefile 的完整路径名。 对于 Unix，这将是由 configure 脚本生成的文件； 其他平台的含义会有所不同。 该文件是特定于平台的文本文件（如果存在）。 此函数仅在 POSIX 平台上有用。

distutils.sysconfig.get_python_inc([plat_specific[, prefix]])

返回通用或平台相关的 C 包含文件的目录。 如果 plat_specific 为真，则返回平台相关的包含目录； 如果为 false 或省略，则返回与平台无关的目录。 如果给出了 prefix，它被用作前缀而不是 PREFIX，或者作为执行前缀而不是 EXEC_PREFIX 如果 plat_specific ] 是真的。

distutils.sysconfig.get_python_lib([plat_specific[, standard_lib[, prefix]]])

返回常规或平台相关库安装的目录。 如果 plat_specific 为真，则返回平台相关的包含目录； 如果为 false 或省略，则返回与平台无关的目录。 如果给出了 prefix，它被用作前缀而不是 PREFIX，或者作为执行前缀而不是 EXEC_PREFIX 如果 plat_specific ] 是真的。 如果 standard_lib 为 true，则返回标准库的目录，而不是第三方扩展的安装目录。

以下函数仅用于 distutils 包中。

distutils.sysconfig.customize_compiler(compiler)

对 distutils.ccompiler.CCompiler 实例进行任何特定于平台的自定义。

该函数目前仅在 Unix 上需要，但应始终调用以支持向前兼容。 它插入不同 Unix 风格的信息，并存储在 Python 的 Makefile 中。 此信息包括选定的编译器、编译器和链接器选项，以及链接器用于共享对象的扩展。

这个函数更加特殊，只能在 Python 自己的构建过程中使用。

distutils.sysconfig.set_python_build()

通知 distutils.sysconfig 模块它被用作 Python 构建过程的一部分。 这会更改文件的许多相对位置，允许它们位于构建区域而不是已安装的 Python 中。

9.21. distutils.text_file — TextFile 类

该模块提供了 TextFile 类，它为文本文件提供了一个接口（可选）负责剥离注释、忽略空行和用反斜杠连接行。

class distutils.text_file.TextFile([filename=None, file=None, **options])

此类提供了一个类似文件的对象，它负责处理您在处理具有某些逐行语法的文本文件时通常想做的所有事情：条带注释（只要 # 是您的注释）字符），跳过空行，通过转义换行符来连接相邻行（即 行尾的反斜杠），去除前导和/或尾随空格。 所有这些都是可选的并且可以独立控制。

该类提供了 warn() 方法，因此您可以生成报告物理行号的警告消息，即使有问题的逻辑行跨越多个物理行。 还提供 unreadline() 用于实现一次一行的前瞻。

TextFile 实例是使用 filename、file 或两者创建的。 如果两者都是 None，则会引发 RuntimeError。 filename 应该是一个字符串，而 file 是一个文件对象（或提供 readline() 和 close() 方法的东西）。 建议您至少提供 filename，以便 TextFile 可以将其包含在警告消息中。 如果未提供 file，则 TextFile 使用 open() 内置函数创建自己的文件。

选项都是布尔值，并影响 readline() 返回的值

选项名称	描述	默认
条评论	从 '#' 到行尾，以及通向 '#' 的任何空格 - 除非它被反斜杠转义	真的
lstrip_ws	在返回之前去除每一行的前导空格	错误的
rstrip_ws	在返回之前去除每一行的尾随空格（包括行终止符！）。	真的
跳过空白	跳过空行 * 在 * 剥离注释和空格之后。 （如果 lstrip_ws 和 rstrip_ws 都为假，那么某些行可能只包含空格：即使 skip_blanks 为真，也不会*跳过这些行。）	真的
join_lines	如果反斜杠是去除注释和空格后一行上的最后一个非换行符，则将以下行与其连接以形成一个逻辑行； 如果连续 N 行以反斜杠结尾，则 N+1 物理行将连接形成一个逻辑行。	错误的
折叠连接	从连接到它们的前辈的行中去除前导空格； 仅当 (join_lines and not lstrip_ws) 时才重要	错误的

请注意，由于 rstrip_ws 可以去除尾部换行符，因此 readline() 的语义必须与内置文件对象的 readline() 方法的语义不同！ 特别是，readline() 返回 None 用于文件结尾：空字符串可能只是一个空行（或全空白行），如果 rstrip_ws[ X160X] 是真的，但 skip_blanks 不是。

open(filename)

打开一个新文件 文件名 。 这会覆盖任何 file 或 filename 构造函数参数。

close()

关闭当前文件并忘记我们所知道的一切（包括文件名和当前行号）。

warn(msg[, line=None])

打印（到 stderr）与当前文件中的当前逻辑行相关联的警告消息。 如果文件中的当前逻辑行跨越多个物理行，则警告是指整个范围，例如 "lines 3-5"。 如果提供 line，则覆盖当前行号； 它可以是一个列表或元组来指示物理行的范围，或者是单个物理行的整数。

readline()

从当前文件中读取并返回单个逻辑行（或者从内部缓冲区中读取，如果行之前已使用 unreadline() 进行“未读”）。 如果 join_lines 选项为真，这可能涉及读取多个连接成单个字符串的物理行。 更新当前行号，因此在 readline() 之后调用 warn() 会发出有关刚刚读取的物理行的警告。 在文件末尾返回 None，因为如果 rstrip_ws 为真但 strip_blanks 不是，则可能出现空字符串。

readlines()

读取并返回当前文件中剩余的所有逻辑行的列表。 这会将当前行号更新为文件的最后一行。

unreadline(line)

将 line（一个字符串）推送到一个内部缓冲区，该缓冲区将被未来的 readline() 调用检查。 用于实现一次一行前瞻的解析器。 请注意，使用 unreadline() 读取的“未读”行随后不会在使用 readline() 读取时重新清理（删除空白或其他）。 如果在调用 readline() 之前对 unreadline() 进行了多次调用，则这些行将以最近的第一顺序返回。

9.23. distutils.cmd — Distutils 命令的抽象基类

该模块提供抽象基类 Command。

class distutils.cmd.Command(dist)

用于定义命令类的抽象基类，Distutils 的“工蜂”。 命令类的一个有用类比是将它们视为具有称为 options 的局部变量的子程序。 这些选项在 initialize_options() 中声明并在 finalize_options() 中定义（给定它们的最终值），这两个选项都必须由每个命令类定义。 两者之间的区别是必要的，因为选项值可能来自外部世界（命令行、配置文件等），并且必须在处理这些外部影响之后计算依赖于其他选项的任何选项——因此 finalize_options( )。 子程序的主体是 run() 方法，它根据其选项的值完成所有工作，每个命令类也必须实现该方法。

类构造函数接受一个参数 dist，一个 Distribution 实例。

9.24. 创建一个新的 Distutils 命令

本节概述了创建新 Distutils 命令的步骤。

新命令位于 distutils.command 包中的模块中。 该目录中有一个名为 command_template 的示例模板。 将此文件复制到与您正在实施的新命令同名的新模块中。 这个模块应该实现一个与模块（和命令）同名的类。 因此，例如，要创建命令 peel_banana（以便用户可以运行 setup.py peel_banana），您需要将 command_template 复制到 distutils/command/peel_banana.py，然后对其进行编辑这样它就实现了类 peel_banana，它是 distutils.cmd.Command 的子类。

Command 的子类必须定义以下方法。

Command.initialize_options()

为该命令支持的所有选项设置默认值。 请注意，这些默认值可能会被其他命令、设置脚本、配置文件或命令行覆盖。 因此，这不是编写选项之间依赖关系的地方； 通常，initialize_options() 实现只是一堆 self.foo = None 分配。

Command.finalize_options()

为该命令支持的所有选项设置最终值。 这总是尽可能晚地调用，即。 在从命令行或其他命令完成任何选项分配之后。 因此，这是对选项依赖项进行编码的地方：如果 foo 依赖于 bar，那么从 bar 设置 foo 是安全的只要 foo 仍然具有在 initialize_options() 中分配的相同值。

Command.run()

命令的存在理由：执行它要执行的操作，由 initialize_options() 中初始化的选项控制，由其他命令、安装脚本、命令行和配置文件自定义，并在 finalize_options() 中完成。 所有终端输出和文件系统交互都应该由 run() 完成。

Command.sub_commands

sub_commands 形式化了命令“族”的概念，例如 install 作为带有子命令 install_lib、install_headers 等的父级。 命令族的父级将 sub_commands 定义为类属性； 它是一个 2 元组列表 (command_name, predicate)，其中 command_name 是一个字符串，而 predicate 是一个函数、一个字符串或 None。 predicate是父命令判断对应命令在当前情况下是否适用的方法。 （例如 install_headers 仅适用于我们有任何 C 头文件要安装的情况。）如果 predicate 是 None，则该命令始终适用。

sub_commands 通常定义在类的 end 处，因为谓词可以是类的方法，所以它们必须已经被定义。 规范示例是 install 命令。

9.29. distutils.command.bdist_msi — 构建 Microsoft Installer 二进制包

class distutils.command.bdist_msi.bdist_msi

自 3.9 版起已弃用： 改用 bdist_wheel（轮包）。

构建 Windows Installer (.msi) 二进制包。

在大多数情况下，bdist_msi 安装程序比 bdist_wininst 安装程序是更好的选择，因为它对 Win64 平台提供更好的支持，允许管理员执行非交互式安装，并允许通过组策略安装.

9.31. distutils.command.bdist_wininst — 构建 Windows 安装程序

自 3.8 版起已弃用： 改用 bdist_wheel（轮包）。

9.36. distutils.command.build_py — 构建包的 .py/.pyc 文件

class distutils.command.build_py.build_py

class distutils.command.build_py.build_py_2to3

build_py 的替代实现，它还在将要安装的每个 .py 文件上运行 2to3 转换库。 要在 setup.py 文件中使用它来设计同时运行 Python 2.x 和 3.x 的发行版，请添加：

try:
    from distutils.command.build_py import build_py_2to3 as build_py
except ImportError:
    from distutils.command.build_py import build_py

到您的 setup.py，以及更高版本：

cmdclass = {'build_py': build_py}

到 setup() 的调用。

9.38. distutils.command.clean — 清理包构建区域

此命令删除由 build 及其子命令创建的临时文件，如中间编译的目标文件。 使用 --all 选项，将删除完整的构建目录。

就地 构建的扩展模块 不会被清除，因为它们不在构建目录中。

9.45. distutils.command.register — 使用 Python Package Index 注册模块

register 命令使用 Python 包索引注册包。 这在 PEP 301 中有更详细的描述。

9.46. distutils.command.check — 检查包的元数据

check 命令对包的元数据执行一些测试。 例如，它验证所有必需的元数据都作为传递给 setup() 函数的参数提供。