gccxmlparser: scan header files to extract API definitions

class pybindgen.gccxmlparser.AnnotationsScanner

Bases: object

get_annotations(decl)

Parameters:decl – pygccxml declaration_t object

parse_boolean(value)

warn_unused_annotations()

exception pybindgen.gccxmlparser.AnnotationsWarning

Bases: pybindgen.gccxmlparser.ModuleParserWarning

Warning for pybindgen GccxmlParser to report a problem in annotations.

class pybindgen.gccxmlparser.ErrorHandler

Bases: pybindgen.settings.ErrorHandler

handle_error(wrapper, exception, traceback_)

class pybindgen.gccxmlparser.GccXmlTypeRegistry(root_module)

Bases: object

Parameters:root_module – the root L{Module} object

class_registered(cpp_class)

lookup_parameter(type_info, param_name, annotations={}, default_value=None)

lookup_return(type_info, annotations={})

class pybindgen.gccxmlparser.ModuleParser(module_name, module_namespace_name='::')

Bases: object

Attr enable_anonymous_containers:  if True, pybindgen will attempt to scan for all std containers, even the ones that have no typedef’ed name. Enabled by default.

Creates an object that will be able parse header files and create a pybindgen module definition.

Parameters:

• module_name – name of the Python module
• module_namespace_name – optional C++ namespace name; if given, only definitions of this namespace will be included in the python module

add_post_scan_hook(hook)

Add a function to be called right after converting a gccxml definition to a PyBindGen wrapper object. This hook function will be called for every scanned type, function, or method. It will be called like this:

post_scan_hook(module_parser, pygccxml_definition, pybindgen_wrapper)

where:

• module_parser – the ModuleParser (this class) instance

• pygccxml_definition – the definition reported by pygccxml

• pybindgen_wrapper – a pybindgen object that generates a wrapper,

  such as CppClass, Function, or CppMethod.

add_pre_scan_hook(hook)

Add a function to be called right before converting a gccxml definition to a PyBindGen wrapper object. This hook function will be called for every scanned type, function, or method, and given the a chance to modify the annotations for that definition. It will be called like this::

pre_scan_hook(module_parser, pygccxml_definition, global_annotations,
              parameter_annotations)

where:

• module_parser – the ModuleParser (this class) instance

• pygccxml_definition – the definition reported by pygccxml

• global_annotations – a dicionary containing the “global annotations”

  for the definition, i.e. a set of key=value pairs not associated with any particular parameter

• parameter_annotations – a dicionary containing the “parameter

  annotations” for the definition. It is a dict whose keys are parameter names and whose values are dicts containing the annotations for that parameter. Annotations pertaining the return value of functions or methods are denoted by a annotation for a parameter named ‘return’.

parse(header_files, include_paths=None, whitelist_paths=None, includes=(), pygen_sink=None, pygen_classifier=None, gccxml_options=None)

parses a set of header files and returns a pybindgen Module instance. It is equivalent to calling the following methods:

1. parse_init(header_files, include_paths, whitelist_paths)
2. scan_types()
3. scan_methods()
4. scan_functions()
5. parse_finalize()

The documentation for L{ModuleParser.parse_init} explains the parameters.

parse_finalize()

parse_init(header_files, include_paths=None, whitelist_paths=None, includes=(), pygen_sink=None, pygen_classifier=None, gccxml_options=None)

Prepares to parse a set of header files. The following methods should then be called in order to finish the rest of scanning process:

1. scan_types()
2. scan_methods()
3. scan_functions()
4. parse_finalize()

Parameters:

• header_files (list of string) – header files to parse
• include_paths (list of string) – (deprecated, use the parameter gccxml_options) list of include paths
• whitelist_paths (list of string) – additional directories for definitions to be included Normally the module parser filters out API definitions that have been defined outside one of the header files indicated for parsing. The parameter whitelist_paths instructs the module parser to accept definitions defined in another header file if such header file is inside one of the directories listed by whitelist_paths.
• pygen_sink (L{CodeSink} or list of L{PygenSection} objects) –

  code sink for python script generation.

  This parameter activates a mode wherein ModuleParser, in addition to building in memory API definitions, creates a python script that will generate the module, when executed. The generated Python script can be human editable and does not require pygccxml or gccxml to run, only PyBindGen to be installed.

  The pygen parameter can be either:

  1. A single code sink: this will become the main and only script file to be generated
  2. A list of L{PygenSection} objects. This option requires the pygen_classifier to be given.

• pygen_classifier – the classifier to use when pygen is given and is a dict
• gccxml_options (dict) – extra options to pass into the pygccxml.parser.config.gccxml_configuration_t object as keyword arguments for more information).

scan_functions()

scan_methods()

scan_types()

exception pybindgen.gccxmlparser.ModuleParserWarning

Bases: exceptions.Warning

Base class for all warnings reported here.

exception pybindgen.gccxmlparser.NotSupportedWarning

Bases: pybindgen.gccxmlparser.ModuleParserWarning

Warning for pybindgen GccxmlParser, to report something pybindgen does not support.

class pybindgen.gccxmlparser.PygenClassifier

Bases: object

classify(pygccxml_definition)

This is a pure virtual method that must be implemented by subclasses. It will be called by PyBindGen for every API definition, and should return a section name.

Parameters:pygccxml_definition – gccxml definition object Returns:section name

get_section_precedence(section_name)

This is a pure virtual method that may (or not) be implemented by subclasses. It will be called by PyBindGen for every API definition, and should return the precedence of a section. This is used when sections reflect ‘modules’ whose types must be registered in a certain order.

Parameters:section_name – the name of the section Returns:order of precedence of the section. The lower the number, the sooner the section is to be registered.

class pybindgen.gccxmlparser.PygenSection(name, code_sink, local_customizations_module=None)

Bases: object

Class to hold information about a python generation section

Parameters:

• name (str) – section name; this name should be a valid python module name; the special name ‘__main__’ is used to denote the main section, which comprises the main script itself
• code_sink (L{CodeSink}) – code sink that will receive the generated code for the section. Normally the code sink should write to a file with the name of the section and a .py extension, to allow importing it as module.
• local_customizations_module (str) – name of the python module that may contain local customizations for the section, or None. If not None, PyBindGen will generate code that tries to import that module in the respective section and call functions on it, or ignore it if the module does not exist.

exception pybindgen.gccxmlparser.WrapperWarning

Bases: pybindgen.gccxmlparser.ModuleParserWarning

Warning for pybindgen GccxmlParser, to be used when a C++ definition cannot be converted to a pybindgen wrapper.

pybindgen.gccxmlparser.find_declaration_from_name(global_ns, declaration_name)

pybindgen.gccxmlparser.normalize_class_name(class_name, module_namespace)

pybindgen.gccxmlparser.normalize_name(decl_string)

pybindgen.gccxmlparser.remove_const(type)

removes const from the type definition

If type is not const type, it will be returned as is

pybindgen.gccxmlparser.remove_pointer(type)

removes pointer from the type definition

If type is not pointer type, it will be returned as is.

pybindgen.gccxmlparser.remove_reference(type)

removes reference from the type definition

If type is not reference type, it will be returned as is.