numpy.distutils.misc_util.Configuration

class documentation

class Configuration: (source)

Undocumented

Method	`__init__`	Construct configuration instance of a package.
Method	`__str__`	Undocumented
Method	`add_data_dir`	Recursively add files under data_path to data_files list.
Method	`add_data_files`	Add data files to configuration data_files.
Method	`add_define_macros`	Add define macros to configuration
Method	`add_extension`	Add extension to configuration.
Method	`add_headers`	Add installable headers to configuration.
Method	`add_include_dirs`	Add paths to configuration include directories.
Method	`add_installed_library`	Similar to add_library, but the specified library is installed.
Method	`add_library`	Add library to configuration.
Method	`add_npy_pkg_config`	Generate and install a npy-pkg config file from a template.
Method	`add_scripts`	Add scripts to configuration.
Method	`add_subpackage`	Add a sub-package to the current Configuration instance.
Method	`append_to`	Append libraries, include_dirs to extension or library item.
Method	`dict_append`	Undocumented
Method	`get_build_temp_dir`	Return a path to a temporary directory where temporary files should be placed.
Method	`get_config_cmd`	Returns the numpy.distutils config command instance.
Method	`get_distribution`	Return the distutils distribution object for self.
Method	`get_info`	Get resources information.
Method	`get_subpackage`	Return list of subpackage configurations.
Method	`get_version`	Try to get version string of a package.
Method	`have_f77c`	Check for availability of Fortran 77 compiler.
Method	`have_f90c`	Check for availability of Fortran 90 compiler.
Method	`info`	Undocumented
Method	`make_config_py`	Generate package __config__.py file containing system_info information used during building the package.
Method	`make_hg_version_py`	Appends a data function to the data_files list that will generate __hg_version__.py file to the current package directory.
Method	`make_svn_version_py`	Appends a data function to the data_files list that will generate __svn_version__.py file to the current package directory.
Method	`paths`	Apply glob to paths and prepend local_path if needed.
Method	`set_options`	Configure Configuration instance.
Method	`todict`	Return a dictionary compatible with the keyword arguments of distutils setup function.
Method	`warn`	Undocumented
Class Variable	`numpy_include_dirs`	Undocumented
Instance Variable	`dict_keys`	Undocumented
Instance Variable	`extra_keys`	Undocumented
Instance Variable	`list_keys`	Undocumented
Instance Variable	`local_path`	Undocumented
Instance Variable	`name`	Undocumented
Instance Variable	`options`	Undocumented
Instance Variable	`package_path`	Undocumented
Instance Variable	`path_in_package`	Undocumented
Instance Variable	`setup_name`	Undocumented
Instance Variable	`top_path`	Undocumented
Instance Variable	`version`	Undocumented
Method	`_add_library`	Common implementation for add_library and add_installed_library. Do not use directly
Method	`_fix_paths_dict`	Undocumented
Method	`_get_configuration_from_setup_py`	Undocumented
Method	`_get_hg_revision`	Return path's Mercurial revision number.
Method	`_get_svn_revision`	Return path's SVN revision number.
Method	`_optimize_data_files`	Undocumented
Method	`_wildcard_get_subpackage`	Undocumented
Class Variable	`_dict_keys`	Undocumented
Class Variable	`_extra_keys`	Undocumented
Class Variable	`_list_keys`	Undocumented

def __init__(self, package_name=None, parent_name=None, top_path=None, package_path=None, caller_level=1, setup_name='setup.py', **attrs): (source) ¶

Construct configuration instance of a package.

package_name -- name of the package: Ex.: 'distutils'
parent_name -- name of the parent package: Ex.: 'numpy'
top_path -- directory of the toplevel package: Ex.: the directory where the numpy package source sits
package_path -- directory of package. Will be computed by magic from the: directory of the caller module if not specified Ex.: the directory where numpy.distutils is

caller_level -- frame level to caller namespace, internal parameter.

def __str__(self): (source) ¶

Undocumented

def add_data_dir(self, data_path): (source) ¶

Recursively add files under data_path to data_files list.

Recursively add files under data_path to the list of data_files to be installed (and distributed). The data_path can be either a relative path-name, or an absolute path-name, or a 2-tuple where the first argument shows where in the install directory the data directory should be installed to.

Notes

Rules for installation paths:

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

Examples

For example suppose the source directory contains fun/foo.dat and fun/bar/car.dat:

>>> self.add_data_dir('fun')                       #doctest: +SKIP
>>> self.add_data_dir(('sun', 'fun'))              #doctest: +SKIP
>>> self.add_data_dir(('gun', '/full/path/to/fun'))#doctest: +SKIP

Will install data-files to the locations:

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

Parameters

data_path:seq or str

Argument can be either

2-sequence (<datadir suffix>, <path to data directory>)

path to data directory where python datadir suffix defaults to package dir.

def add_data_files(self, *files): (source) ¶

Add data files to configuration data_files.

Notes

The form of each element of the files sequence is very flexible allowing many combinations of where to get the files from the package and where they should ultimately be installed on the system. The most basic usage is for an element of the files argument sequence to be a simple filename. This will cause that file from the local path to be installed to the installation path of the self.name package (package path). The file argument can also be a relative path in which case the entire relative path will be installed into the package directory. Finally, the file can be an absolute path name in which case the file will be found at the absolute path name but installed to the package path.

This basic behavior can be augmented by passing a 2-tuple in as the file argument. The first element of the tuple should specify the relative path (under the package install directory) where the remaining sequence of files should be installed to (it has nothing to do with the file-names in the source distribution). The second element of the tuple is the sequence of files that should be installed. The files in this sequence can be filenames, relative paths, or absolute paths. For absolute paths the file will be installed in the top-level package installation directory (regardless of the first argument). Filenames and relative path names will be installed in the package install directory under the path name given as the first element of the tuple.

Rules for installation paths:

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.txt

foo/*.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

An additional feature is that the path to a data-file can actually be a function that takes no arguments and returns the actual path(s) to the data-files. This is useful when the data files are generated while building the package.

Examples

Add files to the list of data_files to be included with the package.

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

will install these data files to:

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

where <package install directory> is the package (or sub-package) directory such as '/usr/lib/python2.4/site-packages/mypackage' ('C: Python2.4 Lib site-packages mypackage') or '/usr/lib/python2.4/site- packages/mypackage/mysubpackage' ('C: Python2.4 Lib site-packages mypackage mysubpackage').

Parameters

*files:sequence

Argument(s) can be either

2-sequence (<datadir prefix>,<path to data file(s)>)

paths to data files where python datadir prefix defaults to package dir.

def add_define_macros(self, macros): (source) ¶

Add define macros to configuration

Add the given sequence of macro name and value duples to the beginning of the define_macros list This list will be visible to all extension modules of the current package.

def add_extension(self, name, sources, **kw): (source) ¶

Add extension to configuration.

Create and add an Extension instance to the ext_modules list. This method also takes the following optional keyword arguments that are passed on to the Extension constructor.

Notes

The self.paths(...) method is applied to all lists that may contain paths.

Parameters
name:`str`	name of the extension
sources:`seq`	list of the sources. The list of sources may contain functions (called source generators) which must take an extension instance and a build directory as inputs and return a source file or list of source files or None. If None is returned then no sources are generated. If the Extension instance has no sources after processing all source generators, then no extension module is built.
**kw	Undocumented
extra_info:`dict` or `list`	dict or list of dict of keywords to be appended to keywords.
include_dirs
define_macros
undef_macros
library_dirs
libraries
runtime_library_dirs
extra_objects
extra_compile_args
extra_link_args
extra_f77_compile_args
extra_f90_compile_args
export_symbols
swig_opts
depends	The depends list contains paths to files or directories that the sources of the extension module depend on. If any path in the depends list is newer than the extension module, then the module will be rebuilt.
language
f2py_options
module_dirs

def add_headers(self, *files): (source) ¶

Add installable headers to configuration.

Add the given sequence of files to the beginning of the headers list. By default, headers will be installed under <python- include>/<self.name.replace('.','/')>/ directory. If an item of files is a tuple, then its first argument specifies the actual installation location relative to the <python-include> path.

Parameters

*files:str or seq

Argument(s) can be either:

2-sequence (<includedir suffix>,<path to header file(s)>)

path(s) to header file(s) where python includedir suffix will default to package name.

def add_include_dirs(self, *paths): (source) ¶

Add paths to configuration include directories.

Add the given sequence of paths to the beginning of the include_dirs list. This list will be visible to all extension modules of the current package.

def add_installed_library(self, name, sources, install_dir, build_info=None): (source) ¶

Similar to add_library, but the specified library is installed.

Most C libraries used with distutils are only used to build python extensions, but libraries built through this method will be installed so that they can be reused by third-party packages.

See Also

add_installed_library, get_info

Notes

This works for both standard installs and in-place builds, i.e. the @prefix@ refer to the source directory for in-place builds.

Examples

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

Assuming the foo.ini.in file has the following content:

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

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

The generated file will have the following content:

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

[default]
Cflags=-Iprefix_dir/include
Libs=

and will be installed as foo.ini in the 'lib' subpath.

When cross-compiling with numpy distutils, it might be necessary to use modified npy-pkg-config files. Using the default/generated files will link with the host libraries (i.e. libnpymath.a). For cross-compilation you of-course need to link with target libraries, while using the host Python installation.

You can copy out the numpy/core/lib/npy-pkg-config directory, add a pkgdir value to the .ini files and set NPY_PKG_CONFIG_PATH environment variable to point to the directory with the modified npy-pkg-config files.

Example npymath.ini modified for cross-compilation:

[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

Parameters
template:`str`	The path of the template, relatively to the current package path.
install_dir:`str`	Where to install the npy-pkg config file, relatively to the current package path.
subst_dict:`dict`, optional	If given, any string of the form `@key@` will be replaced by `subst_dict[key]` in the template file when installed. The install prefix is always available through the variable `@prefix@`, since the install prefix is not easy to get reliably from setup.py.

def add_scripts(self, *files): (source) ¶

Add scripts to configuration.

Add the sequence of files to the beginning of the scripts list. Scripts will be installed under the <prefix>/bin/ directory.

def add_subpackage(self, subpackage_name, subpackage_path=None, standalone=False): (source) ¶

Add a sub-package to the current Configuration instance.

This is useful in a setup.py script for adding sub-packages to a package.

Parameters
subpackage_name:`str`	name of the subpackage
subpackage_path:`str`	if given, the subpackage path such as the subpackage is in subpackage_path / subpackage_name. If None,the subpackage is assumed to be located in the local path / subpackage_name.
standalone:`bool`

def append_to(self, extlib): (source) ¶

Append libraries, include_dirs to extension or library item.

def dict_append(self, **dict): (source) ¶

Undocumented

def get_build_temp_dir(self): (source) ¶

Return a path to a temporary directory where temporary files should be placed.

def get_config_cmd(self): (source) ¶

Returns the numpy.distutils config command instance.

def get_distribution(self): (source) ¶

Return the distutils distribution object for self.

def get_info(self, *names): (source) ¶

Get resources information.

Return information (from system_info.get_info) for all of the names in the argument list in a single dictionary.

def get_subpackage(self, subpackage_name, subpackage_path=None, parent_name=None, caller_level=1): (source) ¶

Return list of subpackage configurations.

Parameters
subpackage_name:`str` or `None`	Name of the subpackage to get the configuration. '*' in subpackage_name is handled as a wildcard.
subpackage_path:`str`	If None, then the path is assumed to be the local path plus the subpackage_name. If a setup.py file is not found in the subpackage_path, then a default configuration is used.
parent_name:`str`	Parent name.
caller_level	Undocumented

def get_version(self, version_file=None, version_variable=None): (source) ¶

Try to get version string of a package.

Return a version string of the current package or None if the version information could not be detected.

Notes

This method scans files named __version__.py, <packagename>_version.py, version.py, and __svn_version__.py for string variables version, __version__, and <packagename>_version, until a version number is found.

def have_f77c(self): (source) ¶

Check for availability of Fortran 77 compiler.

Use it inside source generating function to ensure that setup distribution instance has been initialized.

Notes

True if a Fortran 77 compiler is available (because a simple Fortran 77 code was able to be compiled successfully).

def have_f90c(self): (source) ¶

Check for availability of Fortran 90 compiler.

Use it inside source generating function to ensure that setup distribution instance has been initialized.

Notes

True if a Fortran 90 compiler is available (because a simple Fortran 90 code was able to be compiled successfully)

def info(self, message): (source) ¶

Undocumented

def make_config_py(self, name='__config__'): (source) ¶

Generate package __config__.py file containing system_info information used during building the package.

This file is installed to the package installation directory.

def make_hg_version_py(self, delete=True): (source) ¶

Appends a data function to the data_files list that will generate __hg_version__.py file to the current package directory.

Generate package __hg_version__.py file from Mercurial revision, it will be removed after python exits but will be available when sdist, etc commands are executed.

Notes

If __hg_version__.py existed before, nothing is done.

This is intended for working with source directories that are in an Mercurial repository.

def make_svn_version_py(self, delete=True): (source) ¶

Appends a data function to the data_files list that will generate __svn_version__.py file to the current package directory.

Generate package __svn_version__.py file from SVN revision number, it will be removed after python exits but will be available when sdist, etc commands are executed.

Notes

If __svn_version__.py existed before, nothing is done.

This is intended for working with source directories that are in an SVN repository.

def paths(self, *paths, **kws): (source) ¶

Apply glob to paths and prepend local_path if needed.

Applies glob.glob(...) to each path in the sequence (if needed) and pre-pends the local_path if needed. Because this is called on all source lists, this allows wildcard characters to be specified in lists of sources for extension modules and libraries and scripts and allows path-names be relative to the source directory.

def set_options(self, **options): (source) ¶

Configure Configuration instance.

The following options are available:

ignore_setup_xxx_py
assume_default_configuration
delegate_options_to_subpackages
quiet

def todict(self): (source) ¶

Return a dictionary compatible with the keyword arguments of distutils setup function.

Examples

>>> setup(**config.todict())                           #doctest: +SKIP

def warn(self, message): (source) ¶

Undocumented

numpy_include_dirs: list = (source) ¶

Undocumented

dict_keys = (source) ¶

Undocumented

extra_keys = (source) ¶

Undocumented

list_keys = (source) ¶

Undocumented

local_path: str = (source) ¶

Undocumented

name = (source) ¶

Undocumented

options = (source) ¶

Undocumented

package_path = (source) ¶

Undocumented

path_in_package = (source) ¶

Undocumented

setup_name = (source) ¶

Undocumented

top_path = (source) ¶

Undocumented

version = (source) ¶

Undocumented

def _add_library(self, name, sources, install_dir, build_info): (source) ¶

Common implementation for add_library and add_installed_library. Do not use directly

def _fix_paths_dict(self, kw): (source) ¶

Undocumented

def _get_configuration_from_setup_py(self, setup_py, subpackage_name, subpackage_path, parent_name, caller_level=1): (source) ¶

Undocumented

def _get_hg_revision(self, path): (source) ¶

Return path's Mercurial revision number.

def _get_svn_revision(self, path): (source) ¶

Return path's SVN revision number.

def _optimize_data_files(self): (source) ¶

Undocumented

def _wildcard_get_subpackage(self, subpackage_name, parent_name, caller_level=1): (source) ¶

Undocumented

_dict_keys: list[str] = (source) ¶

Undocumented

_extra_keys: list[str] = (source) ¶

Undocumented

_list_keys: list[str] = (source) ¶

Undocumented

Parameters
name:`str`	Name of the extension.
sources:`sequence`	List of the sources. The list of sources may contain functions (called source generators) which must take an extension instance and a build directory as inputs and return a source file or list of source files or None. If None is returned then no sources are generated. If the Extension instance has no sources after processing all source generators, then no extension module is built.
*build_info:`dict`, optional*	The following keys are allowed: depends macros include_dirs extra_compiler_args extra_f77_compile_args extra_f90_compile_args f2py_options language

Parameters
name:`str`	Name of the installed library.
sources:`sequence`	List of the library's source files. See `add_library` for details.
install_dir:`str`	Path to install the library, relative to the current sub-package.
build_info:`dict`, optional	The following keys are allowed: depends macros include_dirs extra_compiler_args extra_f77_compile_args extra_f90_compile_args f2py_options language
Returns
`None`	Undocumented