Automatic API Discovery

This module is used to scrape the all of the APIs from a given source file and return their name and kind. These include classes, structs, functions, and certain variable types. It is not used to actually describe these elements. That is the job of the autodescriber.

This module is available as an xdress plugin by the name xdress.autoall.

Including this plugin enables the classes, functions, and variables run control parameters to have an asterix (‘*’) in the name positon (index 0). For example, rather than writing:

classes = [
    ('People', 'people'),
    ('JoanOfArc', 'people'),
    ('JEdgaHoover', 'people'),
    ('Leslie', 'people'),
    ('HuaMulan', 'people'),
    ]

we can instead simply write:

classes = [('*', 'people')]

Isn’t this grand?!

author:Anthony Scopatz <scopatz@gmail.com>

Automatic Finder API

class xdress.autoall.AutoNameCache(cachefile='build/autoname.cache')

A quick persistent cache for name lists automatically found in files. The keys are (classname, filename, kind) tuples. The values are (hashes-of-the-file, finder-results) tuples.

Parameters:

cachefile : str, optional

Path to description cachefile.

dump()

Writes the cache out to the filesystem.

isvalid(filename)

Boolean on whether the cach value for a filename matches the state of the file on the system.

class xdress.autoall.GccxmlFinder(root=None, onlyin=None, verbose=False)

Class used for discovering APIs using an etree representation of the GCC-XML AST.

Parameters:

root : element tree node, optional

The root element node of the AST.

onlyin : str, optional

Filename to search, prevents finding APIs coming from other libraries.

verbose : bool, optional

Flag to display extra information while visiting the file.

visit(node=None)

Visits the node and all sub-nodes, filling the API names as it goes.

Parameters:

node : element tree node, optional

The element tree node to start from. If this is None, then the top-level node is found and visited.

visit_kinds(node, kinds)

Visits the node and all sub-nodes, finding instances of the kinds and recording the names as it goes.

Parameters:

node : element tree node

The element tree node to start from.

kinds : str or sequence of str

The API elements to find.

Returns:

names : list of str

Names of the API elements in this file that match the kinds provided.

class xdress.autoall.PycparserFinder(root=None, onlyin=None, verbose=False)

Class used for discovering APIs using the pycparser AST.

Parameters:

root : element tree node, optional

The root element node of the AST.

onlyin : str, optional

Filename to search, prevents finding APIs coming from other libraries.

verbose : bool, optional

Flag to display extra information while visiting the file.

visit(node=None)

Visits the node and all sub-nodes, filling the API names as it goes.

Parameters:

node : element tree node, optional

The element tree node to start from. If this is None, then the top-level node is found and visited.

class xdress.autoall.XDressPlugin

This plugin resolves the ‘*’ syntax in wrapper types by parsing the source files prio to describing them.

The __init__() method may take no arguments or keyword arguments.

setup(rc)

Expands variables, functions, and classes in the rc based on copying src filenames to tar filename and the special ‘*’ all syntax.

setup_basic(rc)

Does the easy part of setting up an autodecsibe environment

setup_heavy(rc)

Does the hard work of actually searching the source files.

xdress.autoall.clang_findall(filename, includes=(), defines=('XDRESS', ), undefines=(), extra_parser_args=(), verbose=False, debug=False, builddir='build', language='c++', clang_includes=())

Automatically finds all API elements in a file via clang.

Parameters:

filename : str

The path to the file

includes : list of str, optional

The list of extra include directories to search for header files.

defines : list of str, optional

The list of extra macro definitions to apply.

undefines : list of str, optional

The list of extra macro undefinitions to apply.

extra_parser_args : list of str, optional

Further command line arguments to pass to the parser.

language : str

Valid language flag.

verbose : Ignored

debug : Ignored

builddir : Ignored

clang_includes : list of str, optional

clang-specific include paths.

Returns:

variables : list of strings

A list of variable names to wrap from the file.

functions : list of strings

A list of function names to wrap from the file.

classes : list of strings

A list of class names to wrap from the file.

xdress.autoall.findall(filename, includes=(), defines=('XDRESS', ), undefines=(), extra_parser_args=(), parsers='gccxml', verbose=False, debug=False, builddir='build', language='c++', clang_includes=())

Automatically finds all API elements in a file. This is the main entry point.

Parameters:

filename : str

The path to the file.

includes: list of str, optional :

The list of extra include directories to search for header files.

defines: list of str, optional :

The list of extra macro definitions to apply.

undefines: list of str, optional :

The list of extra macro undefinitions to apply.

extra_parser_args : list of str, optional

Further command line arguments to pass to the parser.

parsers : str, list, or dict, optional

The parser / AST to use to use for the file. Currently ‘clang’, ‘gccxml’, and ‘pycparser’ are supported, though others may be implemented in the future. If this is a string, then this parser is used. If this is a list, this specifies the parser order to use based on availability. If this is a dictionary, it specifies the order to use parser based on language, i.e. {'c' ['pycparser', 'gccxml'], 'c++': ['gccxml', 'pycparser']}.

verbose : bool, optional

Flag to diplay extra information while describing the class.

debug : bool, optional

Flag to enable/disable debug mode.

builddir : str, optional

Location of – often temporary – build files.

language : str

Valid language flag.

clang_includes : list of str, optional

clang-specific include paths.

Returns:

variables : list of strings

A list of variable names to wrap from the file.

functions : list of strings

A list of function names to wrap from the file.

classes : list of strings

A list of class names to wrap from the file.

xdress.autoall.gccxml_findall(filename, includes=(), defines=('XDRESS', ), undefines=(), extra_parser_args=(), verbose=False, debug=False, builddir='build', language='c++', clang_includes=())

Automatically finds all API elements in a file via GCC-XML.

Parameters:

filename : str

The path to the file

includes : list of str, optional

The list of extra include directories to search for header files.

defines : list of str, optional

The list of extra macro definitions to apply.

undefines : list of str, optional

The list of extra macro undefinitions to apply.

extra_parser_args : list of str, optional

Further command line arguments to pass to the parser.

verbose : bool, optional

Flag to diplay extra information while describing the class.

debug : bool, optional

Flag to enable/disable debug mode.

builddir : str, optional

Location of – often temporary – build files.

language : str

Valid language flag.

clang_includes : ignored

Returns:

variables : list of strings

A list of variable names to wrap from the file.

functions : list of strings

A list of function names to wrap from the file.

classes : list of strings

A list of class names to wrap from the file.

xdress.autoall.pycparser_findall(filename, includes=(), defines=('XDRESS', ), undefines=(), extra_parser_args=(), verbose=False, debug=False, builddir='build', language='c', clang_includes=())

Automatically finds all API elements in a file via GCC-XML.

Parameters:

filename : str

The path to the file

includes : list of str, optional

The list of extra include directories to search for header files.

defines : list of str, optional

The list of extra macro definitions to apply.

undefines : list of str, optional

The list of extra macro undefinitions to apply.

extra_parser_args : list of str, optional

Further command line arguments to pass to the parser.

verbose : bool, optional

Flag to diplay extra information while describing the class.

debug : bool, optional

Flag to enable/disable debug mode.

builddir : str, optional

Location of – often temporary – build files.

language : str

Valid language flag.

clang_includes : ignored

Returns:

variables : list of strings

A list of variable names to wrap from the file.

functions : list of strings

A list of function names to wrap from the file.

classes : list of strings

A list of class names to wrap from the file.