Utilities

Helpers for xdress.

author:Anthony Scopatz <scopatz@gmail.com>

Utilities API

class xdress.utils.DescriptionCache(cachefile='build/desc.cache')

A quick persistent cache for descriptions from files. The keys are (classname, filename, kind) tuples. The values are (hashes-of-the-file, description-dictionary) tuples.

Parameters :

cachefile : str, optional

Path to description cachefile.

dump()

Writes the cache out to the filesystem.

isvalid(name, kind)

Boolean on whether the cach value for a (apiname, kind) tuple matches the state of the file on the system.

class xdress.utils.RunControl(**kwargs)

A composable configuration class for xdress. Unlike argparse.Namespace, this keeps the object dictionary (__dict__) separate from the run control attributes dictionary (_dict).

Parameters :

kwargs : optional

Items to place into run control.

class xdress.utils.apiname

This is a type, based on a named tuple, that represents the API element names and is used to declare or discover where variables, functions, and classes live for the rest of xdress. All of the fields default to NotSpecified if not given. These feilds are the sames as what appear in description dictionaries under the ‘name’ key.

Parameters :

srcname : str, tuple, or NotSpecified

The element’s API name in the original source code, eg. MyClass.

srcfiles : str, tuple of str, or NotSpecified

This is a sequence of unique strings which represents the file paths where the API element may be defined. For example, (‘myfile.c’, ‘myfile.h’). If the element is defined outside of these files, then the automatic discovery or description may fail. When using ensure_apiname(), all strings are automatically globbed, so ‘src/myfile.*’ will be converted to (‘src/myfile.c’, ‘src/myfile.h’). Since these files are parsed they must actually exist on the filesystem.

tarbase : str or NotSpecified

The base portion of all automatically generated (target) files. This does not include the directory or the file extension. For example, if you wanted cythongen to create a file name ‘mynewfile.pyx’ then the value here would be simply ‘mynewfile’.

tarname : str, tuple, or NotSpecified

The element’s API name in the automatically generated (target) files, e.g. MyNewClass.

incfiles : tuple of str or NotSpecified

This is a sequence of all files which must be #include’d to access the srcname at compile time. This should be as minimal of a set as possible, preferably only one file. For example even though most HDF5 API declarations are split across multiple files, to use the public API you only ever need to include ‘hdf5.h’. Because these files are not parsed they do not need to exist for xdress to run. Thus the strings in incfiles are not globbed.

sidecars : str, tuple of str, or NotSpecified

This is a sequence of all sidecar files to use for this API element. Like srcfiles, these files must exist for xdress to run. They similarly globbed. For example, ‘myfile.py’.

language : str or NotSpecified

Flag for the language that the srcfiles are implemented in. Valid options are: ‘c’, ‘c++’, ‘f’, ‘fortran’, ‘f77’, ‘f90’, ‘python’, and ‘cython’.

See also

ensure_apiname

class xdress.utils.indentstr

A special string subclass that can be used to indent the whol string inside of format strings by accessing an indentN attr. For example, s.indent8 will return a copy of the string s where every line starts with 8 spaces.

xdress.utils.c_literal(s)

Convert a C/C++ literal to the corresponding Python value.

xdress.utils.ensure_apiname(name)

Takes user input and returns the corresponding apiname named tuple. If the name is already an apiname instance with no NotSpecified fields, this does not make a copy.

xdress.utils.ensuredirs(f)

For a file path, ensure that its directory path exists.

xdress.utils.exec_file(filename, glb=None, loc=None)

A function equivalent to the Python 2.x execfile statement.

xdress.utils.expand_default_args(methods)

This function takes a collection of method tuples and expands all of the default arguments, returning a set of all methods possible.

xdress.utils.extra_filenames(name)

Returns a diictionary of extra filenames for an API element implemented in a given language and bound into a target.

Parameters :

name : apiname

The API element name.

Returns :

extra : dict

Extra filenames.

xdress.utils.find_filenames(srcname, tarname=None, sourcedir='src', language=None)

Returns a description dictionary for a class or function implemented in a source file and bound into a target file.

Parameters :

srcname : str

File basename of implementation.

tarname : str, optional

File basename where the bindings will be generated.

srcdir : str, optional

Source directory.

Returns :

desc : dict

Description dictionary containing only filenames.

xdress.utils.find_sidecar(*args, **kwargs)

Finds the sidecar for a filename, if it exists. Otherwise returns None.

xdress.utils.find_source(basename, sourcedir='.', language=None)

Finds a source filename, header filename, language name, and language source extension given a basename and source directory.

xdress.utils.flatten(iterable)

Generator which returns flattened version of nested sequences.

xdress.utils.guess_language(filename, default='c++')

Try to guess a files’ language from its extention, defaults to C++.

xdress.utils.indent(s, n=4, join=True)

Indents all lines in the string or list s by n spaces.

xdress.utils.infer_format(filename, format)

Tries to figure out a file format.

xdress.utils.isclassdesc(desc)

Tests if a description is a class-type description.

xdress.utils.isfuncdesc(desc)

Tests if a description is a function-type description.

xdress.utils.ishashable(x)

Tests if a value is hashable.

xdress.utils.isvardesc(desc)

Tests if a description is a variable-type description.

xdress.utils.memoize(obj)

Generic memoziation decorator based off of code from http://wiki.python.org/moin/PythonDecoratorLibrary . This is not suitabe for method caching.

xdress.utils.merge_descriptions(descriptions)

Given a sequence of descriptions, in order of increasing precedence, merge them into a single description dictionary.

xdress.utils.newcopyover(f1, f2, verbose=False)

Useful for not forcing re-compiles and thus playing nicely with the build system. This is acomplished by not writing the file if the existsing contents are exactly the same as what would be written out.

Parameters :

f1 : str

Path to file to copy from

f2 : str

Path to file to copy over

vebose : bool, optional

prints extra message

xdress.utils.newoverwrite(s, filename, verbose=False)

Useful for not forcing re-compiles and thus playing nicely with the build system. This is acomplished by not writing the file if the existsing contents are exactly the same as what would be written out.

Parameters :

s : str

string contents of file to possible

filename : str

Path to file.

vebose : bool, optional

prints extra message

xdress.utils.parse_global_rc()

Search a global xdressrc file and parse if it exists. If nothing is found, an empty RunControl is returned.

xdress.utils.parse_template(s, open_brace='<', close_brace='>', separator=', ')

Takes a string – which may represent a template specialization – and returns the corresponding type.

xdress.utils.sortedbytype(iterable)

Sorts an iterable by types first, then value.

xdress.utils.split_template_args(s, open_brace='<', close_brace='>', separator=', ')

Takes a string with template specialization and returns a list of the argument values as strings.

xdress.utils.touch(filename)

Opens a file and updates the mtime, like the posix command of the same name.

xdress.utils.warn_forbidden_name(forname, inname=None, rename=None)

Warns the user that a forbidden name has been found.

xdress.utils.writenewonly(s, filename, verbose=False)

Only writes the contents of the string to a file if the file does not exist. Useful for not tocuhing files.

Parameters :

s : str

string contents of file to possible

filename : str

Path to file.

vebose : bool, optional

prints extra message

xdress.utils.DEFAULT_PLUGINS = ('xdress.autoall', 'xdress.cythongen', 'xdress.stlwrap')

Default list of plugin module names.

xdress.utils.DEFAULT_RC_FILE = 'xdressrc.py'

Default run control file name.

xdress.utils.NotSpecified = NotSpecified

A helper class singleton for run control meaning that a ‘real’ value has not been given.

xdress.utils.nyansep = '~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~=[,,_,,]:3'

WAT?!

xdress.utils.memoize_method

Decorator suitable for memoizing methods, rather than functions and classes. This is based off of code that may be found at http://code.activestate.com/recipes/577452-a-memoize-decorator-for-instance-methods/ This code was originally released under the MIT license.