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 aMultiSectionFactory
object is used as code generation output.
- property 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_submodule(submodule_name)¶
get a submodule by its name
- property 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:
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