Utilities¶
Helpers for xdress.
author: | Anthony Scopatz <scopatz@gmail.com> |
---|
Utilities API¶
-
class
xdress.utils.
DescriptionCache
(cachefile='build/desc.cache')[source]¶ 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.
-
class
xdress.utils.
RunControl
(**kwargs)[source]¶ 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
[source]¶ 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
-
class
xdress.utils.
indentstr
[source]¶ 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.
-
class
xdress.utils.
memoize_method
(meth)[source]¶ 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.
-
xdress.utils.
ensure_apiname
(name)[source]¶ 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.
exec_file
(filename, glb=None, loc=None)[source]¶ A function equivalent to the Python 2.x execfile statement.
-
xdress.utils.
expand_default_args
(methods)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Finds the sidecar for a filename, if it exists. Otherwise returns None.
-
xdress.utils.
find_source
(basename, sourcedir='.', language=None)[source]¶ Finds a source filename, header filename, language name, and language source extension given a basename and source directory.
-
xdress.utils.
flatten
(iterable)[source]¶ Generator which returns flattened version of nested sequences.
-
xdress.utils.
guess_language
(filename, default='c++')[source]¶ Try to guess a files’ language from its extention, defaults to C++.
-
xdress.utils.
indent
(s, n=4, join=True)[source]¶ Indents all lines in the string or list s by n spaces.
-
xdress.utils.
memoize
(obj)[source]¶ 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)[source]¶ Given a sequence of descriptions, in order of increasing precedence, merge them into a single description dictionary.
-
xdress.utils.
newcopyover
(f1, f2, verbose=False)[source]¶ 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)[source]¶ 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
()[source]¶ 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=', ')[source]¶ Takes a string – which may represent a template specialization – and returns the corresponding type.
-
xdress.utils.
split_template_args
(s, open_brace='<', close_brace='>', separator=', ')[source]¶ Takes a string with template specialization and returns a list of the argument values as strings.
-
xdress.utils.
touch
(filename)[source]¶ 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)[source]¶ Warns the user that a forbidden name has been found.
-
xdress.utils.
writenewonly
(s, filename, verbose=False)[source]¶ 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[source]¶ A helper class singleton for run control meaning that a ‘real’ value has not been given.
-
xdress.utils.
nyansep
= '~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~\\_/~=[,,_,,]:3'¶ WAT?!