NumPy参考 > Packaging (numpy.distutils)
NumPy提供了增强的distutils功能,可以更轻松地构建和安装使用Fortran编译库的子包,自动生成代码和扩展模块。要使用NumPy distutils的功能,请使用中的setup
命令
numpy.distutils.core
。Configuration
还提供了一个有用的类,
numpy.distutils.misc_util
它可以使构造关键字参数更容易传递给设置函数(通过传递从该类的todict()方法获得的字典)。NumPy Distutils-用户指南中提供了更多信息。
numpy.distutils
|
|
exec_command |
|
|
|
|
notfound_action: |
从以下位置返回名为“ fname”的文件的列表:1)系统范围的目录(此模块的目录位置)2)用户HOME目录(os.environ ['HOME'])3)本地目录 |
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
实例的良好示例。
get_subpackage
(self,subpackage_name,subpackage_path = None,parent_name = None,caller_level = 1 )[源代码] ¶返回子包配置列表。
要获取配置的子程序包的名称。subpackage_name中的“ *”被视为通配符。
如果为None,则假定该路径为本地路径加上subpackage_name。如果在subpackage_path中找不到setup.py文件,则使用默认配置。
父母名字。
add_subpackage
(self,subpackage_name,subpackage_path = None,standalone = False )[源代码] ¶将子包添加到当前的Configuration实例。
这在setup.py脚本中很有用,用于将子软件包添加到软件包中。
子包的名称
如果给定,则子包路径(如子包)位于subpackage_path / subpackage_name中。如果为None,则假定子包位于本地路径/ subpackage_name中。
add_data_files
(self,* files )[源代码] ¶将数据文件添加到配置data_files。
参数可以是
2序列(<datadir前缀>,<数据文件的路径>)
数据文件的路径,其中python datadir前缀默认为package dir。
笔记
文件序列中每个元素的形式都非常灵活,允许从软件包中获取文件的位置以及最终应将它们安装在系统上的位置的多种组合。最基本的用法是将文件参数序列的元素设置为简单文件名。这将导致该文件从本地路径安装到self.name软件包的安装路径(软件包路径)。file参数也可以是相对路径,在这种情况下,整个相对路径都将安装到软件包目录中。最后,文件可以是绝对路径名,在这种情况下,可以在绝对路径名下找到该文件,但将其安装到程序包路径中。
可以通过传入2元组作为文件参数来增强这种基本行为。元组的第一个元素应指定相对路径(在软件包安装目录下),其余文件序列应安装到该相对路径(与源分发中的文件名无关)。元组的第二个元素是应安装的文件序列。此序列中的文件可以是文件名,相对路径或绝对路径。对于绝对路径,该文件将安装在顶级软件包安装目录中(无论第一个参数如何)。文件名和相对路径名将安装在软件包安装目录下的元组第一个元素给出的路径名下。
安装路径规则:
file.txt->(。,file.txt)-> parent / file.txt
foo / file.txt->(foo,foo / file.txt)-> parent / foo / file.txt
/foo/bar/file.txt->(。,/foo/bar/file.txt)-> parent / file.txt
*
.txt-> parent / a.txt,parent / b.txtfoo /
*
.txt``-> parent / foo / a.txt,parent / foo / b.txt
*/*.txt
->(*
,*
/*
.txt)-> parent / c / a.txt,parent / d / b.txt(sun,file.txt)-> parent / sun / file.txt
(sun,bar / file.txt)-> parent / sun / file.txt
(sun,/foo/bar/file.txt)-> parent / sun / file.txt
(sun,
*
.txt)-> parent / sun / a.txt,parent / sun / b.txt(sun,bar /
*
.txt)-> parent / sun / a.txt,parent / sun / b.txt(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
其中,<package install directory>是软件包(或子软件包)目录,例如“ /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
(self,data_path )[源代码] ¶将data_path下的文件递归添加到data_files列表。
将data_path下的文件递归添加到要安装(和分发)的data_files列表中。data_path可以是相对路径名,也可以是绝对路径名,也可以是2元组,其中第一个参数显示应将数据目录安装到安装目录中的哪个位置。
参数可以是
2序列(<datadir后缀>,<数据目录的路径>)
数据目录的路径,其中python datadir后缀默认为package dir。
笔记
安装路径规则:
foo/bar -> (foo/bar, foo/bar) -> parent/foo/bar
(gun, foo/bar) -> parent/gun
foo/* -> (foo/a, foo/a), (foo/b, foo/b) -> parent/foo/a, parent/foo/b
(gun, foo/*) -> (gun, foo/a), (gun, foo/b) -> gun
(gun/*, foo/*) -> parent/gun/a, parent/gun/b
/foo/bar -> (bar, /foo/bar) -> parent/bar
(gun, /foo/bar) -> parent/gun
(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
(self,* paths )[源代码] ¶向配置包含目录添加路径。
将给定的路径序列添加到include_dirs列表的开头。该列表将对当前软件包的所有扩展模块可见。
add_headers
(self,* files )[源代码] ¶将可安装的标题添加到配置。
将给定的文件序列添加到标题列表的开头。默认情况下,头文件将安装在<python-include> / <self.name.replace('。','/')> /目录下。如果文件项是元组,则其第一个参数指定相对于<python-include>路径的实际安装位置。
参数可以是:
2序列(<includedir后缀>,<头文件的路径>)
头文件的路径,其中python includedir后缀将默认为程序包名称。
add_extension
(self,name,sources,** kw )[source] ¶在配置中添加扩展名。
创建扩展实例并将其添加到ext_modules列表。此方法还采用以下可选关键字参数,这些参数会传递给Extension构造函数。
扩展名
来源清单。源列表可能包含函数(称为源生成器),这些函数必须将扩展实例和构建目录作为输入,并返回源文件或源文件列表或“无”。如果返回None,则不生成任何源。如果扩展实例在处理完所有源生成器后没有源,则不会构建扩展模块。
依赖列表包含扩展模块源所依赖的文件或目录的路径。如果从属列表中的任何路径都比扩展模块新,则将重建该模块。
关键字的dict或字典的列表。
笔记
self.paths(…)方法应用于可能包含路径的所有列表。
add_library
(self,name,sources,** build_info )[source] ¶将库添加到配置。
扩展名。
来源清单。源列表可能包含函数(称为源生成器),这些函数必须将扩展实例和构建目录作为输入,并返回源文件或源文件列表或“无”。如果返回None,则不生成任何源。如果扩展实例在处理完所有源生成器后没有源,则不会构建扩展模块。
允许使用以下密钥:
依靠
巨集
include_dirs
extra_compiler_args
extra_f77_compile_args
extra_f90_compile_args
f2py_options
语言
add_installed_library
(self,name,sources,install_dir,build_info = None )[source] ¶与add_library类似,但是已安装指定的库。
与C一起使用的大多数C库distutils
仅用于构建python扩展,但是将安装通过此方法构建的库,以便第三方程序包可以重用它们。
安装的库的名称。
库的源文件列表。有关add_library
详细信息,请参见。
相对于当前子软件包的库安装路径。
允许使用以下密钥:
依靠
巨集
include_dirs
extra_compiler_args
extra_f77_compile_args
extra_f90_compile_args
f2py_options
语言
笔记
编码链接到指定C库所需的选项的最佳方法是使用“ libname.ini”文件,并用于get_info
检索所需的选项(add_npy_pkg_config
有关更多信息,请参见)。
add_npy_pkg_config
(self,template,install_dir,subst_dict = None )[源代码] ¶从模板生成并安装npy-pkg配置文件。
从模板生成的配置文件安装在给定的安装目录中,使用subst_dict进行变量替换。
模板的路径,相对于当前包路径。
相对于当前软件包路径,在哪里安装npy-pkg配置文件。
如果提供,则安装时,模板文件中的任何形式的字符串都@key@
将被替换
subst_dict[key]
。安装前缀始终可以通过变量获得@prefix@
,因为从setup.py中获取安装前缀并不容易。
也可以看看
笔记
这对于标准安装和就地构建均有效,即,就地构建
@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”子路径中。
与numpy distutils交叉编译时,可能有必要使用修改后的npy-pkg-config文件。使用默认/生成的文件将与主机库(即libnpymath.a)链接。对于交叉编译,您当然需要在使用主机Python安装时链接目标库。
您可以复制numpy / core / lib / npy-pkg-config目录,将pkgdir值添加到.ini文件,并设置NPY_PKG_CONFIG_PATH环境变量以指向带有修改后的npy-pkg-config文件的目录。
修改了示例npymath.ini以进行交叉编译:
[meta]
Name=npymath
Description=Portable, core math library implementing C99 standard
Version=0.1
[variables]
pkgname=numpy.core
pkgdir=/build/arm-linux-gnueabi/sysroot/usr/lib/python3.7/site-packages/numpy/core
prefix=${pkgdir}
libdir=${prefix}/lib
includedir=${prefix}/include
[default]
Libs=-L${libdir} -lnpymath
Cflags=-I${includedir}
Requires=mlib
[msvc]
Libs=/LIBPATH:${libdir} npymath.lib
Cflags=/INCLUDE:${includedir}
Requires=mlib
paths
(self,* paths,** kws )[源代码] ¶将glob应用于路径,并在需要时添加local_path。
将glob.glob(…)应用于序列中的每个路径(如果需要),并在需要时预先添加local_path。因为这是在所有源列表上调用的,所以这允许在扩展模块,库和脚本的源列表中指定通配符,并允许路径名相对于源目录。
have_f77c
(自我)[来源] ¶检查Fortran 77编译器的可用性。
在源生成函数中使用它来确保安装分发实例已初始化。
笔记
如果有可用的Fortran 77编译器,则为true(因为可以成功编译简单的Fortran 77代码)。
have_f90c
(自我)[来源] ¶检查Fortran 90编译器的可用性。
在源生成函数中使用它来确保安装分发实例已初始化。
笔记
如果有Fortran 90编译器可用,则为true(因为可以成功编译简单的Fortran 90代码)
get_version
(self,version_file = None,version_variable = None )[源代码] ¶尝试获取软件包的版本字符串。
返回当前软件包的版本字符串,如果无法检测到版本信息,则返回None。
笔记
此方法扫描名为__version __。py,<packagename> _version.py,version.py和__svn_version__.py的文件中的字符串变量version,__ version__和<packagename> _version,直到找到版本号。
make_svn_version_py
(self,delete = True )[源代码] ¶将数据函数附加到data_files列表,该列表将生成__svn_version__.py文件到当前程序包目录。
从SVN版本号生成软件包__svn_version__.py文件,在python退出后将被删除,但在执行sdist等命令时可用。
笔记
如果以前存在__svn_version__.py,则不执行任何操作。
这旨在用于SVN信息库中的源目录。
常规的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机制numpy.distutils
。此机制基于包含所有选项的.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
通常,文件需要在构建期间生成,因为它只需要一些在构建时就已知的信息(例如前缀)。如果使用Configuration
方法add_npy_pkg_config,这通常是自动的。假设我们有一个模板文件foo.ini.in,如下所示:
[meta]
Name: foo
Version: @[email protected]
Description: foo library
[variables]
prefix = @[email protected]
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很难获得此前缀)。也可以使用get_npy_pkg_dir
函数返回的路径将npy-pkg-config文件安装在与numpy相同的位置
。
信息很容易从get_info
函数中
检索numpy.distutils.misc_util
:
>>> info = get_info('npymath')
>>> config.add_extension('foo', sources=['foo.c'], extra_info=**info)
查找.ini文件的路径的附加列表可以分配给get_info
。
.src
文件¶NumPy distutils支持自动转换名为<somefile> .src的源文件。此功能可用于维护非常相似的代码块,仅需在块之间进行简单更改即可。在安装程序的构建阶段,如果遇到名为<somefile> .src的模板文件,则将从模板中构建一个名为<somefile>的新文件,并将其放置在构建目录中以供使用。支持两种形式的模板转换。第一种形式出现在名为<file> .ext.src的文件中,其中ext是公认的Fortran扩展名(f,f90,f95,f77,用于ftn,pyf)。第二种形式用于所有其他情况。请参阅使用模板转换.src文件。