Python API¶

This section includes information for using the Python API of bob.extension.

Summary¶

Core Functionality¶

`bob.extension.boost`([requirement])	A class for capturing configuration information from boost
`bob.extension.build_ext`(dist, **kw)	Compile the C++ :py:class`Library`'s using CMake, and the python extensions afterwards
`bob.extension.check_packages`(packages)	Checks if the requirements for the given packages are satisfied.
`bob.extension.CMakeListsGenerator`(name, ...)	Generates a CMakeLists.txt file for the given sources, include directories and libraries.
`bob.extension.construct_search_paths`([...])	Constructs a list of candidate paths to search for.
`bob.extension.DEFAULT_PREFIXES`	The list common places to search for library-related files.
`bob.extension.Extension`(name, sources, **kwargs)	Extension building with pkg-config packages.
`bob.extension.find_executable`(name[, ...])	Finds an executable on the file system.
`bob.extension.find_library`(name[, version, ...])	Finds a library file on the file system.
`bob.extension.generate_self_macros`(extname, ...)	Generates standard macros with library, module names and prefix
`bob.extension.get_bob_libraries`(bob_packages)	Returns a list of include directories, libraries and library directories for the given bob libraries.
`bob.extension.get_config`([package, ...])	Returns a string containing the configuration information for the given `package` name.
`bob.extension.get_full_libname`(name[, path, ...])	Generates the name of the library from the given name, path and version.
`bob.extension.Library`(name, sources, version)	A class to compile a pure C++ code library used within and outside an extension using CMake.
`bob.extension.load_bob_library`(name, _file_)	Loads the bob Library for the given package name in the given version (if given).
`bob.extension.normalize_requirements`(...)	Normalizes the requirements keeping only the most tight
`bob.extension.pkgconfig`(name[, paths])	A class for capturing configuration information from pkg-config
`bob.extension.rc`	The content of the global configuration file loaded as a dictionary.
`bob.extension.rc_context`(dict)	A context manager for bob.extension.rc.
`bob.extension.reorganize_isystem`(args)	Re-organizes the -isystem includes so that more specific paths come first
`bob.extension.uniq`(seq[, idfun])	Very fast, order preserving uniq function
`bob.extension.uniq_paths`(seq)	Uniq'fy a list of paths taking into consideration their real paths
`bob.extension.download.get_file`(filename, urls)	Downloads a file from a given a list of URLS. In case the first link fails, the following ones will be tried. The downloaded files will be saved in `~/bob_data` by default. You may change the location of this folder using::.

Utilities¶

`bob.extension.utils.egrep`(filename, expression)	Runs grep for a given expression on each line of the file
`bob.extension.utils.find_file`(name[, ...])	Finds a generic file on the file system.
`bob.extension.utils.find_header`(name[, ...])	Finds a header file on the file system.
`bob.extension.utils.find_packages`([directories])	This function replaces the `find_packages` command from `setuptools` to search for packages only in the given directories.
`bob.extension.utils.link_documentation`([...])	Generates a list of documented packages on our documentation server for the packages read from the "requirements.txt" file and the given list of additional packages.
`bob.extension.utils.load_requirements`([f])	Loads the contents of requirements.txt on the given path.
`bob.extension.download.get_file`(filename, urls)	Downloads a file from a given a list of URLS. In case the first link fails, the following ones will be tried. The downloaded files will be saved in `~/bob_data` by default. You may change the location of this folder using::.
`bob.extension.download.search_file`(...)	Search for files either in a file structure, or in a tarball.
`bob.extension.download.list_dir`(base_path[, ...])	Lists the files and folders inside a folder or a tarball.

Configuration¶

`bob.extension.rc_config.ENVNAME`	Name of environment variable to look for an alternative for the RC file
`bob.extension.rc_config.RCFILENAME`	Default name to be used for the RC file to load
`bob.extension.config.load`(paths[, context, ...])	Loads a set of configuration files, in sequence

Scripts¶

`bob.extension.scripts.click_helper.ConfigCommand`(...)	A click.Command that can take options both form command line options and configuration files.
`bob.extension.scripts.click_helper.ResourceOption`([...])	An extended click.Option that automatically loads resources from config files.
`bob.extension.scripts.click_helper.verbosity_option`(...)	Adds a -v/--verbose option to a click command.
`bob.extension.scripts.click_helper.bool_option`(...)	Generic provider for boolean options
`bob.extension.scripts.click_helper.list_float_option`(...)	Get option to get a list of float f
`bob.extension.scripts.click_helper.open_file_mode_option`(...)	Get open mode file option
`bob.extension.scripts.click_helper.AliasedGroup`([...])	Class that handles prefix aliasing for commands
`bob.extension.scripts.click_helper.log_parameters`(...)	Logs the click parameters with the logging module.
`bob.extension.scripts.click_helper.assert_click_runner_result`(result)	Helper for asserting click runner results

Core Functionality¶

A custom build class for Pkg-config based extensions

class bob.extension.CMakeListsGenerator(name, sources, target_directory, version='1.0.0', include_directories=[], system_include_directories=[], libraries=[], library_directories=[], macros=[])[source]¶

Bases: object

Generates a CMakeLists.txt file for the given sources, include directories and libraries.

generate(source_directory, build_directory)[source]¶: Generates the CMakeLists.txt file in the given directory.

bob.extension.DEFAULT_PREFIXES = ['/opt/local', '/usr/local', '/usr']¶: The list common places to search for library-related files.

bob.extension.DistutilsExtension¶: alias of setuptools.extension.Extension

class bob.extension.Extension(name, sources, **kwargs)[source]¶

Bases: setuptools.extension.Extension

Extension building with pkg-config packages.

See the documentation for distutils.extension.Extension for more details on input parameters.

class bob.extension.Library(name, sources, version, bob_packages=[], packages=[], boost_modules=[], include_dirs=[], system_include_dirs=[], libraries=[], library_dirs=[], define_macros=[])[source]¶

Bases: bob.extension.Extension

A class to compile a pure C++ code library used within and outside an extension using CMake.

compile(build_directory, compiler=None, stdout=None)[source]¶: This function will automatically create a CMakeLists.txt file in the package_directory including the required information. Afterwards, the library is built using CMake in the given build_directory. The build type is automatically taken from the debug option in the buildout.cfg. To change the compiler, use the compiler parameter.

class bob.extension.boost(requirement='')[source]¶

Bases: object

A class for capturing configuration information from boost

Example usage:

>>> from bob.extension import boost
>>> pkg = boost('>= 1.35')
>>> pkg.include_directory
'...'
>>> pkg.version
'...'

You can also use this class to retrieve information about installed Boost libraries and link information:

>>> from bob.extension import boost
>>> pkg = boost('>= 1.35')
>>> pkg.libconfig(['python', 'system'])
(...)

libconfig(modules, only_static=False, templates=['boost_%(name)s-mt-%(py)s', 'boost_%(name)s-%(py)s', 'boost_%(name)s%(pyv)s', 'boost_%(name)s-mt', 'boost_%(name)s'])[source]¶

Returns a tuple containing the library configuration for requested modules.

This function respects the path location where the include files for Boost are installed.

Parameters:

modules (list of strings)

A list of string specifying the requested libraries to search for. For example, to search for libboost_mpi.so, pass only mpi.

static (bool)

A boolean, indicating if we should try only to search for static versions of the libraries. If not set, any would do.

templates (list of template strings)

A list that defines in which order to search for libraries on the default search path, defined by self.include_directory. Tune this list if you have compiled specific versions of Boost with support to multi-threading (-mt), debug (-g), STLPORT (-p) or required to insert compiler, the underlying thread API used or your own namespace.

Here are the keywords you can use:

%(name)s: resolves to the module name you are searching for
%(ver)s: resolves to the current boost version string (e.g. '1.50.0')
%(py)s: resolves to the string 'pyXY' where XY represent the major and minor versions of the current python interpreter.
%(pyv)s: resolves to the string 'XY' where XY represent the major and minor versions of the current python interpreter.

Example templates:

'boost_%(name)s-mt'
'boost_%(name)s'
'boost_%(name)s-gcc43-%(ver)s'

Returns:

directories (list of strings): A list of directories indicating where the libraries are installed
libs (list of strings): A list of strings indicating the names of the libraries you can use

macros()[source]¶

Returns package availability and version number macros

This method returns a python list with 2 macros indicating package availability and a version number, using standard GNU compatible names. Example:

>>> from bob.extension import boost
>>> pkg = boost('>= 1.34')
>>> pkg.macros()
[('HAVE_BOOST', '1')]

class bob.extension.build_ext(dist, **kw)[source]¶

Bases: setuptools.command.build_ext.build_ext

Compile the C++ :py:class`Library`’s using CMake, and the python extensions afterwards

See the documentation for distutils.command.build_ext for more information.

finalize_options()[source]¶

Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place to code option dependencies: if ‘foo’ depends on ‘bar’, then it is safe to set ‘foo’ from ‘bar’ as long as ‘foo’ still has the same value it was assigned in ‘initialize_options()’.

This method must be implemented by all command classes.

run()[source]¶: Iterates through the list of Extension packages and reorders them, so that the Library’s come first

build_extension(ext)[source]¶

Builds the given extension.

When the extension is of type Library, it compiles the library with CMake, otherwise the default compilation mechanism is used. Afterwards, it adds the according library, and the include and library directories of the Library’s, so that other Extensions can find the newly generated lib.

get_ext_filename(fullname)[source]¶: Returns the library path for the given name

bob.extension.check_packages(packages)[source]¶

Checks if the requirements for the given packages are satisfied.

:param list of str: Each representing a requirement that

must be statistfied. Package requirements can be set like this:

"pkg > VERSION"

In this case, the package version should be greater than the given version number. Comparisons are done using distutils.version.LooseVersion. You can use other comparators such as <, <=, >= or ==. If no version number is given, then we only require that the package is installed.

Raises: RuntimeError – in case requirements are not satisfied. This means either not finding a package if no version number is specified or verifying that the package version does not match the required version by the builder.

bob.extension.construct_search_paths(prefixes=None, subpaths=None, suffix=None)[source]¶

Constructs a list of candidate paths to search for.

The list of paths is constructed using the following order of priority:

BOB_PREFIX_PATH environment variable, if set. BOB_PREFIX_PATH can contain several paths divided by os.pathsep.
The paths provided with the prefixes parameter.
The current python executable prefix.
The CONDA_PREFIX environment variable, if set.
DEFAULT_PREFIXES.

Parameters

prefixes ([str], optional) – The list of paths to be added to the results.
subpaths ([str], optional) – A list of subpaths to be appended to each path at the end. For example, if you specify ['foo', 'bar'] for this parameter, then os.path.join(paths[0], 'foo'), os.path.join(paths[0], 'bar'), and so on are added to the returned paths. Globs are accepted in this list and resolved using the function glob.glob().
suffix (str, optional) – suffix will be appended to all paths except prefixes.

Returns

paths – A list of unique and existing paths to be used in your search.

Return type

[str]

bob.extension.find_executable(name, subpaths=None, prefixes=None)[source]¶

Finds an executable on the file system. Returns all candidates.

This method will find all occurrences of a given name on the file system and will return them to the user. It uses construct_search_paths to construct the candidate folders that the executable may exist in accounting automatically for typical executable folder names.

Parameters

name (str) – The name of the file. For example, gcc.
subpaths ([str], optional) – See construct_search_paths
prefixes (str, optional) – See construct_search_paths

Returns

A list of filenames that exist on the filesystem, matching your description.

Return type

[str]

bob.extension.find_library(name, version=None, subpaths=None, prefixes=None, only_static=False)[source]¶

Finds a library file on the file system. Returns all candidates.

This method will find all occurrences of a given name on the file system and will return them to the user. It uses construct_search_paths to construct the candidate folders that the library may exist in accounting automatically for typical library folder names.

Parameters

name (str) – The name of the module to be found. If you’d like to find libz.so, for example, specify "z". For libmath.so, specify "math".
version (str, optional) – The version of the library we are searching for. If not specified, then look only for the default names, such as libz.so and the such.
subpaths (str, optional) – See construct_search_paths
subpaths – See construct_search_paths
only_static (bool, optional) – A boolean, indicating if we should try only to search for static versions of the libraries. If not set, any would do.

Returns

A list of filenames that exist on the filesystem, matching your description.

Return type

[str]

bob.extension.find_system_include_paths()[source]¶

Finds system include paths if the environment variable CC is set

Returns: A list of include paths defined by the compiler
Return type: list

bob.extension.generate_self_macros(extname, version)[source]¶: Generates standard macros with library, module names and prefix

bob.extension.get_bob_libraries(bob_packages)[source]¶: Returns a list of include directories, libraries and library directories for the given bob libraries.

bob.extension.get_config(package='bob.extension', externals=None, api_version=None)[source]¶

Returns a string containing the configuration information for the given package name. By default, it returns the configuration of this package.

This function can be reused by other packages. If these packages have external C or C++ dependencies, the externals dictionary can be specified. Also, if the package provides an API version, it can be specified.

Keyword parameters:

packagestr: The name of the package to get the configuration information from. Usually, the __name__ of the package.
externals{dep: description}: A dictionary of external C or C++ dependencies, with the dep``endent package name as key, and a free ``description as value.
api_versionint (usually in hexadecimal): The API version of the package, if any.

bob.extension.get_full_libname(name, path=None, version=None)[source]¶: Generates the name of the library from the given name, path and version.

bob.extension.load_bob_library(name, _file_)[source]¶

Loads the bob Library for the given package name in the given version (if given). The _file_ parameter is expected to be the __file__ member of the main __init__.py of the package. It is used to determine the directory, where the library should be loaded from.

Keyword parameters

namestring: The name of the bob package to load the library from, e.g. bob.core
_file_string: The __file__ member of the __init__.py file in which the library is loaded.

bob.extension.normalize_requirements(requirements)[source]¶: Normalizes the requirements keeping only the most tight

class bob.extension.pkgconfig(name, paths=None)[source]¶

Bases: object

A class for capturing configuration information from pkg-config

Example usage:

>>> from bob.extension import pkgconfig
>>> blitz = pkgconfig('blitz')
>>> blitz.include_directories()
[...]
>>> blitz.library_directories()
[...]

If the package does not exist, a RuntimeError is raised. All calls to any methods of a pkgconfig object are translated into a subprocess call that queries for that specific information. If pkg-config fails, a RuntimeError is raised.

include_directories()[source]¶

Returns a pre-processed list containing include directories.