misc_util¶

classnumpy.distutils.misc_util.Configuration(package_name=None,parent_name=None,top_path=None,package_path=None,**attrs)[source]¶

Construct a configuration instance for the given package name. Ifparent_name is not None, then construct the package as asub-package of theparent_name package. Iftop_path andpackage_path are None then they are assumed equal tothe path of the file this instance was created in. The setup.pyfiles in the numpy distribution are good examples of how to usetheConfiguration instance.

todict()[source]¶

Return a dictionary compatible with the keyword arguments of distutilssetup function.

Examples

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

get_distribution()[source]¶

Return the distutils distribution object for self.

get_subpackage(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. ‘*’ insubpackage_name is handled as a wildcard. subpackage_path:str If None, then the path is assumed to be the local path plus thesubpackage_name. If a setup.py file is not found in thesubpackage_path, then a default configuration is used. parent_name:str Parent name.

add_subpackage(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 apackage.

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

add_data_files(*files)[source]¶

Add data files to configuration data_files.

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 defaultsto package dir.

Notes

The form of each element of the files sequence is very flexibleallowing many combinations of where to get the files from the packageand where they should ultimately be installed on the system. The mostbasic usage is for an element of the files argument sequence to be asimple filename. This will cause that file from the local path to beinstalled to the installation path of the self.name package (packagepath). The file argument can also be a relative path in which case theentire relative path will be installed into the package directory.Finally, the file can be an absolute path name in which case the filewill be found at the absolute path name but installed to the packagepath.

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

Rules for installation paths:

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

An additional feature is that the path to a data-file can actually bea function that takes no arguments and returns the actual path(s) tothe data-files. This is useful when the data files are generated whilebuilding 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')

will install these data files to:

<packageinstalldirectory>/foo.datfun/gun.datnun/pun.datsun.datbar/car.datcan.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’).

add_data_dir(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 beinstalled (and distributed). The data_path can be either a relativepath-name, or an absolute path-name, or a 2-tuple where the firstargument shows where in the install directory the data directoryshould be installed to.

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 defaultsto package dir.

Notes

Rules for installation paths:

foo/bar->(foo/bar,foo/bar)->parent/foo/bar(gun,foo/bar)->parent/gunfoo/*->(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 andfun/bar/car.dat:

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

Will install data-files to the locations:

<packageinstalldirectory>/fun/foo.datbar/car.datsun/foo.datbar/car.datgun/foo.datcar.dat

add_include_dirs(*paths)[source]¶

Add paths to configuration include directories.

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

add_headers(*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 filesis a tuple, then its first argument specifies the actual installationlocation 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 willdefault to package name.

add_extension(name,sources,**kw)[source]¶

Add extension to configuration.

Create and add an Extension instance to the ext_modules list. Thismethod also takes the following optional keyword arguments that arepassed on to the Extension constructor.

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 instanceand a build directory as inputs and return a source file or list ofsource files or None. If None is returned then no sources aregenerated. If the Extension instance has no sources afterprocessing all source generators, then no extension module isbuilt. 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 thesources of the extension module depend on. If any path in thedepends list is newer than the extension module, then the modulewill be rebuilt. language : f2py_options : module_dirs : extra_info:dict or list dict or list of dict of keywords to be appended to keywords.

Notes

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

add_library(name,sources,**build_info)[source]¶

Add library to configuration.

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 instanceand a build directory as inputs and return a source file or list ofsource files or None. If None is returned then no sources aregenerated. If the Extension instance has no sources afterprocessing all source generators, then no extension module isbuilt. 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

add_scripts(*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.

add_installed_library(name,sources,install_dir,build_info=None)[source]¶

Similar to add_library, but the specified library is installed.

Most C libraries used withdistutils are only used to build pythonextensions, but libraries built through this method will be installedso that they can be reused by third-party packages.

Parameters:	name:str Name of the installed library. sources:sequence List of the library’s source files. Seeadd_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

See also

add_library,add_npy_pkg_config,get_info

Notes

The best way to encode the options required to link against the specifiedC libraries is to use a “libname.ini” file, and useget_info toretrieve the required options (seeadd_npy_pkg_config for moreinformation).

add_npy_pkg_config(template,install_dir,subst_dict=None)[source]¶

Generate and install a npy-pkg config file from a template.

The config file generated fromtemplate is installed in thegiven install directory, usingsubst_dict for variable substitution.

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 currentpackage path. subst_dict:dict, optional If given, any string of the form@key@ will be replaced bysubst_dict[key] in the template file when installed. The installprefix is always available through the variable@prefix@, since theinstall prefix is not easy to get reliably from setup.py.

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.0Description=dummydescription[default]Cflags=-I@prefix@/includeLibs=

The generated file will have the following content:

[meta]Name=barVersion=1.0Description=dummydescription[default]Cflags=-Iprefix_dir/includeLibs=

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

paths(*paths,**kws)[source]¶

Apply glob to paths and prepend local_path if needed.

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

get_config_cmd()[source]¶

Returns the numpy.distutils config command instance.

get_build_temp_dir()[source]¶

Return a path to a temporary directory where temporary files should beplaced.

have_f77c()[source]¶

Check for availability of Fortran 77 compiler.

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

Notes

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

have_f90c()[source]¶

Check for availability of Fortran 90 compiler.

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

Notes

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

get_version(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 versioninformation 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.

make_svn_version_py(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 availablewhen sdist, etc commands are executed.

Notes

If __svn_version__.py existed before, nothing is done.

This isintended for working with source directories that are in an SVNrepository.

make_config_py(name='__config__')[source]¶

Generate package __config__.py file containing system_infoinformation used during building the package.

This file is installed to thepackage installation directory.

get_info(*names)[source]¶

Get resources information.

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

Other modules¶

npy-pkg-config files¶

To make the necessary build options available to third parties, you could usethenpy-pkg-config mechanism implemented innumpy.distutils. This mechanism isbased on a .ini file which contains all the options. A .ini file is verysimilar to .pc files as used by the pkg-config unix utility:

[meta]Name: fooVersion: 1.0Description: foo library[variables]prefix = /home/user/locallibdir = ${prefix}/libincludedir = ${prefix}/include[default]cflags = -I${includedir}libs = -L${libdir} -lfoo

Generally, the file needs to be generated during the build, since it needs someinformation known at build time only (e.g. prefix). This is mostly automatic ifone uses theConfiguration methodadd_npy_pkg_config. Assuming we have atemplate file foo.ini.in as follows:

[meta]Name: fooVersion: @version@Description: foo library[variables]prefix = @prefix@libdir = ${prefix}/libincludedir = ${prefix}/include[default]cflags = -I${includedir}libs = -L${libdir} -lfoo

and the following code in 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)

This will install the file foo.ini into the directory package_dir/lib, and thefoo.ini file will be generated from foo.ini.in, where each@version@ will bereplaced bysubst_dict['version']. The dictionary has an additional prefixsubstitution rule automatically added, which contains the install prefix (sincethis is not easy to get from setup.py). npy-pkg-config files can also beinstalled at the same location as used for numpy, using the path returned fromget_npy_pkg_dir function.

Reusing a C library from another package¶

Info are easily retrieved from theget_info function innumpy.distutils.misc_util:

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

An additional list of paths to look for .ini files can be given toget_info.

Fortran files¶

This template converter will replicate allfunction andsubroutine blocks in the file with names that contain ‘<…>’according to the rules in ‘<…>’. The number of comma-separated wordsin ‘<…>’ determines the number of times the block is repeated. Whatthese words are indicates what that repeat rule, ‘<…>’, should bereplaced with in each block. All of the repeat rules in a block mustcontain the same number of comma-separated words indicating the numberof times that block should be repeated. If the word in the repeat ruleneeds a comma, leftarrow, or rightarrow, then prepend it with abackslash ‘ ‘. If a word in the repeat rule matches ‘ \<index>’ thenit will be replaced with the <index>-th word in the same repeatspecification. There are two forms for the repeat rule: named andshort.

Other files¶

Non-Fortran files use a separate syntax for defining template blocksthat should be repeated using a variable expansion similar to thenamed repeat rules of the Fortran-specific repeats. The template rulesfor these files are:

1. “/**begin repeat “on a line by itself marks the beginning ofa segment that should be repeated.
2. Named variable expansions are defined using #name=item1, item2, item3,…, itemN# and placed on successive lines. These variables arereplaced in each repeat block with corresponding word. All namedvariables in the same repeat block must define the same number ofwords.
3. In specifying the repeat rule for a named variable, item*N is short-hand for item, item, …, item repeated N times. In addition,parenthesis in combination with *N can be used for grouping severalitems that should be repeated. Thus, #name=(item1, item2)*4# isequivalent to #name=item1, item2, item1, item2, item1, item2, item1,item2#
4. “*/ “on a line by itself marks the end of the variable expansionnaming. The next line is the first line that will be repeated usingthe named rules.
5. Inside the block to be repeated, the variables that should be expandedare specified as @name@.
6. “/**end repeat**/ “on a line by itself marks the previous lineas the last line of the block to be repeated.