# 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.

  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_root()
    Returns

      the root `Module` (even if it is self)

  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:

  > 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