9. API Reference

9.1. distutils.core —核心 Distutils Function

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

• distutils.core. setup(* arguments *)
  • 基本的万能Function可以完成 Distutils 方法所要求的大部分Function。

设置函数需要大量参数。下表列出了这些内容。

• distutils.core. run_setup(* script_name * [，* script_args = None ， stop_after ='run'*])
  • 在稍微受控制的环境中运行安装脚本，然后返回驱动事物的distutils.dist.Distribution实例。如果您需要找出分发元数据(作为关键字 args 从* script *传递到setup())或配置文件或命令行的内容，这将很有用。

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

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

此外，distutils.core模块还公开了许多其他类别的类。

• Extension来自distutils.extension

• Command来自distutils.cmd

• Distribution来自distutils.dist

以下是对每个方法的简短描述，但请参见相关模块以获取完整参考。

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

在 3.8 版中进行了更改：在 Unix 上，Cextensions 不再链接到 libpython，只有在 Android 和 Cygwin 上。

• 类别 distutils.core. Distribution
  • Distribution描述了如何构建，安装和打包 Python 软件包。

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

在 3.7 版中进行了更改：Distribution现在会警告如果未将classifiers，keywords和platforms字段指定为列表或字符串。

• 类别 distutils.core. Command
  • Command类(或更确切地说是其子类之一的实例)实现单个 distutils 命令。

9.2. distutils.ccompiler — CCompilerBase Class

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

该模块提供以下Function。

• 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 或 2Tuples 的列表，其中(name,)表示未定义(-U)宏 name ，而(name, value)表示将(-D)宏 name 定义为 value *。 * include_dirs *只是要添加到头文件搜索路径(-I)的目录名称的列表。返回适用于 Unix 编译器或 Visual C 的命令行选项列表。

• distutils.ccompiler. get_default_compiler(* osname ， platform *)

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

• osname 应该是标准 Python OS 名称之一(即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 ( )

  • 打印可用编译器的列表(由--help-compiler选项用于 build ， build_ext ， build_clib )。
• • class * distutils.ccompiler. CCompiler([* verbose = 0 ， dry_run = 0 ， force = 0 *])
  • 抽象 Base ClassCCompiler定义了必须由实际编译器类实现的接口。该类还具有一些编译器类使用的一些 Util 方法。

编译器抽象类背后的基本思想是，每个实例可用于构建单个项目的所有编译/链接步骤。因此，所有这些编译和链接步骤的公共属性(包括目录，定义的宏，要链接的库等)是编译器实例的属性。为了允许各个文件的处理方式不同，可以根据每次编译或每个链接来更改大多数这些属性。

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

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

• add_include_dir(* dir *)

  • 将* dir *添加到将搜索头文件的目录列表中。指示编译器pass对add_include_dir()的连续调用按搜索目录的 Sequences 搜索目录。

• set_include_dirs(* dirs *)

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

• add_library(* libname *)

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

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

• set_libraries(* libnames *)

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

• add_library_dir(* dir *)

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

• 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 *的每个链接中。这不会影响链接程序默认情况下可能包括的任何标准对象文件(例如系统库)。

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

• detect_language(来源)

  • 检测给定文件或文件列表的语言。使用实例属性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 *])

  • 返回一个布尔值，指示当前平台是否支持* funcname *。pass提供其他包含文件和路径以及库和路径，可以使用可选参数来扩展编译环境。

• library_dir_option(* dir *)

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

• library_option(* lib *)

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

• runtime_library_dir_option(* dir *)

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

• set_executables(*** args *)

  • 定义将运行以执行各个编译阶段的可执行文件(以及它们的选项)。此处可以指定的确切可执行文件集取决于编译器类(pass'executables'类属性)，但是大多数将具有：

在带有命令行的平台(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) 2Tuples 或(name,) 1Tuples。前者定义一个宏；如果值为None，则定义的宏没有显式值。 1Tuples 的情况下未定义宏。以后的定义/重新定义/未定义优先。

• include_dirs *(如果提供)必须是字符串列表，要添加到默认目录的目录仅包含此编译的文件搜索路径。

• debug *是布尔值；如果为 true，将指示编译器在目标文件中(或旁边)输出调试符号。

• 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()的库以及作为* 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 *])
  • 将一堆东西链接在一起以创建可执行文件或共享库文件。

“一堆东西”包括作为* object *提供的目标文件列表。 * 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()相反，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 =无*，* target_lang =无*])

  • 链接可执行文件。 * 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 *])

  • 预处理单个以* source 命名的 C/C 源文件。输出将被写入名为 output_file 的文件，如果未提供 output_file ，则将写入 stdout *。 * macros *是针对compile()的宏定义的列表，这将扩大define_macro()和undefine_macro()设置的宏。 * include_dirs *是目录名称的列表，将以与add_include_dir()相同的方式添加到默认列表中。

失败时引发PreprocessError。

CCompiler类定义了以下 Util 方法，供各种具体的子类使用。

• executable_filename(* basename * [，* strip_dir = 0 ， output_dir =''* *])

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

• library_filename(* libname * [，* lib_type ='static'， strip_dir = 0 ， output_dir =“''*])

  • 返回当前平台上给定库名称的文件名。在 Unix 上，* lib_type 为'static'的库的格式通常为liblibname.a，而 lib_type *为'dynamic'的库的格式则为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指定的库搜索目录

• 由具有-c选项的 cc (或类似)可执行文件处理：编译.c至.o

• 链接由 ar 命令处理的静态库(可能使用 ranlib)

• 由 cc -shared处理的链接共享库

9.4. distutils.msvccompiler — Microsoft 编译器

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

MSVCCompiler通常会自行选择正确的编译器，链接器等。要覆盖此选择，必须同时设置环境变量* DISTUTILS_USE_SDK 和 MSSdk *。 * MSSdk *表示已pass SDK 的SetEnv.Cmd脚本设置了当前环境，或在安装 SDK 时已注册了环境变量； * DISTUTILS_USE_SDK *指示 distutils 用户已做出明确选择，以MSVCCompiler覆盖编译器选择。

9.5. distutils.bcppcompiler-Borland 编译器

此模块为 Borland C 编译器提供BorlandCCompiler，它是抽象CCompiler类的子类。

9.6. distutils.cygwincompiler — Cygwin 编译器

此模块提供CygwinCCompiler类，是UnixCCompiler的子类，该子类处理 GNU C 编译器到 Windows 的 Cygwin 端口。它还包含 Mingg32CCompiler 类，该类处理 GCC 的 Mingw32 端口(与 no-cygwin 模式下的 cygwin 相同)。

9.7. distutils.archive_util —归档 Util

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

• distutils.archive_util. make_archive(* base_name ， format * [，* root_dir = None ， base_dir = None ， verbose = 0 ， dry_run = 0 *])
  • 创建一个存档文件(例如zip或tar)。 * base_name *是要创建的文件的名称，减去任何特定于格式的 extensions； * format *是存档格式：zip，tar，gztar，bztar，xztar或ztar之一。 * root_dir 是一个目录，它将是 Files 的根目录；即。在创建归档文件之前，我们通常chdir到 root_dir *。 * base_dir *是我们开始存档的目录；即。 * 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 命名的压缩 Util 必须位于默认程序搜索路径上，因此这可能是特定于 Unix 的。输出的 tar 文件将命名为base_dir.tar，可能还会加上适当的压缩 extensions(.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 zipUtil(如果已安装并在默认搜索路径上找到)。如果两种工具都不可用，则加DistutilsExecError。返回输出 zip 文件的名称。

9.8. distutils.dep_util —依赖性检查

该模块提供用于执行简单的，基于时间戳的文件和文件组依赖关系的Function；同样，Function完全基于此类时间戳依赖性分析。

• distutils.dep_util. newer(* source ， target *)

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

• distutils.dep_util. newer_pairwise(* sources ， targets *)

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

• distutils.dep_util. newer_group(* sources ， target * [，* missing ='error'*])

  • 如果* target 相对于 sources 中列出的任何文件已过期，则返回 true。换句话说，如果 target 存在并且比 sources *中的每个文件都新，则返回 false；否则，返回 false。否则返回 true。 * missing 控制缺少源文件时我们的操作；默认值('error')是从os.stat()内部用OSError炸毁;如果是'ignore'，我们会静默删除所有丢失的源文件；如果它是'newer'，则任何缺少的源文件都会使我们假定 target *已过期(这在“空运行”模式下很方便：它会使您 Feign 执行无效的命令，因为 Importing 丢失了，但这没关系，因为您实际上不会运行命令。

9.9. distutils.dir_util —目录树操作

该模块提供用于在目录和目录树上进行操作的Function。

• distutils.dir_util. mkpath(* name * [，* mode = 0o777 ， verbose = 0 ， dry_run = 0 *])

  • 创建一个目录和所有丢失的祖先目录。如果目录已经存在(或者* name 是空字符串，这意味着当前目录，当然是存在的目录)，则不执行任何操作。如果在创建过程中无法创建某个目录(例如，存在某些子路径，但它是文件而不是目录)，请加DistutilsFileError。如果 verbose *为 true，则将每个 mkdir 的单行摘要打印到 stdout。返回实际创建的目录列表。

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

  • 在* base_dir 下创建将 file *放置在此处所需的所有空目录。 * 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()创建它。复制的finally结果是将 src 中的每个文件都复制到 dst ，并且将 src 下的目录递归复制到 dst 。使用输出名称返回已复制或可能已复制的文件列表。返回值不受 update 或 dry_run 的影响：它只是 src 下所有文件的列表，名称更改为 dst *下。

• preserve_mode 和 preserve_times 与distutils.file_util.copy_file()相同；请注意，它们仅适用于常规文件，不适用于目录。如果 preserve_symlinks *为 true，则符号链接将被复制为符号链接(在支持它们的平台上！)；否则(默认)，将复制符号链接的目标。 * 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 *为 true，则不报告给sys.stdout)。

9.10. distutils.file_util —单个文件操作

该模块包含一些用于对单个文件进行操作的 Util Function。

• 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 为 true(默认值)，则复制文件的模式(类型和权限位，或当前平台上类似的内容)。如果 preserve_times 为 true(默认值)，则还将复制最后修改时间和最后访问时间。如果 update 为 true，则仅当 dst 不存在或 dst 确实存在但早于 src 时才复制 src *。

• link 允许您进行硬链接(使用os.link())或符号链接(使用os.symlink())而不是复制：将其设置为'hard'或'sym'；如果它是None(默认值)，则复制文件。不要在不支持链接的系统上设置 link *：copy_file()不检查是否存在硬链接或符号链接。它使用_copy_file_contents()复制文件内容。

返回一个 Tuples(dest_name, copied)：* dest_name 是输出文件的实际名称，如果复制了文件，则 copied 为 true(如果 dry_run *为 true，则将被复制)。

• distutils.file_util. move_file(* src ， dst * [，* verbose ， dry_run *])
  • 将文件* src 移至 dst 。如果 dst 是目录，则文件将以相同的名称移入该目录；否则， src 仅重命名为 dst *。返回文件的新全名。

• distutils.file_util. write_file(文件名，内容)
  • 创建一个名为* filename 的文件，并向其中写入 contents *(无行终止符的字符串序列)。

9.11. distutils.util —其他其他 Util Function

该模块包含其他任何其他 Util 模块都无法使用的其他零配件。

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

返回值的示例：

• linux-i586

• linux-alpha

• solaris-2.6-sun4u

对于非 POSIX 平台，当前仅返回sys.platform。

对于 Mac OS X 系统，OS 版本反映了二进制文件将在其上运行的最低版本(即，在构建 Python 时的MACOSX_DEPLOYMENT_TARGET的值)，而不是当前系统的 OS 版本。

对于 Mac OS X 上的通用二进制版本，体系结构值反映的是通用二进制状态，而不是当前处理器的体系结构。对于 32 位通用二进制文件，架构为fat；对于 64 位通用二进制文件，架构为fat64；对于 4 路通用二进制文件，架构为universal。从 Python 2.7 和 Python 3.2 开始，体系结构fat3用于 3 向通用构建(ppc，i386，x86_64)，而intel用于 i386 和 x86_64 体系结构的通用构建

在 Mac OS X 上返回值的示例：

• macosx-10.3-ppc

• macosx-10.3-fat

• macosx-10.5-universal

• macosx-10.6-intel

• distutils.util. convert_path(* pathname *)

  • 返回'pathname'作为将在本机文件系统上工作的名称，即，将其拆分为'/'，然后使用当前目录分隔符将其重新放回原处。因为安装脚本中的文件名始终以 Unix 样式提供，所以必须将其转换为本地约定，然后才能在文件系统中实际使用它们。如果* pathname *以斜杠开头或结尾，则在非 Unix-ish 系统上提高ValueError。

• distutils.util. change_root(* new_root ， pathname *)

  • 返回带有* new_root 前缀的 pathname 。如果 pathname 是相对的，则等效于os.path.join(new_root,pathname)，否则，需要将 pathname *设为相对，然后将两者结合在一起，这在 DOS/Windows 上比较棘手。

• distutils.util. check_environ ( )

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

• HOME-用户的主目录(仅 Unix)

• PLAT-当前平台的说明，包括硬件和 os(请参见get_platform())

• distutils.util. subst_vars(* s ， local_vars *)

  • 在* s 上执行 shell/Perl 样式的变量替换。每次出现$后跟名称的情况都被视为变量，并且变量会用 local_vars 词典中的值替换；如果变量不在 local_vars 中，则用os.environ中的值替换。首先检查/增强 os.environ 以确保它包含某些值：参见check_environ()。提高ValueError以获取在 local_vars *或os.environ中找不到的任何变量。

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

• distutils.util. split_quoted(* s *)

  • 根据类 Unix 规则将字符串拆分为引号和反斜杠。简而言之：单词由空格分隔，只要这些空格不被反斜杠或加引号的字符串引起即可。单引号和双引号是等效的，并且引号字符可以反斜杠转义。反斜杠将从任何两个字符的转义序列中删除，仅保留转义的字符。引号字符从任何带引号的字符串中去除。返回单词列表。

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

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

• distutils.util. strtobool(* val *)

  • 将真值的字符串表示形式转换为 true(1)或 false(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和 PEP 488)。 * py_files *是要编译的文件列表；所有不以.py结尾的文件都将被静默跳过。 * optimize *必须为以下之一：

• 0-不要优化

• 1-常规优化(例如python -O)

• 2-额外的优化(例如python -OO)

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

每个bytecode文件中编码的源文件名默认为* py_files 中列出的文件名；您可以使用 prefix 和 basedir *进行修改。 * prefix 是一个字符串，将从每个源文件名中剥离，而 base_dir 是一个目录名称，该名称将作为前缀(在 prefix 被剥离之后)。您可以根据需要提供 prefix 和 base_dir *之一或全部(或都不提供)。

如果* dry_run *为 true，则实际上不执行任何会影响文件系统的操作。

字节编译可以在解释程序中使用标准的py_compile模块直接完成，也可以pass编写临时脚本并执行来间接进行。通常，您应该让byte_compile()确定是否使用直接编译(有关详细信息，请参见源代码)。 * direct *标志由间接模式下生成的脚本使用。除非您知道自己在做什么，否则将其设置为None。

在版本 3.2.3 中进行了更改：在__pycache__子目录中创建名称为导入魔术标签的.pyc文件，而不是在当前目录中创建没有标签的文件。

在版本 3.5 中进行了更改：根据 PEP 488创建.pyc个文件。

• distutils.util. rfc822_escape(* header *)
  • pass确保每个换行符后有 8 个空格，返回转义的* header *版本以包含在 RFC 822Headers 中。请注意，它不会对该字符串进行其他修改。

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 通常是针对显然是finally用户的错误(例如，错误的命令行参数)的错误引发的。

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

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

该模块为标准getopt模块提供了包装，该包装提供了以下附加Function：

• 短期和长期选择权 Binding 在一起

• 选项具有帮助字符串，因此fancy_getopt()可能会创建完整的使用情况摘要

• 选项设置传入对象的属性

• 布尔选项可以具有“负别名”，例如。如果--quiet是--verbose的“负别名”，则命令行上的--quiet会将* verbose *设置为 false。

• distutils.fancy_getopt. fancy_getopt(* options ， negative_opt ， object ， args *)

  • 包装Function。 * options *是(long_option, short_option, help_string) 3Tuples 的列表，如FancyGetopt的构造函数中所述。 * negative_opt 应该是将选项名称 Map 到选项名称的字典，键和值都应该在 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 是一个三 Tuples 列表：(long_option, short_option, help_string)

如果一个选项带有一个参数，则它的* long_option *应该附加'='； * short_option 应该只是一个字符，任何情况下都不能为':'。如果 long_option 没有对应的 short_option ，则 short_option *应该为None。所有选项 Tuples 必须具有长选项。

FancyGetopt类提供以下方法：

• FancyGetopt. getopt([* args = None ， object = None *])
  • 解析 args 中的命令行选项。作为属性存储在* object *上。

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

• FancyGetopt. get_option_order ( )

  • 如果尚未调用getopt()，则返回由上一次运行getopt()引发RuntimeError处理的(option, value)Tuples 的列表。

• FancyGetopt. generate_help([* header = None *])

  • 从此FancyGetopt对象的选项表中生成帮助文本(字符串列表，每行建议的输出内容之一)。

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

9.17. distutils.filelist — FileList 类

此模块提供FileList类，用于戳入文件系统和构建文件列表。

9.18. distutils.log —简单的 PEP 282 样式的日志记录

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

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

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

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

提供了一些附加Function，这些Function可以对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 ( ... )

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

• distutils.sysconfig. get_config_h_filename ( )

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

• distutils.sysconfig. get_makefile_filename ( )

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

• distutils.sysconfig. get_python_inc([* plat_specific * [，前缀]])

  • 返回常规或依赖于平台的 C include 文件的目录。如果* plat_specific 为 true，则返回平台相关的包含目录；否则，返回。如果为 false 或Ellipsis，则返回平台无关的目录。如果给定了* prefix ，则如果 plat_specific *为 true，则将其用作前缀而不是PREFIX，或者用作 exec-prefix 而不是EXEC_PREFIX。

• distutils.sysconfig. get_python_lib([* plat_specific * [，* standard_lib * [，* prefix *]]])

  • 返回常规或依赖于平台的库安装的目录。如果* plat_specific 为 true，则返回平台相关的包含目录；否则，返回。如果为 false 或Ellipsis，则返回平台无关的目录。如果给定了* prefix ，则如果 plat_specific 为 true，则将其用作前缀而不是PREFIX，或者用作 exec-prefix 而不是EXEC_PREFIX。如果 standard_lib *为 true，则返回标准库的目录，而不是用于安装第三方扩展的目录。

以下Function仅适用于distutils软件包。

• distutils.sysconfig. customize_compiler(* compiler *)
  • 对distutils.ccompiler.CCompiler实例进行任何特定于平台的自定义。

目前仅在 Unix 上需要此函数，但应一致调用此函数以支持前向兼容性。它插入随 Unix 风格变化的信息，并存储在 Python 的Makefile中。该信息包括所选的编译器，编译器和链接器选项，以及链接器用于共享库的 extensions。

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

• distutils.sysconfig. set_python_build ( )
  • 通知distutils.sysconfig模块正在将其用作 Python 构建过程的一部分。这会更改文件的许多相对位置，从而使它们可以位于构建区域中，而不必位于已安装的 Python 中。

9.21. distutils.text_file — TextFile 类

此模块提供TextFile类，该类为文本文件提供了一个接口(可选)，该接口负责删除 Comments，忽略空行以及使用反斜杠连接行。

• • class * distutils.text_file. TextFile([* filename = None ， file = None ，** options *])
  • 此类提供了一个类似文件的对象，该对象可以处理具有逐行语法的文本文件时通常要执行的所有操作：删除 Comments(只要#为 Comments 字符)，跳过空白行，pass转义换行符(例如，在行尾使用反斜杠)来加入相邻行，去除前导和/或尾随空格。所有这些都是可选的，可独立控制。

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

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

这些选项均为布尔值，并且会影响readline()返回的值

请注意，由于* rstrip_ws 可以去除结尾的换行符，因此readline()的语义必须与内置文件对象的readline()方法的语义不同！特别是，readline()返回文件末尾的None：如果 rstrip_ws 为 true，而 skip_blanks *不是，则空字符串可能只是空白行(或全空格行)。

• open(文件名)

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

• close ( )

  • 关闭当前文件，然后忘记我们所知道的所有信息(包括文件名和当前行号)。

• warn(* msg * [，* line = None *])

  • 打印(到 stderr)与当前文件中的当前逻辑行相关的警告消息。如果文件中的当前逻辑行跨越多个物理行，则警告涉及整个范围，例如"lines 3-5"。如果提供了* line *，它将覆盖当前行号；它可以是表示物理行范围的列表或 Tuples，也可以是单个物理行的整数。

• readline ( )

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

• readlines ( )

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

• unreadline(* line *)

  • 将* line *(字符串)推入内部缓冲区，以后的readline()次调用将对其进行检查。方便地实现一次行前行的解析器。请注意，使用readline()读取时，用unreadline()“未读”的行随后不会重新清理(去除空格或其他内容)。如果在调用readline()之前对unreadline()进行了多次调用，则将以最新的第一 Sequences 最返回行。

9.22. distutils.version —版本号类

9.23. distutils.cmd — Distutils 命令的抽象 Base Class

此模块提供抽象 Base ClassCommand。

• • class * distutils.cmd. Command(* dist *)
  • 用于定义命令类的抽象 Base Class，即 Distutils 的“工蜂”。命令类的一个有用的类比是将它们视为带有局部变量的子例程，这些局部变量称为* options *。选项在initialize_options()中语句，并在finalize_options()中定义(给定其finally值)，这两个参数必须由每个命令类定义。两者之间的区别是必要的，因为选项值可能来自外部环境(命令行，配置文件等)，并且依赖于其他选项的任何选项都必须在处理完这些外部影响之后计算出来，因此为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 ( )

  • 为该命令支持的所有选项设置finally值。这总是被称为越晚越好，即。从命令行或其他命令完成任何选项分配后。因此，这里是编码选项依赖项的地方：如果* 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 定义为类属性；它是 2Tuples(command_name, predicate)的列表，其中 command_name 是字符串，而 predicate *是函数，字符串或None。 * predicate 是父命令的一种方法，用于确定相应命令在当前情况下是否适用。 (例如install_headers仅在要安装任何 C 头文件的情况下适用.)如果 predicate *为None，则该命令始终适用。

• sub_commands 通常是在类的 end *处定义的，因为谓词可以是该类的方法，因此它们必须已经被定义。典型示例是 install 命令。

9.25. distutils.command —各个 Distutils 命令

9.26. distutils.command.bdist —构建二进制安装程序

9.27. distutils.command.bdist_packager —打包程序的抽象 Base Class

9.28. distutils.command.bdist_dumb —构建一个“哑”安装程序

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

• 类别 distutils.command.bdist_msi. bdist_msi
  • 构建Windows Installer(.msi)二进制程序包。

在大多数情况下，bdist_msi安装程序比bdist_wininst安装程序更好，因为它为 Win64 平台提供了更好的支持，允许 Management 员执行非交互式安装，并允许pass组策略进行安装。

9.30. distutils.command.bdist_rpm —将二进制发行版构建为 Redhat RPM 和 SRPM

9.31. distutils.command.bdist_wininst —生成 Windows 安装程序

从 3.8 版开始不推荐使用：而是使用 bdist_wheel(wheel 软件包)。

9.32. distutils.command.sdist —构建源分发

9.33. distutils.command.build —构建包的所有文件

9.34. distutils.command.build_clib —在包中构建任何 C 库

9.35. distutils.command.build_ext —在软件包中构建任何扩展

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

• 类别 distutils.command.build_py. build_py

• 类别 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.37. distutils.command.build_scripts —构建包的脚本

9.38. distutils.command.clean —清洁软件包构建区域

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

in place内置扩展模块不会被清除，因为它们不在 build 目录中。

9.39. distutils.command.config —执行程序包配置

9.40. distutils.command.install-安装软件包

9.41. distutils.command.install_data —从程序包安装数据文件

9.42. distutils.command.install_headers —从软件包中安装 C/C 头文件

9.43. distutils.command.install_lib-从软件包中安装库文件

9.44. distutils.command.install_scripts —从软件包安装脚本文件

9.45. distutils.command.register —使用 Python 包索引注册模块

register命令向 Python 软件包索引注册软件包。 PEP 301中对此进行了更详细的描述。

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

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