Module Definitions

Detailed Description

Defining Python modules from C++ with classes, functions, and enums.

This module provides helper classes and macros to define Python modules that can contain C++ classes, functions, enums, and other objects exported to Python.

Module Components

A Python module can contain:

• Functions: C++ functions exported with various signatures
• Classes: C++ classes exported as Python classes
• Enums: C++ enums exported as Python enum types
• Objects: Arbitrary Python objects (constants, instances, etc.)
• Values: Simple values like integers and strings

But every module must also be declared, and have an entrypoint.

Usage Overview

To create a Python module, you typically use macros that work with ModuleDefinition: Macro names follow a consistent grammar, see Python Macro Name Conventions.

// Define module
PY_DECLARE_MODULE_NAME_DOC(mymodule, "mymodule", "My example module")
 
// Add functions
PY_MODULE_FUNCTION(mymodule, myFunction)
 
// Add classes
PY_MODULE_CLASS(mymodule, MyClass)
 
// Add enums
PY_MODULE_ENUM(mymodule, MyEnum)
 
// Create module entrypoint for Python extension
PY_MODULE_ENTRYPOINT(mymodule)

The ModuleDefinition class is typically not used directly. Instead, use the provided macros in pyobject_macros.h that work with ModuleDefinition instances.

Topics
	Module Declaration Macros
	These macros declare and define ModuleDefinition objects that represent Python modules.
	Module Entrypoint and Injection Macros
	These macros handle module initialization, injection, and extension module creation.
	Module Constants and Objects Macros
	These macros add constants, variables, and arbitrary Python objects to modules.
	Module Function Macros
	These macros export C++ functions to a Python and add them to a Python module.
	Function Cast Export Macros (Deprecated)

Classes
class	lass::python::ModuleDefinition
	Definition of a Python module. More...

Class Integration
Macros to add Python classes to modules. These macros integrate class definitions with module definitions, making the classes available as types within the module namespace. Classes must first be declared using PY_DECLARE_CLASS_* macros before they can be added to modules.
#define	PY_INJECT_CLASS_IN_MODULE(t_cppClass, i_module, s_doc)
	Inject a class into a module at runtime.
#define	PY_MODULE_CLASS(i_module, t_cppClass)
	Add a Python class to a module.

Macro Definition Documentation

PY_INJECT_CLASS_IN_MODULE

#define PY_INJECT_CLASS_IN_MODULE	(		t_cppClass,
			i_module,
			s_doc )

Value:

    t_cppClass::_lassPyClassDef.setDocIfNotNull(s_doc);\
    i_module.injectClass(t_cppClass::_lassPyClassDef);

Inject a class into a module at runtime.

This is the legacy runtime approach for adding classes to modules. Use PY_MODULE_CLASS() instead for compile-time registration.

Parameters

t_cppClass	Python binding class type that has been declared with PY_DECLARE_CLASS_*
i_module	Module object identifier to inject the class into
s_doc	Optional class documentation string (or nullptr)

Note

This macro must be invoked after the module has been created. It's best to place this in a postInject function as shown in the example below. The postInject function gets the module object as a parameter, but don't use that if you want the Lass stubgen tool to work correctly. Work on the module definition instead (the one you created with PY_DECLARE_MODULE()).

Example

PY_DECLARE_MODULE( mymodule )
PY_DECLARE_CLASS(MyClass)
void mymodule_postinject(PyObject*)
{
    PY_INJECT_CLASS_IN_MODULE(MyClass, mymodule, "Sample class") // mymodule.MyClass
}
LASS_EXECUTE_BEFORE_MAIN( mymodule.setPostInject(mymodule_postinject); )
PY_MODULE_ENTRYPOINT( mymodule)

Definition at line 3952 of file pyobject_macros.h.

PY_MODULE_CLASS

#define PY_MODULE_CLASS	(		i_module,
			t_cppClass )

Add a Python class to a module.

Registers a class definition to be included in the module when it is created. The class must have been declared with PY_DECLARE_CLASS_* macros. This is executed before main(), so the class is available when the module is created.

Parameters

i_module	Module identifier declared by PY_DECLARE_MODULE_* (must be unscoped identifier for token concatenation)
t_cppClass	Python binding class type that has been declared with PY_DECLARE_CLASS_*

Example

PY_DECLARE_CLASS_NAME_DOC(MyClass, "MyClass", "Sample class")
PY_MODULE_CLASS(mymodule, MyClass)

Definition at line 3973 of file pyobject_macros.h.