`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/ — unittests 目录

它们的内容如下所述.

`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) — 如果需要,对 paths 的项应用 glob.glob(..) .修复相对于 config.local_path 的 paths 项.
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) — 创建并添加一个 Extension 实例到 ext_modules 列表.第一个参数 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
```
第一个参数包含可以用于访问其属性（如 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 编译器可用则返回 True（即:一个简单的 Fortran 77 代码成功编译）.
config.have_f90c() — 如果 Fortran 90 编译器可用则返回 True（即:一个简单的 Fortran 90 代码成功编译）.
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 的源文件.这个功能可以用来维护非常相似的代码块,这些代码块之间只需要简单的更改.在 setup 的构建阶段,如果遇到名为 <somefile>.src 的模板文件,则会从模板构建一个名为 <somefile> 的新文件,并将其放置在构建目录中以供使用.支持两种形式的模板转换.第一种形式适用于名为 <file>.ext.src 的文件,其中 ext 是可识别的 Fortran 扩展（f, f90, f95, f77, for, ftn, pyf）.第二种形式用于所有其他情况.

Fortran 文件#

此模板转换器将根据 ‘<…>’ 中的规则,复制文件中所有包含 ‘<…>’ 的函数和 子程序 块.’<…>’ 中逗号分隔的单词数量决定了块重复的次数.这些单词指示了每个块中重复规则 ‘<…>’ 应替换的内容.块中的所有重复规则必须包含相同数量的逗号分隔单词,指示该块应重复的次数.如果重复规则中的单词需要逗号、左箭头或右箭头,则在前面加上反斜杠 ‘ '.如果重复规则中的单词匹配 ‘ <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=实数, 双精度, 复数, 双复数>
<ftype=实数, 双精度, 复数, 双复数>
<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**/:

/**begin repeat 单独一行标记了一个应重复的段的开始.
命名变量扩展使用 #name=item1, item2, item3, ..., itemN# 定义,并放在连续的行上.这些变量在每个重复块中被相应的单词替换.同一重复块中的所有命名变量必须定义相同数量的单词.
在指定命名变量的重复规则时,``item*N`` 是 item, item, ..., item 重复 N 次的简写.此外,括号与 *N 结合可以用于分组应重复的多个项目.因此,``#name=(item1, item2)*4#`` 等同于 #name=item1, item2, item1, item2, item1, item2, item1, item2#.
单独一行的 */ 标记了变量扩展命名的结束.下一行是使用命名规则重复的第一行.
在要重复的块内,应展开的变量被指定为 @name@.
/**end repeat**/ 单独一行表示前一行是将被重复的块的最后一行.
在NumPy的C源代码中的一个循环可能会有一个 @TYPE@ 变量,该变量针对字符串替换,预处理后会变成多个带有诸如 INT、LONG、UINT、ULONG 等字符串的相同循环.因此,``@TYPE@`` 风格的语法通过模仿具有泛型类型支持的语言,减少了代码重复和维护负担.

上述规则在以下模板源示例中可能更清晰:

 /* TIMEDELTA to non-float types */

 /**begin repeat
  *
  * #TOTYPE = BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG,
  *           LONGLONG, ULONGLONG, DATETIME,
  *           TIMEDELTA#
  * #totype = npy_byte, npy_ubyte, npy_short, npy_ushort, npy_int, npy_uint,
  *           npy_long, npy_ulong, npy_longlong, npy_ulonglong,
  *           npy_datetime, npy_timedelta#
  */

 /**begin repeat1
  *
  * #FROMTYPE = TIMEDELTA#
  * #fromtype = npy_timedelta#
  */
 static void
 @FROMTYPE@_to_@TOTYPE@(void *input, void *output, npy_intp n,
         void *NPY_UNUSED(aip), void *NPY_UNUSED(aop))
 {
     const @fromtype@ *ip = input;
     @totype@ *op = output;

     while (n--) {
         *op++ = (@totype@)*ip++;
     }
 }
 /**end repeat1**/

 /**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 时,列表可能包含更多目录,例如,``numpy/base/setup.py`` 文件生成并被 numpy 头文件使用的 config.h 文件的路径.
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) — 当给定父路径时,返回模块相对于父路径的路径.也处理 __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 编译器会查找以下模式:

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

在前20行源代码中使用 f77flags 指定 fcompiler 的类型（第一个字符 C 是可选的）.

待办事项:此功能也可以轻松扩展到 Fortran 90 代码.如果您需要此功能,请告诉我们.

numpy.distutils 用户指南#

SciPy 结构#

SciPy 包的要求#

setup.py 文件#