instant package

Submodules

instant.build module

This module contains the main part of Instant, the build_module function.

instant.build.arg_strings(x)[source]
instant.build.assert_is_bool(x)[source]
instant.build.assert_is_str(x)[source]
instant.build.assert_is_str_list(x)[source]
instant.build.build_module(modulename=None, source_directory='.', code='', init_code='', additional_definitions='', additional_declarations='', sources=[], wrap_headers=[], local_headers=[], system_headers=[], include_dirs=['.'], library_dirs=[], libraries=[], swigargs=['-c++', '-fcompact', '-O', '-I.', '-small'], swig_include_dirs=[], cppargs=['-O2'], lddargs=[], object_files=[], arrays=[], generate_interface=True, generate_setup=True, cmake_packages=[], signature=None, cache_dir=None)[source]

Generate and compile a module from C/C++ code using SWIG.

The keyword arguments are as follows:
  • B{modulename}: - The name you want for the module.

    If specified, the module will not be cached. If missing, a name will be constructed based on a checksum of the other arguments, and the module will be placed in the global cache. String.

  • B{source_directory}: - The directory where user supplied files reside. The files given in B{sources}, B{wrap_headers}, and B{local_headers} are expected to exist in this directory. String.

  • B{code}: - A string containing C or C++ code to be compiled and wrapped. String.

  • B{init_code}: - Code that should be executed when the Instant module is imported. This code is inserted in the SWIG interface file, and is used for instance for calling C{import_array()} used for the initialization of NumPy arrays. String.

  • B{additional_definitions}: - Additional definitions (typically needed for inheritance) for interface file. These definitions should be given as triple-quoted strings in the case they span multiple lines, and are placed both in the initial block for C/C++ code (C{%{,%}}-block), and the main section of the interface file. String.

  • B{additional_declarations}: - Additional declarations (typically needed for inheritance) for interface file. These declarations should be given as triple-quoted strings in the case they span multiple lines, and are plaves in the main section of the interface file. String.

  • B{sources}: - Source files to compile and link with the module. These files are compiled togehter with the SWIG-generated wrapper file into the final library file. Should reside in directory specified in B{source_directory}. List of strings.

  • B{wrap_headers}: - Local header files that should be wrapped by SWIG. The files specified will be included both in the initial block for C/C++ code (with a C directive) and in the main section of the interface file (with a SWIG directive). Should reside in directory specified in B{source_directory}. List of strings.

  • B{local_headers}: - Local header files required to compile the wrapped code. The files specified will be included in the initial block for C/C++ code (with a C directive). Should reside in directory specified in B{source_directory}. List of strings.

  • B{system_headers}: - System header files required to compile the wrapped code. The files specified will be included in the initial block for C/C++ code (with a C directive). List of strings.

  • B{include_dirs}: - Directories to search for header files for building the extension module. Needs to be absolute path names. List of strings.

  • B{library_dirs}: - Directories to search for libraries (C{-l}) for building the extension module. Needs to be absolute paths. List of strings.

  • B{libraries}: - Libraries needed by the Instant module. The libraries will be linked in from the shared object file. The initial C{-l} is added automatically. List of strings.

  • B{swigargs}: - List of arguments to swig, e.g. C{[“-lpointers.i”]}

    to include the SWIG pointers.i library.

  • B{swig_include_dirs}: - A list of directories to include in the ‘swig’ command.

  • B{cppargs}: - List of arguments to the compiler, e.g. C{[“-Wall”, “-fopenmp”]}.

  • B{lddargs}: - List of arguments to the linker, e.g. C{[“-E”, “-U”]}.

  • B{object_files}: - If you want to compile the files yourself. TODO: Not yet supported.

  • B{arrays}: - A nested list describing the C arrays to be made from NumPy arrays. The SWIG interface for fil NumPy is used. For 1D arrays, the inner list should contain strings with the variable names for the length of the arrays and the array itself. 2D matrices should contain the names of the dimensions in the two directions as well as the name of the array, and 3D tensors should contain the names of the dimensions in the three directions in addition to the name of the array. If the NumPy array har more than four dimensions, the inner list should contain strings with variable names for the number of dimensions, the length in each dimension as a pointer, and the array itself, respectively.

  • B{generate_interface}: - A bool to indicate if you want to generate the interface files.

  • B{generate_setup}: - A bool to indicate if you want to generate the setup.py file.

  • B{cmake_packages}: - A list with CMake configured packages which are used to configure and build the extension module. If used it will override the default behaviour of using distutils.

  • B{signature}: - A signature string to identify the form instead of the source code.

  • B{cache_dir}: - A directory to look for cached modules and place new ones.

    If missing, a default directory is used. Note that the module will not be cached if B{modulename} is specified. The cache directory should not be used for anything else.

instant.build.build_module_vmtk(c_code, cache_dir=None)[source]
instant.build.build_module_vtk(c_code, cache_dir=None)[source]
instant.build.copy_files(source, dest, files)[source]

Copy a list of files from a source directory to a destination directory. This may seem a bit complicated, but a lot of this code is error checking.

instant.build.copy_to_cache(module_path, cache_dir, modulename, check_for_existing_path=True)[source]

Copy module directory to cache.

instant.build.makedirs(path)[source]

Creates a directory (tree). If directory already excists it does nothing.

instant.build.recompile(modulename, module_path, new_compilation_checksum, build_system='distutils')[source]

Recompile module if the new checksum is different from the one in the checksum file in the module directory.

instant.build.strip_strings(x)[source]

instant.cache module

This module contains helper functions for working with the module cache.

Example operations:
  • modulename = modulename_from_checksum(checksum)
  • modulename = modulename_from_checksum(compute_checksum(signature))
  • module = import_module_directly(path, modulename)
  • module = import_module(modulename)
  • module = import_module(checksum)
  • module = import_module(compute_checksum(signature))
  • modules = cached_modules()
  • modules = cached_modules(cache_dir)
instant.cache.cached_modules(cache_dir=None)[source]

Return a list with the names of all cached modules.

instant.cache.check_disk_cache(modulename, cache_dir, moduleids)[source]
instant.cache.check_memory_cache(moduleid)[source]
instant.cache.checksum_from_modulename(modulename)[source]

Construct a module name from a checksum for use in cache.

instant.cache.import_and_cache_module(path, modulename, moduleids)[source]
instant.cache.import_module(moduleid, cache_dir=None)[source]

Import module from cache given its moduleid and an optional cache directory.

The moduleid can be either
  • the module name
  • a signature string, of which a checksum is taken to look up in the cache
  • a checksum string, which is used directly to look up in the cache
  • a hashable non-string object with a function moduleid.signature() which is used to get a signature string

The hashable object is used to look up in the memory cache before signature() is called. If the module is found on disk, it is placed in the memory cache.

instant.cache.import_module_directly(path, modulename)[source]

Import a module with the given module name that resides in the given path.

instant.cache.is_valid_module_name(name)[source]
instant.cache.memory_cached_module(moduleid)[source]

Returns the cached module if found.

instant.cache.modulename_from_checksum(checksum)[source]

Construct a module name from a checksum for use in cache.

instant.cache.place_module_in_memory_cache(moduleid, module)[source]

Place a compiled module in cache with given id.

instant.codegeneration module

This module contains helper functions for code generation.

instant.codegeneration.create_typemaps(classes)[source]
instant.codegeneration.find_vtk_classes(str)[source]
instant.codegeneration.generate_interface_file_vtk(signature, code)[source]
instant.codegeneration.generate_vtk_includes(classes)[source]
instant.codegeneration.mapstrings(format, sequence)[source]
instant.codegeneration.reindent(code)[source]

Reindent a multiline string to allow easier to read syntax.

Each line will be indented relative to the first non-empty line. Start the first line without text like shown in this example:

code = reindent("""
    Foo
    Bar
        Blatti
    Ping
    """)

makes all indentation relative to Foo.

instant.codegeneration.unique(sequence)[source]
instant.codegeneration.write_cmakefile(module_name, cmake_packages, csrcs, cppsrcs, local_headers, include_dirs, library_dirs, libraries, swig_include_dirs, swigargs, cppargs, lddargs)[source]
instant.codegeneration.write_interfacefile(filename, modulename, code, init_code, additional_definitions, additional_declarations, system_headers, local_headers, wrap_headers, arrays)[source]

Generate a SWIG interface file. Intended for internal library use.

The input arguments are as follows:
  • modulename (Name of the module)
  • code (Code to be wrapped)
  • init_code (Code to put in the init section of the interface file)
  • additional_definitions (Definitions to be placed in initial block with C code as well as in the main section of the SWIG interface file)
  • additional_declarations (Declarations to be placed in the main section of the SWIG interface file)
  • system_headers (A list of system headers with declarations needed by the wrapped code)
  • local_headers (A list of local headers with declarations needed by the wrapped code)
  • wrap_headers (A list of local headers that will be included in the code and wrapped by SWIG)
  • arrays (A nested list, the inner lists describing the different arrays)

The result of this function is that a SWIG interface with the name modulename.i is written to the current directory.

instant.codegeneration.write_itk_cmakefile(name)[source]
instant.codegeneration.write_setup(filename, modulename, csrcs, cppsrcs, local_headers, include_dirs, library_dirs, libraries, swig_include_dirs, swigargs, cppargs, lddargs)[source]

Generate a setup.py file. Intended for internal library use.

instant.codegeneration.write_vmtk_cmakefile(name)[source]
instant.codegeneration.write_vtk_interface_file(signature, code)[source]

instant.config module

This module contains helper functions for configuration using pkg-config.

instant.config.check_and_set_swig_binary(binary='swig', path='')[source]

Check if a particular swig binary is available

instant.config.check_swig_version(version, same=False)[source]

Check the swig version

Returns True if the version of the installed swig is equal or greater than the version passed to the function.

If same is True, the function returns True if and only if the two versions are the same.

Usage: if instant.check_swig_version(‘1.3.36’):

print “Swig version is greater than or equal to 1.3.36”
else:
print “Swig version is lower than 1.3.36”
instant.config.get_swig_binary()[source]

Return any cached swig binary

instant.config.get_swig_version()[source]

Return the current swig version in a ‘str’

instant.config.header_and_libs_from_pkgconfig(*packages, **kwargs)[source]

This function returns list of include files, flags, libraries and library directories obtain from a pkgconfig file.

The usage is:
(includes, flags, libraries, libdirs) = header_and_libs_from_pkgconfig(*list_of_packages)
or:
(includes, flags, libraries, libdirs, linkflags) = header_and_libs_from_pkgconfig(*list_of_packages, returnLinkFlags=True)

instant.inlining module

This module contains the inline* functions, which allows easy inlining of C/C++ functions.

instant.inlining.get_func_name(c_code)[source]
instant.inlining.inline(c_code, **kwargs)[source]

This is a short wrapper around the build_module function in instant.

It creates a module given that the input is a valid C function. It is only possible to inline one C function each time.

Usage:

>>> from instant import inline
>>> add_func = inline("double add(double a, double b){ return a+b; }")
>>> print "The sum of 3 and 4.5 is ", add_func(3, 4.5)
instant.inlining.inline_module(c_code, **kwargs)[source]

This is a short wrapper around the build_module function in instant.

It creates a module given that the input is a valid C function. It is only possible to inline one C function each time.

Usage:

>>> from instant import inline
>>> add_func = inline("double add(double a, double b){ return a+b; }")
>>> print "The sum of 3 and 4.5 is ", add_func(3, 4.5)
instant.inlining.inline_module_with_numpy(c_code, **kwargs)[source]

This is a short wrapper around the build_module function in instant.

It creates a module given that the input is a valid C function. It is only possible to inline one C function each time. The difference between this function and the inline function is that C-arrays can be used. The following example illustrates that.

Usage:

>>> import numpy
>>> import time
>>> from instant import inline_with_numpy
>>> c_code = """
    double sum (int n1, double* array1){
        double tmp = 0.0;
        for (int i=0; i<n1; i++) {
            tmp += array1[i];
        }
        return tmp;
    }
    """
>>> sum_func = inline_with_numpy(c_code,  arrays = [['n1', 'array1']])
>>> a = numpy.arange(10000000); a = numpy.sin(a)
>>> sum_func(a)
instant.inlining.inline_vmtk(c_code, cache_dir=None)[source]
instant.inlining.inline_vtk(c_code, cache_dir=None)[source]
instant.inlining.inline_with_numpy(c_code, **kwargs)[source]

This is a short wrapper around the build_module function in instant.

It creates a module given that the input is a valid C function. It is only possible to inline one C function each time. The difference between this function and the inline function is that C-arrays can be used. The following example illustrates that.

Usage:

>>> import numpy
>>> import time
>>> from instant import inline_with_numpy
>>> c_code = """
    double sum (int n1, double* array1){
        double tmp = 0.0;
        for (int i=0; i<n1; i++) {
            tmp += array1[i];
        }
        return tmp;
    }
    """
>>> sum_func = inline_with_numpy(c_code,  arrays = [['n1', 'array1']])
>>> a = numpy.arange(10000000); a = numpy.sin(a)
>>> sum_func(a)

instant.locking module

File locking for the cache system, to avoid problems when multiple processes work with the same module. Only works on UNIX systems.

Two Python libraries can be used:

flufl.lock : A nfs safe which can be downloaded from:

fcntl : A builtin Python module which only works on posix machines
and it is does unfortunately not work on nfs
instant.locking.get_lock(cache_dir, module_name)[source]

Get a new file lock.

instant.locking.release_lock(lock)[source]

Release a lock currently held by Instant.

class instant.locking.file_lock(cache_dir, module_name)[source]

Bases: object

File lock using with statement

instant.output module

This module contains internal logging utilities.

instant.output.get_log_handler()[source]
instant.output.get_logger()[source]
instant.output.get_status_output(cmd, input=None, cwd=None, env=None)[source]
instant.output.instant_assert(condition, *message)[source]
instant.output.instant_debug(*message)[source]
instant.output.instant_error(*message)[source]
instant.output.instant_info(*message)[source]
instant.output.instant_warning(*message)[source]
instant.output.set_log_handler(handler)[source]
instant.output.set_log_level(level)[source]
instant.output.set_logging_level(level)[source]
instant.output.write_file(filename, text, mode='w')[source]

Write text to a file and close it.

instant.paths module

This module contains helper functions for working with temp and cache directories.

instant.paths.delete_temp_dir()[source]

Delete the temporary directory created by get_temp_dir().

instant.paths.get_default_cache_dir()[source]

Return the default cache directory.

instant.paths.get_default_error_dir()[source]

Return the default error directory.

instant.paths.get_instant_dir()[source]

Return the default instant directory, creating it if necessary.

instant.paths.get_temp_dir()[source]

Return a temporary directory for the duration of this process.

Multiple calls in the same process returns the same directory. Remember to call delete_temp_dir() before exiting.

instant.paths.makedirs(path)[source]

Creates a directory (tree). If directory already excists it does nothing.

instant.paths.validate_cache_dir(cache_dir)[source]

instant.signatures module

This module contains helper functions for working with checksums.

instant.signatures.compute_checksum(text='', filenames=[])[source]

Get the checksum value of filename modified based on Python24ToolsScriptsmd5.py

Module contents

Instant allows compiled C/C++ modules to be created at runtime in your Python application, using SWIG to wrap the C/C++ code.

A simple example:
>>> from instant import inline
>>> add_func = inline("double add(double a, double b){ return a+b; }")
>>> print "The sum of 3 and 4.5 is ", add_func(3, 4.5)

The main functions are C{build_module}, C{write_code}, and C{inline*} see their documentation for more details.

For more examples, see the tests/ directory in the Instant distribution.

Questions, bugs and patches should be sent to fenics-dev@googlegroups.com.