module: generate Python modules and submodules

Objects that represent – and generate code for – C/C++ Python extension modules.

Modules and Sub-modules

A L{Module} object takes care of generating the code for a Python module. The way a Python module is organized is as follows. There is one “root” L{Module} object. There can be any number of L{SubModule}s. Sub-modules themselves can have additional sub-modules. Calling L{Module.generate} on the root module will trigger code generation for the whole module, not only functions and types, but also all its sub-modules.

In Python, a sub-module will appear as a I{built-in} Python module that is available as an attribute of its parent module. For instance, a module I{foo} having a sub-module I{xpto} appears like this:

|>>> import foo
|>>> foo.xpto
|<module 'foo.xpto' (built-in)>

Modules and C++ namespaces

Modules can be associated with specific C++ namespaces. This means, for instance, that any C++ class wrapped inside that module must belong to that C++ namespace. Example:

|>>> from cppclass import *
|>>> mod = Module("foo", cpp_namespace="::foo")
|>>> mod.add_class("Bar")
|<pybindgen.CppClass 'foo::Bar'>

When we have a toplevel C++ namespace which contains another nested namespace, we want to wrap the nested namespace as a Python sub-module. The method L{ModuleBase.add_cpp_namespace} makes it easy to create sub-modules for wrapping nested namespaces. For instance:

|>>> from cppclass import *
|>>> mod = Module("foo", cpp_namespace="::foo")
|>>> submod = mod.add_cpp_namespace('xpto')
|>>> submod.add_class("Bar")
|<pybindgen.CppClass 'foo::xpto::Bar'>

class pybindgen.module.Module(name, docstring=None, cpp_namespace=None)

Bases: pybindgen.module.ModuleBase

Parameters:

• name – module name
• docstring – docstring to use for this module
• cpp_namespace – C++ namespace prefix associated with this module

generate(out, module_file_base_name=None)

Generates the module

Parameters:module_file_base_name – base name of the module file.

This is useful when we want to produce a _foo module that will be imported into a foo module, to avoid making all types docstrings contain _foo.Xpto instead of foo.Xpto.

generate_c_to_python_type_converter(value_type, code_sink)

Generates a c-to-python converter function for a given type and returns the name of the generated function. If called multiple times with the same name only the first time is the converter function generated.

Use: this method is to be considered pybindgen internal, used by code generation modules.

Returns:name of the converter function

generate_python_to_c_type_converter(value_type, code_sink)

Generates a python-to-c converter function for a given type and returns the name of the generated function. If called multiple times with the same name only the first time is the converter function generated.

Use: this method is to be considered pybindgen internal, used by code generation modules.

Returns:name of the converter function

get_c_to_python_type_converter_function_name(value_type)

Internal API, do not use.

get_python_to_c_type_converter_function_name(value_type)

Internal API, do not use.

class pybindgen.module.ModuleBase(name, parent=None, docstring=None, cpp_namespace=None)

Bases: dict

ModuleBase objects can be indexed dictionary style to access contained types. Example:

>>> from enum import Enum
>>> from cppclass import CppClass
>>> m = Module("foo", cpp_namespace="foo")
>>> subm = m.add_cpp_namespace("subm")
>>> c1 = m.add_class("Bar")
>>> c2 = subm.add_class("Zbr")
>>> e1 = m.add_enum("En1", ["XX"])
>>> e2 = subm.add_enum("En2", ["XX"])
>>> m["Bar"] is c1
True
>>> m["foo::Bar"] is c1
True
>>> m["En1"] is e1
True
>>> m["foo::En1"] is e1
True
>>> m["badname"]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 'badname'
>>> m["foo::subm::Zbr"] is c2
True
>>> m["foo::subm::En2"] is e2
True

Note: this is an abstract base class, see L{Module}

Parameters:

• name – module name
• parent – parent L{module<Module>} (i.e. the one that contains this submodule) or None if this is a root module
• docstring – docstring to use for this module
• cpp_namespace – C++ namespace prefix associated with this module

Returns:

a new module object

add_class(*args, **kwargs)

Add a class to the module. See the documentation for L{CppClass.__init__} for information on accepted parameters.

add_container(*args, **kwargs)

Add a container to the module. See the documentation for L{Container.__init__} for information on accepted parameters.

add_cpp_namespace(name)

Add a nested module namespace corresponding to a C++ namespace. If the requested namespace was already added, the existing module is returned instead of creating a new one.

Parameters:name – name of C++ namespace (just the last component,

not full scoped name); this also becomes the name of the submodule.

Returns:a L{SubModule} object that maps to this namespace.

add_custom_function_wrapper(*args, **kwargs)

Add a function, using custom wrapper code, to the module/namespace. See the documentation for pybindgen.function.CustomFunctionWrapper for information on accepted parameters.

add_enum(*args, **kwargs)

Add an enumeration to the module. See the documentation for L{Enum.__init__} for information on accepted parameters.

add_exception(*args, **kwargs)

Add a C++ exception to the module. See the documentation for L{CppException.__init__} for information on accepted parameters.

add_function(*args, **kwargs)

Add a function to the module/namespace. See the documentation for Function.__init__() for information on accepted parameters.

add_include(include)

Adds an additional include directive, needed to compile this python module

Parameters:include – the name of the header file to include, including surrounding “” or <>.

add_struct(*args, **kwargs)

Add a struct to the module.

In addition to the parameters accepted by L{CppClass.__init__}, this method accepts the following keyword parameters:

• no_constructor (bool): if True, the structure will not have a constructor by default (if omitted, it will be considered to have a trivial constructor).
• no_copy (bool): if True, the structure will not have a copy constructor by default (if omitted, it will be considered to have a simple copy constructor).

add_typedef(wrapper, alias)

Declares an equivalent to a typedef in C::

typedef Foo Bar;

Parameters:

• wrapper – the wrapper object to alias (Foo in the example)
• alias – name of the typedef alias

@note: only typedefs for CppClass objects have been implemented so far; others will be implemented in the future.

begin_section(section_name)

Declare that types and functions registered with the module in the future belong to the section given by that section_name parameter, until a matching end_section() is called.

Note

begin_section()/end_section() are silently ignored unless a MultiSectionFactory object is used as code generation output.

current_section

declare_one_time_definition(definition_name)

Internal helper method for code geneneration to coordinate generation of code that can only be defined once per compilation unit

(note: assuming here one-to-one mapping between ‘module’ and ‘compilation unit’).

Parameters:definition_name – a string that uniquely identifies the code

definition that will be added. If the given definition was already declared KeyError is raised.

>>> module = Module('foo')
>>> module.declare_one_time_definition("zbr")
>>> module.declare_one_time_definition("zbr")
Traceback (most recent call last):
...
KeyError: 'zbr'
>>> module.declare_one_time_definition("bar")

do_generate(out, module_file_base_name=None)

(internal) Generates the module.

end_section(section_name)

Declare the end of a section, i.e. further types and functions will belong to the main module.

Parameters:section_name – name of section; must match the one in the previous begin_section() call.

generate_forward_declarations(code_sink)

(internal) generate forward declarations for types

get_current_section()

get_module_path()

Get the full [module, submodule, submodule,...] path

get_name()

get_namespace_path()

Get the full [root_namespace, namespace, namespace,...] path (C++)

get_root()

Returns:the root Module (even if it is self)

get_submodule(submodule_name)

get a submodule by its name

name

register_type(name, full_name, type_wrapper)

Register a type wrapper with the module, for easy access in the future. Normally should not be called by the programmer, as it is meant for internal pybindgen use and called automatically.

Parameters:

• name – type name without any C++ namespace prefix, or None
• full_name – type name with a C++ namespace prefix, or None
• type_wrapper – the wrapper object for the type (e.g. L{CppClass} or L{Enum})

set_c_function_name_transformer(transformer)

Sets the function to be used when transforming a C function name into the python function name; the given given function is called like this:

python_name = transformer(c_name)

set_name(name)

set_strip_prefix(prefix)

Sets the prefix string to be used when transforming a C function name into the python function name; the given prefix string is removed from the C function name.

class pybindgen.module.MultiSectionFactory

Bases: object

Abstract base class for objects providing support for multi-section code generation, i.e., splitting the generated C/C++ code into multiple files. The generated code will generally have the following structure:

1. For each section there is one source file specific to that section;

2. There is a I{main} source file, e.g. C{foomodule.cc}. Code that does not belong to any section will be included in this main file;

3. Finally, there is a common header file, (e.g. foomodule.h), which is included by the main file and section files alike. Typically this header file contains function prototypes and type definitions.

@see: L{Module.generate}

get_common_header_code_sink()

Create and/or return a code sink for the common header.

get_common_header_include()

Return the argument for an #include directive to include the common header.

Returns:a string with the header name, including surrounding

“” or <>. For example, ‘“foomodule.h”’.

get_main_code_sink()

Create and/or return a code sink for the main file.

get_section_code_sink(section_name)

Create and/or return a code sink for a given section.

Parameters:section_name – name of the section Returns:a L{CodeSink} object that will receive generated code belonging to the section C{section_name}

class pybindgen.module.SubModule(name, parent, docstring=None, cpp_namespace=None)

Bases: pybindgen.module.ModuleBase

Parameters:

• parent – parent L{module<Module>} (i.e. the one that contains this submodule)
• name – name of the submodule
• docstring – docstring to use for this module
• cpp_namespace – C++ namespace component associated with this module