Packaging (numpy.distutils)

NumPy提供增强的distutils功能，使其更容易构建和安装使用Fortran编译库的子包，自动生成代码和扩展模块。要使用NumPy distutils的功能，请使用numpy.distutils.core的setup命令。在numpy.distutils.misc_util中还提供了一个有用的Configuration类，它可以更容易地构造关键字参数以传递给安装函数（通过传递从todict()方法的类）。有关详细信息，请参阅<site-packages>/numpy/doc/DISTUTILS.txt中的NumPy Distutils用户指南。

Modules in numpy.distutils

misc_util

get_numpy_include_dirs()
dict_append（d，\ * \ * kws）
appendpath（prefix，path）
allpath（name）	使用操作系统的路径分隔符将/ -separated路径名转换为一个。
dot_join（\ * args）
generate_config_py（target）	生成包含在构建包期间使用的system_info信息的config.py文件。
get_cmd（cmdname [，_cache]）
terminal_has_colors()
red_text（s）
green_text（s）
yellow_text（s）
blue_text（s）
cyan_text（s）
cyg2win32（path）
all_strings（lst）	如果lst中的所有项目都是字符串对象，则返回True。
has_f_sources（来源）	如果源包含Fortran文件，则返回True
has_cxx_sources（sources）	如果源包含C ++文件，则返回True
filter_sources（sources）	返回四个文件名列表，分别包含C，C ++，Fortran和Fortran 90模块源。
get_dependencies（sources）
is_local_src_dir（目录）	如果目录是本地目录，返回true。
get_ext_source_files（ext）
get_script_files（scripts）

class numpy.distutils.misc_util.Configuration(package_name=None, parent_name=None, top_path=None, package_path=None, **attrs)

构造给定包名称的配置实例。如果parent_name不为None，则将包构建为parent_name包的子包。如果top_path和package_path为None，则假定它们等于创建此实例的文件的路径。numpy分布中的setup.py文件是如何使用Configuration实例的好例子。

todict()

返回与distutils setup函数的关键字参数兼容的字典。

例子

>>> setup(**config.todict())                           

get_distribution()

返回distutils分布对象为self。

get_subpackage(subpackage_name, subpackage_path=None, parent_name=None, caller_level=1)

返回子包配置列表。

参数：

subpackage_name：str或None

获取配置的子包的名称。subpackage_name中的'*'作为通配符处理。

subpackage_path：str

如果为None，则路径假定为本地路径加上subpackage_name。如果在subpackage_path中找不到setup.py文件，则使用默认配置。

parent_name：str

父名称。

add_subpackage(subpackage_name, subpackage_path=None, standalone=False)

将子包添加到当前配置实例。

这在用于将子包添加到包的setup.py脚本中很有用。

参数：

subpackage_name：str

子包名称

subpackage_path：str

如果给定，子包路径（例如子包）位于subpackage_path / subpackage_name中。如果为无，则假定子包位于本地路径/ subpackage_name中。

standalone：bool

add_data_files(*files)

将数据文件添加到配置data_files。

参数：

文件：sequence

参数可以是

• 2-sequence (,)
• 数据文件的路径，其中python datadir前缀默认为package dir。

笔记

文件序列的每个元素的形式是非常灵活的，允许从包中获取文件的何处以及它们最终将被安装在系统上的多种组合。最基本的用法是将files参数序列的一个元素作为一个简单的文件名。这将导致该文件从本地路径安装到self.name包的安装路径（包路径）。文件参数也可以是相对路径，在这种情况下，整个相对路径将安装到包目录中。最后，文件可以是绝对路径名，在这种情况下，文件将在绝对路径名中找到，但安装到包路径。

这种基本行为可以通过传递2元组作为文件参数来增强。元组的第一个元素应该指定应该在其中安装文件的剩余序列的相对路径（在软件包安装目录下）（它与源分发中的文件名无关）。元组的第二个元素是应该安装的文件序列。此序列中的文件可以是文件名，相对路径或绝对路径。对于绝对路径，文件将安装在顶层软件包安装目录中（不考虑第一个参数）。文件名和相对路径名将安装在软件包安装目录中作为元组的第一个元素提供的路径名下。

安装路径规则：

1. file.txt - >（。，file.txt） - > parent / file.txt
2. foo / file.txt - >（foo，foo / file.txt） - > parent / foo / file.txt
3. /foo/bar/file.txt - >（。，/foo/bar/file.txt） - > parent / file.txt
4. * .txt - > parent / a.txt，parent / b.txt
5. foo / * .txt - > parent / foo / a.txt，parent / foo / b.txt
6. / .txt - >（，* / .txt） - > parent / c / a.txt，parent / d / b.txt
7. （sun，file.txt） - > parent / sun / file.txt
8. （sun，bar / file.txt） - > parent / sun / file.txt
9. （sun，/foo/bar/file.txt） - > parent / sun / file.txt
10. （sun，* .txt） - > parent / sun / a.txt，parent / sun / b.txt
11. （sun，bar / * .txt） - > parent / sun / a.txt，parent / sun / b.txt
12. （sun / ，* / .txt） - > parent / sun / c / a.txt，parent / d / b.txt

另一个特性是，到数据文件的路径实际上可以是一个不带参数并返回到数据文件的实际路径的函数。这在构建包时生成数据文件时很有用。

例子

将文件添加到要包含在包中的data_files列表中。

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

将安装这些数据文件到：

<package install directory>/
 foo.dat
 fun/
   gun.dat
   nun/
     pun.dat
 sun.dat
 bar/
   car.dat
 can.dat

其中是包（或子包）目录，例如'/usr/lib/python2.4/site-packages/mypackage'（'C：Python2.4 Lib site-packages mypackage'）或'/ usr /lib/python2.4/site-packages/mypackage/mysubpackage'（'C：Python2.4 Lib site-packages mypackage mysubpackage'）。

add_data_dir(data_path)

递归地将data_path下的文件添加到data_files列表。

递归地将data_path下的文件添加到要安装（和分发）的data_files列表中。data_path可以是相对路径名或绝对路径名，也可以是2元组，其中第一个参数显示安装目录中应安装数据目录的位置。

参数：

data_path：seq或str

参数可以是

• 2序列（，）
• 数据目录的路径，其中python datadir后缀默认为package dir。

笔记

安装路径规则：

foo / bar - >（foo / bar，foo / bar） - > parent / foo / bar（gun，foo / bar） - > parent / gun foo / * - >（foo / a，foo / a） / b，foo / b） - > parent / foo / a，parent / foo / b（gun，foo / ） - （gun，foo / a），（gun，foo / b）枪（枪/，foo / ） - ＆gt；父/枪/ a，父/枪/ b / foo / bar - ＆gt； （bar，/ foo / bar） - >父/条（枪，/ foo / bar） - ＆gt；父/枪（fun / / gun / *，sun / foo / bar） - > parent / fun / foo / gun / bar

例子

例如假设源目录包含fun / foo.dat和fun / bar / car.dat：

>>> self.add_data_dir('fun')                       
>>> self.add_data_dir(('sun', 'fun'))              
>>> self.add_data_dir(('gun', '/full/path/to/fun'))

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

<package install directory>/
  fun/
    foo.dat
    bar/
      car.dat
  sun/
    foo.dat
    bar/
      car.dat
  gun/
    foo.dat
    car.dat

add_include_dirs(*paths)

添加配置包含目录的路径。

将给定的路径序列添加到include_dirs列表的开头。此列表对当前软件包的所有扩展模块都可见。

add_headers(*files)

为配置添加可安装的标头。

将给定的文件序列添加到标题列表的开头。By default, headers will be installed under // directory. 如果文件项是元组，则其第一个参数指定相对于路径的实际安装位​​置。

参数：

文件：str或seq

参数可以是：

• 2-sequence (,)
• 路径到头文件，其中python includeir后缀将默认为包名称。

add_extension(name, sources, **kw)

将扩展名添加到配置。

创建并将扩展实例添加到ext_modules列表。此方法还采用以下可选的关键字参数传递到Extension构造函数。

参数：

名称：str

扩展名称

源：seq

源列表。源列表可能包含一些函数（称为源生成器），它们必须将扩展实例和构建目录作为输入，并返回源文件或源文件列表或无。如果返回None，则不会生成任何源。如果扩展实例在处理所有源生成器之后没有源，则不构建扩展模块。

include_dirs：

define_macros：

undef_macros：

library_dirs：

库：

runtime_library_dirs：

extra_objects：

extra_compile_args：

extra_link_args：

extra_f77_compile_args：

extra_f90_compile_args：

export_symbols：

swig_opts：

取决于：

依赖列表包含扩展模块的来源所依赖的文件或目录的路径。如果依赖列表中的任何路径比扩展模块新，则将重建模块。

语言：

f2py_options：

module_dirs：

extra_info：dict或list

要附加到关键字的关键字的dict的dict或list。

笔记

self.paths（...）方法应用于可能包含路径的所有列表。

add_library(name, sources, **build_info)

将库添加到配置。

参数：

名称：str

扩展名称。

源：序列

源的列表。源列表可能包含一些函数（称为源生成器），它们必须将扩展实例和构建目录作为输入，并返回源文件或源文件列表或无。如果返回None，则不会生成任何源。如果扩展实例在处理所有源生成器之后没有源，则不构建扩展模块。

build_info：dict，可选

允许以下密钥：

• 依靠
• 宏
• include_dirs
• extra_compiler_args
• extra_f77_compiler_args
• extra_f90_compiler_args
• f2py_options
• 语言

add_scripts(*files)

将脚本添加到配置。

将文件序列添加到脚本列表的开头。脚本将安装在/ bin /目录下。

add_installed_library(name, sources, install_dir, build_info=None)

与add_library类似，但安装了指定的库。

与distutils一起使用的大多数C库仅用于构建Python扩展，但是通过此方法构建的库将被安装，以便它们可以被第三方包重用。

参数：

名称：str

已安装库的名称。

源：序列

库源文件列表。有关详细信息，请参见add_library。

install_dir：str

相对于当前子包安装库的路径。

build_info：dict，可选

允许以下密钥：

• 依靠
• 宏
• include_dirs
• extra_compiler_args
• extra_f77_compiler_args
• extra_f90_compiler_args
• f2py_options
• 语言

返回：

没有

也可以看看

add_library，add_npy_pkg_config，get_info

笔记

编译链接到指定C库所需的选项的最佳方法是使用“libname.ini”文件，并使用get_info检索所需的选项（请参阅add_npy_pkg_config

add_npy_pkg_config(template, install_dir, subst_dict=None)

从模板生成并安装npy-pkg配置文件。

从模板生成的配置文件安装在给定的安装目录中，使用subst_dict进行变量替换。

参数：

模板：str

模板的路径，相对于当前的包路径。

install_dir：str

在哪里安装npy-pkg配置文件，相对于当前的包路径。

subst_dict：dict，可选

如果给定，则在安装时，模板文件中的任何字符串@key@将替换为subst_dict[key]。安装前缀始终可通过变量@prefix@获得，因为安装前缀不容​​易从setup.py中可靠地获取。

也可以看看

add_installed_library，get_info

笔记

这适用于标准安装和就地构建，即@prefix@指的是原位构建的源目录。

例子

config.add_npy_pkg_config('foo.ini.in', 'lib', {'foo': bar})

假设foo.ini.in文件具有以下内容：

[meta]
Name=@foo@
Version=1.0
Description=dummy description

[default]
Cflags=-I@prefix@/include
Libs=

生成的文件将具有以下内容：

[meta]
Name=bar
Version=1.0
Description=dummy description

[default]
Cflags=-Iprefix_dir/include
Libs=

并将作为foo.ini安装在'lib'子路径中。

paths(*paths, **kws)

将glob应用于路径，如果需要，在前面添加local_path。

将glob.glob（...）应用于序列中的每个路径（如果需要），如果需要，预先置入local_path。因为在所有源列表上调用，所以允许在扩展模块和库和脚本的源列表中指定通配符，并允许路径名相对于源目录。

get_config_cmd()

返回numpy.distutils config命令实例。

get_build_temp_dir()

返回到临时文件应放置的临时目录的路径。

have_f77c()

检查Fortran 77编译器的可用性。

在源生成函数中使用它，以确保设置分发实例已初始化。

笔记

如果Fortran 77编译器可用（因为一个简单的Fortran 77代码能够成功编译），则为true。

have_f90c()

检查Fortran 90编译器的可用性。

在源生成函数中使用它，以确保设置分发实例已初始化。

笔记

如果Fortran 90编译器可用（因为一个简单的Fortran 90代码能够成功编译）

get_version(version_file=None, version_variable=None)

尝试获取包的版本字符串。

返回当前软件包的版本字符串或无法检测版本信息。

笔记

此方法扫描名为__version__.py，_version.py，version.py和__svn_version__.py的文件，用于字符串变量版本，__version__和_version，直到找到版本号。 t0>

make_svn_version_py(delete=True)

将数据函数附加到data_files列表，将生成__svn_version__.py文件到当前包目录。

从SVN版本号生成包__svn_version__.py文件，它将在python退出后删除，但将在执行sdist，etc命令时可用。

笔记

如果之前存在__svn_version__.py，则不会执行任何操作。

这用于处理SVN存储库中的源目录。

make_config_py(name='__config__')

生成包含在构建包期间使用的包含system_info信息的包__config__.py文件。

此文件安装到软件包安装目录。

get_info(*names)

获取资源信息。

返回单个字典中参数列表中所有名称的信息（从system_info.get_info）。

Other modules

system_info.get_info（name [，notfound_action]）	notfound_action：
system_info.get_standard_file（fname）	返回名为“fname”的文件的列表
cpuinfo.cpu
log.set_verbosity（v [，force]）
exec_command	exec_command

Building Installable C libraries

不安装常规C库（通过add_library安装），并且仅在构建期间使用（它们是静态链接的）。可安装的C库是一个纯C库，它不依赖于python C运行时，并且安装成可以被第三方包使用。要构建和安装C库，您只需使用方法add_installed_library而不是add_library，除了额外的install_dir参数：

>>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')

npy-pkg-config files

要使必要的构建选项可用于第三方，您可以使用numpy.distutils中实现的npy-pkg-config机制。此机制基于包含所有选项的.ini文件。.ini文件与pkg-config unix实用程序使用的.pc文件非常相似：

[meta]
Name: foo
Version: 1.0
Description: foo library

[variables]
prefix = /home/user/local
libdir = ${prefix}/lib
includedir = ${prefix}/include

[default]
cflags = -I${includedir}
libs = -L${libdir} -lfoo

通常，该文件需要在构建期间生成，因为它需要在构建时仅知道一些信息（例如前缀）。如果使用配置方法add_npy_pkg_config，则这是自动的。假设我们有一个模板文件foo.ini.in如下：

[meta]
Name: foo
Version: @version@
Description: foo library

[variables]
prefix = @prefix@
libdir = ${prefix}/lib
includedir = ${prefix}/include

[default]
cflags = -I${includedir}
libs = -L${libdir} -lfoo

和setup.py中的以下代码：

>>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
>>> subst = {'version': '1.0'}
>>> config.add_npy_pkg_config('foo.ini.in', 'lib', subst_dict=subst)

这会将文件foo.ini安装到目录package_dir / lib中，并且foo.ini文件将从foo.ini.in生成，其中每个@version@将替换为subst_dict['version']。字典有一个额外的前缀替换规则自动添加，其中包含安装前缀（因为这不容易从setup.py获得）。npy-pkg-config文件也可以使用从get_npy_pkg_dir函数返回的路径安装在与numpy相同的位置。

Reusing a C library from another package

可以从numpy.distutils.misc_util中的get_info函数轻松检索信息：

>>> info = get_info('npymath')
>>> config.add_extension('foo', sources=['foo.c'], extra_info=**info)

可以向get_info提供查找.ini文件的其他路径列表。

Conversion of .src files

NumPy distutils支持自动转换名为.src的源文件。 该设施可以用于维持非常类似的代码块，只需要简单的块之间的改变。在安装的构建阶段，如果遇到名为.src的模板文件，则从模板构造名为的新文件，并将其放在要使用的构建目录中。 支持两种形式的模板转换。第一种形式出现在名为.ext.src的文件中，其中ext是一个公认的Fortran扩展名（f，f90，f95，f77，for，ftn，pyf）。 第二种形式用于所有其他情况。

Fortran files

此模板转换器将根据“<...>”中的规则复制文件中名称包含“<...>”的所有函数和子例程 '<...>'中逗号分隔的字的数量确定块被重复的次数。 这些字是什么表示什么重复规则，'<...>'，应该在每个块中替换。 块中的所有重复规则必须包含相同数量的逗号分隔的字，指示块应该重复的次数。如果重复规则中的单词需要逗号，左边或右边，那么在它前面加上一个反斜杠“”。如果重复规则中的单词与'\ '匹配，则在相同重复规范中它将被字替换。 重复规则有两种形式：命名和短。

Named repeat rule

当同一组重复必须在块中使用多次时，命名重复规则很有用。It is specified using , where N is the number of times the block should be repeated. 在块的每个重复，整个表达式，'<...>'将首先替换为item1，然后替换为item2，依此类推，直到完成N个重复。 Once a named repeat specification has been introduced, the same repeat rule may be used in the current block by referring only to the name (i.e. .

Short repeat rule

A short repeat rule looks like . 规则指定整个表达式'<...>'应首先替换为item1，然后替换为item2，依此类推，直到完成N个重复。

Pre-defined names

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

• <_c>
• <_t complex="" double="" precision="">

Other files

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

1. “/ **开始重复”在一行上标记了应该重复的段的开始。
2. 命名的变量扩展使用＃name = item1，item2，item3，...，itemN＃定义，并放置在连续的行上。这些变量在每个重复块中用相应的字替换。在同一重复块中的所有命名变量必须定义相同数量的字。
3. 在指定命名变量的重复规则时，项目* N是项目，项目，...，项目的重复N次的简写。此外，括号与* N组合可用于对应重复的多个项目进行分组。因此，＃name =（item1，item2）* 4＃相当于＃name = item1，item2，item1，item2，item1，item2，item1，item2＃
4. “* /”在一行上本身标志着变量扩展命名的结束。下一行是将使用命名规则重复的第一行。
5. 在要重复的块中，应扩展的变量指定为@ name @。
6. “/ ** end repeat ** /”在一行上，将前一行标记为要重复的块的最后一行。