numpy.distutils 用户指南#

警告

numpy.distutils 已弃用，将在 Python >= 3.12 中移除。有关更多详细信息，请参阅 numpy.distutils 的状态和迁移建议

SciPy 结构#

目前 SciPy 项目包含两个包

  • NumPy — 它提供以下包：

    • numpy.distutils - Python distutils 的扩展

    • numpy.f2py - 将 Fortran/C 代码绑定到 Python 的工具

    • numpy._core - Numeric 和 numarray 包的未来替代品

    • numpy.lib - 额外的实用程序函数

    • numpy.testing - NumPy 风格的单元测试工具

    • 等等

  • SciPy — Python 的科学工具集合。

本文档旨在描述如何向 SciPy 添加新的工具。

SciPy 包的要求#

SciPy 包含 Python 包，称为 SciPy 包，这些包可以通过 scipy 命名空间提供给 Python 用户。每个 SciPy 包可能包含其他 SciPy 包。以此类推。因此，SciPy 目录树是具有任意深度和宽度的包树。任何 SciPy 包都可能依赖于 NumPy 包，但对其他 SciPy 包的依赖性应保持最小或为零。

除了其源代码外，SciPy 包还包含以下文件和目录

  • setup.py — 构建脚本

  • __init__.py — 包初始化器

  • tests/ — 单元测试目录

它们的內容将在下面描述。

setup.py 文件#

为了将 Python 包添加到 SciPy，其构建脚本 (setup.py) 必须满足某些要求。最重要的要求是包定义一个 configuration(parent_package='',top_path=None) 函数，该函数返回一个适合传递给 numpy.distutils.core.setup(..) 的字典。为了简化此字典的构建，numpy.distutils.misc_util 提供了 Configuration 类，如下所述。

SciPy 纯 Python 包示例#

以下是一个用于纯 SciPy 包的最小 setup.py 文件的示例

#!/usr/bin/env python3
def configuration(parent_package='',top_path=None):
    from numpy.distutils.misc_util import Configuration
    config = Configuration('mypackage',parent_package,top_path)
    return config

if __name__ == "__main__":
    from numpy.distutils.core import setup
    #setup(**configuration(top_path='').todict())
    setup(configuration=configuration)

configuration 函数的参数指定父 SciPy 包的名称 (parent_package) 以及主 setup.py 脚本的目录位置 (top_path)。这些参数以及当前包的名称应传递给 Configuration 构造函数。

Configuration 构造函数有一个第四个可选参数 package_path，当包文件位于与 setup.py 文件的目录不同的位置时，可以使用它。

其余 Configuration 参数都是关键字参数，它们将用于初始化 Configuration 实例的属性。通常，这些关键字与 setup(..) 函数所期望的关键字相同，例如 packages、ext_modules、data_files、include_dirs、libraries、headers、scripts、package_dir 等。但是，不建议直接指定这些关键字，因为这些关键字参数的内容不会被处理或检查 SciPy 构建系统的完整性。

最后，Configuration 有一个 .todict() 方法，它返回所有配置数据作为字典，适合传递给 setup(..) 函数。

Configuration 实例属性#

除了可以通过关键字参数指定给 Configuration 构造函数的属性外，Configuration 实例（让我们将其表示为 config）还具有以下属性，这些属性在编写安装脚本时可能很有用

  • config.name - 当前包的完整名称。可以将父包的名称提取为 config.name.split('.')。

  • config.local_path - 当前 setup.py 文件所在位置的路径。

  • config.top_path - 主 setup.py 文件所在位置的路径。

Configuration 实例方法#

  • config.todict() — 返回适合传递给 numpy.distutils.core.setup(..) 函数的配置字典。

  • config.paths(*paths) --- applies ``glob.glob(..) to items of paths if necessary. Fixes paths item that is relative to config.local_path.

  • config.get_subpackage(subpackage_name,subpackage_path=None) — 返回子包配置列表。子包在当前目录下的名称为 subpackage_name 中查找，但路径也可以通过可选的 subpackage_path 参数指定。如果 subpackage_name 指定为 None，则子包名称将取自 subpackage_path 的基本名称。子包名称中使用的任何 * 将扩展为通配符。

  • config.add_subpackage(subpackage_name,subpackage_path=None) — 将 SciPy 子包配置添加到当前配置中。参数的含义和用法如上所述，请参见 config.get_subpackage() 方法。

  • config.add_data_files(*files) — 将 files 预先添加到 data_files 列表中。如果 files 项是元组，则其第一个元素定义相对于包安装目录的数据文件复制位置的后缀，而第二个元素指定数据文件的路径。默认情况下，数据文件将复制到包安装目录下。例如，

    config.add_data_files('foo.dat',
                      ('fun',['gun.dat','nun/pun.dat','/tmp/sun.dat']),
                      'bar/car.dat'.
                      '/full/path/to/can.dat',
                      )

    将数据文件安装到以下位置

    <installation path of config.name package>/
  foo.dat
  fun/
    gun.dat
    pun.dat
    sun.dat
  bar/
    car.dat
  can.dat

    数据文件的路径可以是没有任何参数并返回数据文件路径的函数——这在构建包时生成数据文件时很有用。（XXX：解释此函数在何时被调用）

  • config.add_data_dir(data_path) — 将目录 data_path 递归地添加到 data_files 中。从 data_path 开始的整个目录树将复制到包安装目录下。如果 data_path 是元组，则其第一个元素定义相对于包安装目录的数据文件复制位置的后缀，而第二个元素指定数据目录的路径。默认情况下，数据目录将复制到包安装目录下 data_path 的基本名称下。例如，

    config.add_data_dir('fun')  # fun/ contains foo.dat bar/car.dat
config.add_data_dir(('sun','fun'))
config.add_data_dir(('gun','/full/path/to/fun'))

    将数据文件安装到以下位置

    <installation path of config.name package>/
  fun/
     foo.dat
     bar/
        car.dat
  sun/
     foo.dat
     bar/
        car.dat
  gun/
     foo.dat
     bar/
        car.dat

  • config.add_include_dirs(*paths) — 将 paths 预先添加到 include_dirs 列表中。此列表对当前包的所有扩展模块可见。

  • config.add_headers(*files) — 将 files 预先添加到 headers 列表中。默认情况下，标题将安装在 <prefix>/include/pythonX.X/<config.name.replace('.','/')>/ 目录下。如果 files 项是元组，则它的第一个参数指定相对于 <prefix>/include/pythonX.X/ 路径的安装后缀。这是一种 Python distutils 方法；不鼓励在 NumPy 和 SciPy 中使用它，而应使用 config.add_data_files(*files)。

  • config.add_scripts(*files) — 将 files 预先添加到 scripts 列表中。脚本将安装在 <prefix>/bin/ 目录下。

  • config.add_extension(name,sources,**kw) — 创建并向 ext_modules 列表添加一个 Extension 实例。第一个参数 name 定义将在 config.name 包下安装的扩展模块的名称。第二个参数是源列表。 add_extension 方法还接受关键字参数，这些参数将传递给 Extension 构造函数。允许的关键字列表如下： include_dirs、define_macros、undef_macros、library_dirs、libraries、runtime_library_dirs、extra_objects、extra_compile_args、extra_link_args、export_symbols、swig_opts、depends、language、f2py_options、module_dirs、extra_info、extra_f77_compile_args、extra_f90_compile_args。

    请注意，config.paths 方法将应用于所有可能包含路径的列表。 extra_info 是一个字典或一个字典列表，其内容将追加到关键字参数中。列表 depends 包含扩展模块的源代码所依赖的文件或目录的路径。如果 depends 列表中的任何路径都比扩展模块更新，则该模块将被重建。

    源列表可能包含具有模式 def <funcname>(ext, build_dir): return <source(s) or None> 的函数（“源代码生成器”）。如果 funcname 返回 None，则不会生成任何源代码。如果在处理完所有源代码生成器后，Extension 实例没有源代码，则不会构建任何扩展模块。这是有条件地定义扩展模块的推荐方法。源代码生成器函数由 numpy.distutils 的 build_src 子命令调用。

    例如，以下是一个典型的源代码生成器函数

    def generate_source(ext,build_dir):
    import os
    from distutils.dep_util import newer
    target = os.path.join(build_dir,'somesource.c')
    if newer(target,__file__):
        # create target file
    return target

    第一个参数包含 Extension 实例，它可以用于访问其属性，如 depends、sources 等列表，并在构建过程中修改它们。第二个参数给出了构建目录的路径，该路径必须在创建文件到磁盘时使用。

  • config.add_library(name, sources, **build_info) — 向 libraries 列表添加一个库。允许的关键字参数为 depends、macros、include_dirs、extra_compiler_args、f2py_options、extra_f77_compile_args、extra_f90_compile_args。有关参数的更多信息，请参见 .add_extension() 方法。

  • config.have_f77c() — 如果 Fortran 77 编译器可用（即：成功编译了一个简单的 Fortran 77 代码），则返回 True。

  • config.have_f90c() — 如果 Fortran 90 编译器可用（即：一个简单的 Fortran 90 代码编译成功），则返回 True。

  • config.get_version() — 返回当前包的版本字符串，如果无法检测到版本信息，则返回 None。此方法扫描文件 __version__.py、<packagename>_version.py、version.py、__svn_version__.py，查找字符串变量 version、__version__、<packagename>_version。

  • config.make_svn_version_py() — 向 data_files 列表中追加一个数据函数，该函数将在当前包目录中生成 __svn_version__.py 文件。Python 退出时，该文件将从源目录中删除。

  • config.get_build_temp_dir() — 返回一个指向临时目录的路径。这是构建临时文件的目录。

  • config.get_distribution() — 返回 distutils Distribution 实例。

  • config.get_config_cmd() — 返回 numpy.distutils 配置命令实例。

  • config.get_info(*names) —

使用模板转换 .src 文件#

NumPy distutils 支持自动转换名为 <somefile>.src 的源文件。此功能可用于维护非常相似的代码块，这些代码块仅需在块之间进行简单的更改。在安装阶段，如果遇到名为 <somefile>.src 的模板文件，则会从模板中构建一个名为 <somefile> 的新文件，并将其放置在构建目录中以供使用。支持两种形式的模板转换。第一种形式用于名为 <file>.ext.src 的文件，其中 ext 是一个公认的 Fortran 扩展名（f、f90、f95、f77、for、ftn、pyf）。第二种形式用于所有其他情况。

Fortran 文件#

此模板转换器将复制文件中所有包含 ‘<…>’ 的名称的 **function** 和 **subroutine** 块，根据 ‘<…>’ 中的规则进行复制。‘<…>’ 中逗号分隔的单词数决定了块重复的次数。这些单词指示了重复规则 ‘<…>’ 在每个块中应该被替换为什么。一个块中的所有重复规则都必须包含相同数量的逗号分隔的单词，以指示该块应该重复的次数。如果重复规则中的单词需要逗号、左箭头或右箭头，则在前面加上反斜杠 ‘\’。如果重复规则中的单词匹配 ‘\<index>’，则它将被替换为同一重复规范中的第 <index> 个单词。重复规则有两种形式：命名形式和简短形式。

命名重复规则#

当一个块中必须多次使用同一组重复项时，命名重复规则很有用。它使用 <rule1=item1, item2, item3,…, itemN> 指定，其中 N 是块应该重复的次数。在每个块的重复过程中，整个表达式 ‘<…>’ 将首先被替换为 item1，然后替换为 item2，依此类推，直到完成 N 次重复。一旦引入命名重复规范，就可以在 **当前块** 中通过仅引用名称（即 <rule1>）来使用相同的重复规则。

简短重复规则#

简短重复规则看起来像 <item1, item2, item3, …, itemN>。该规则指定整个表达式 ‘<…>’ 应该首先被替换为 item1，然后替换为 item2，依此类推，直到完成 N 次重复。

预定义名称#

以下预定义的命名重复规则可用

  • <prefix=s,d,c,z>

  • <_c=s,d,c,z>

  • <_t=real, double precision, complex, double complex>

  • <ftype=real, double precision, complex, double complex>

  • <ctype=float, double, complex_float, complex_double>

  • <ftypereal=float, double precision, \0, \1>

  • <ctypereal=float, double, \0, \1>

其他文件#

非 Fortran 文件使用单独的语法来定义应使用变量扩展（类似于 Fortran 特定重复的命名重复规则）重复的模板块。

NumPy Distutils 预处理用自定义模板语言编写的 C 源文件（扩展名：.c.src），以生成 C 代码。@ 符号用于包装宏式变量，以增强字符串替换机制，该机制可能描述（例如）一组数据类型。

模板语言块由 /**begin repeat 和 /**end repeat**/ 行分隔，也可以使用连续编号的分隔行（例如 /**begin repeat1 和 /**end repeat1**/）嵌套。

  1. /**begin repeat 单独在一行上表示一个应该重复的段的开始。

  2. 使用 #name=item1, item2, item3, ..., itemN# 定义命名变量扩展，并将其放置在连续的行上。这些变量在每个重复块中用相应的单词替换。同一个重复块中的所有命名变量必须定义相同数量的单词。

  3. 在为命名变量指定重复规则时，item*N 是 item, item, ..., item 重复 N 次的简写。此外，括号与 *N 的组合可用于对应该重复的多个项目进行分组。因此，#name=(item1, item2)*4# 等效于 #name=item1, item2, item1, item2, item1, item2, item1, item2#。

  4. */ 单独在一行上表示变量扩展命名的结束。下一行是将使用命名规则重复的第一行。

  5. 在要重复的块内，要扩展的变量指定为 @name@。

  6. /**end repeat**/ 单独在一行上表示前一行是该块的最后一行。

  7. NumPy C 源代码中的循环可能包含一个 @TYPE@ 变量，该变量用于字符串替换，它被预处理为多个在其他方面相同的循环，这些循环包含多个字符串，例如 INT、LONG、UINT、ULONG。因此，@TYPE@ 样式语法通过模仿具有泛型类型支持的语言来减少代码重复和维护负担。

以下模板源示例可以更清楚地说明上述规则

 1 /* TIMEDELTA to non-float types */
 2
 3 /**begin repeat
 4  *
 5  * #TOTYPE = BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG,
 6  *           LONGLONG, ULONGLONG, DATETIME,
 7  *           TIMEDELTA#
 8  * #totype = npy_byte, npy_ubyte, npy_short, npy_ushort, npy_int, npy_uint,
 9  *           npy_long, npy_ulong, npy_longlong, npy_ulonglong,
10  *           npy_datetime, npy_timedelta#
11  */
12
13 /**begin repeat1
14  *
15  * #FROMTYPE = TIMEDELTA#
16  * #fromtype = npy_timedelta#
17  */
18 static void
19 @FROMTYPE@_to_@TOTYPE@(void *input, void *output, npy_intp n,
20         void *NPY_UNUSED(aip), void *NPY_UNUSED(aop))
21 {
22     const @fromtype@ *ip = input;
23     @totype@ *op = output;
24
25     while (n--) {
26         *op++ = (@totype@)*ip++;
27     }
28 }
29 /**end repeat1**/
30
31 /**end repeat**/

对泛型类型 C 源文件（无论是 NumPy 本身还是使用 NumPy Distutils 的任何第三方包）的预处理由 conv_template.py 执行。这些模块在构建过程中生成的类型特定 C 文件（扩展名：.c）已准备好进行编译。这种形式的泛型类型也支持 C 头文件（预处理以生成 .h 文件）。

numpy.distutils.misc_util 中的有用函数#

  • get_numpy_include_dirs() — 返回 NumPy 基础包含目录的列表。NumPy 基础包含目录包含头文件，例如 numpy/arrayobject.h、numpy/funcobject.h 等。对于已安装的 NumPy，返回的列表长度为 1，但构建 NumPy 时，该列表可能包含更多目录，例如，指向 config.h 文件的路径，该文件由 numpy/base/setup.py 文件生成，并由 numpy 头文件使用。

  • append_path(prefix,path) — 将 path 智能附加到 prefix。

  • gpaths(paths, local_path='') — 对路径应用 glob，并在需要时在前面添加 local_path。

  • njoin(*path) — 连接路径名组件 + 将 / 分隔的路径转换为 os.sep 分隔的路径，并从路径中解析 ..、.。例如：njoin('a',['b','./c'],'..','g') -> os.path.join('a','b','g')。

  • minrelpath(path) — 解析 path 中的点。

  • rel_path(path, parent_path) — 返回相对于 parent_path 的 path。

  • def get_cmd(cmdname,_cache={}) — 返回 numpy.distutils 命令实例。

  • all_strings(lst)

  • has_f_sources(sources)

  • has_cxx_sources(sources)

  • filter_sources(sources) — 返回 c_sources, cxx_sources, f_sources, fmodule_sources

  • get_dependencies(sources)

  • is_local_src_dir(directory)

  • get_ext_source_files(ext)

  • get_script_files(scripts)

  • get_lib_source_files(lib)

  • get_data_files(data)

  • dot_join(*args) — 使用点连接非零参数。

  • get_frame(level=0) — 从调用堆栈中返回给定级别的帧对象。

  • cyg2win32(path)

  • mingw32() — 在使用 mingw32 环境时返回 True。

  • terminal_has_colors()、red_text(s)、green_text(s)、yellow_text(s)、blue_text(s)、cyan_text(s)

  • get_path(mod_name,parent_path=None) — 返回给定 parent_path 时相对于 parent_path 的模块的路径。也处理 __main__ 和 __builtin__ 模块。

  • allpath(name) — 在 name 中用 os.sep 替换 /。

  • cxx_ext_match、fortran_ext_match、f90_ext_match、f90_module_name_match

numpy.distutils.system_info 模块#

  • get_info(name,notfound_action=0)

  • combine_paths(*args,**kws)

  • show_all()

numpy.distutils.cpuinfo 模块#

  • cpuinfo

numpy.distutils.log 模块#

  • set_verbosity(v)

numpy.distutils.exec_command 模块#

  • get_pythonexe()

  • find_executable(exe, path=None)

  • exec_command( command, execute_in='', use_shell=None, use_tee=None, **env )

__init__.py 文件#

典型的 SciPy __init__.py 的头部是

"""
Package docstring, typically with a brief description and function listing.
"""

# import functions into module namespace
from .subpackage import *
...

__all__ = [s for s in dir() if not s.startswith('_')]

from numpy.testing import Tester
test = Tester().test
bench = Tester().bench

NumPy Distutils 中的额外功能#

在 setup.py 脚本中为库指定 config_fc 选项#

可以在 setup.py 脚本中指定 config_fc 选项。例如，使用

config.add_library('library',
                   sources=[...],
                   config_fc={'noopt':(__file__,1)})

将编译 library 源代码，但不使用优化标志。

建议以与编译器无关的方式指定此类 config_fc 选项。

从源代码中获取额外的 Fortran 77 编译器选项#

一些旧的 Fortran 代码需要特殊的编译器选项才能正常工作。为了针对每个源文件指定编译器选项，numpy.distutils Fortran 编译器会在源文件的前 20 行中查找以下模式。

CF77FLAGS(<fcompiler type>) = <fcompiler f77flags>

并使用 f77flags 来指定对应 fcompiler 类型（第一个字符 C 是可选的）。

TODO: 此功能也可以轻松扩展到 Fortran 90 代码。如果您需要此功能，请告诉我们。

本页内容