Module Entrypoint and Injection Macros

Detailed Description

These macros handle module initialization, injection, and extension module creation.

They manage the Python module lifecycle from creation to registration with the Python interpreter.

If you're building a Python extension module (a .pyd or .so file), you will typically use the entrypoint macros to create the required PyInit_* function that Python calls:

// Declare module
PY_DECLARE_MODULE_DOC(mymodule, "My example module")
 
// Add functions and classes
// ...
 
// Create module entrypoint for Python extension
PY_MODULE_ENTRYPOINT(mymodule)

The injection macros are more low-level and can be used to create modules at runtime to be registered with an embedded Python interpreter.

Macros
#define	PY_MODULE_ENTRYPOINT_NAME(i_module, i_name)
	Create a PyInit_* Python module initialization function with custom name.
#define	PY_MODULE_ENTRYPOINT(i_module)
	Create a Python module initialization function using the module identifier as the name.
#define	PY_INJECT_MODULE(i_module)
	Inject a Python module so Python becomes aware of it.
#define	PY_INJECT_MODULE_EX(i_module, s_moduleName, s_doc)
	Inject a module with name and documentation override.
#define	PY_INJECT_MODULE_NAME(i_module, s_moduleName)
	Inject a module with name override.
#define	PY_INJECT_MODULE_DOC(i_module, s_doc)
	Inject a module with documentation override.
#define	PY_EXTENSION_MODULE_EX(i_module, f_injection, s_doc)
	Inject a python module so Python is aware of it and produce all necessary code so a module can be used as extension of Python.
#define	PY_EXTENSION_MODULE_DOC(i_module, f_injection, s_doc)
	Create an extension module with documentation.
#define	PY_EXTENSION_MODULE(i_module, f_injection)
	Create an extension module (no documentation).

Macro Definition Documentation

PY_MODULE_ENTRYPOINT_NAME

#define PY_MODULE_ENTRYPOINT_NAME	(		i_module,
			i_name )

Value:

    PyMODINIT_FUNC LASS_CONCATENATE(PyInit_, i_name)() { return i_module.inject(); }

Create a PyInit_* Python module initialization function with custom name.

Generates the PyInit_* function required for Python extension modules. This function will be called by Python when the module is imported.

Parameters

i_module	Module identifier declared with PY_DECLARE_MODULE_*
i_name	Name for the initialization function (PyInit_<i_name> will be generated) Must be the same as your modoule name

Example

PY_DECLARE_MODULE_NAME(mod_mymodule, "mymodule")
// ...
PY_MODULE_ENTRYPOINT_NAME(mod_mymodule, mymodule) // generates PyInit_mymodule()

Definition at line 288 of file pyobject_macros.h.

PY_MODULE_ENTRYPOINT

#define PY_MODULE_ENTRYPOINT

(

i_module

)

Value:

PY_MODULE_ENTRYPOINT_NAME( i_module, i_module )

Create a Python module initialization function using the module identifier as the name.

Wraps PY_MODULE_ENTRYPOINT_NAME() with i_name = i_module.

Parameters

i_module

Module identifier (used for both module reference and function name)

Example

PY_DECLARE_MODULE(mymodule)
// ...
PY_MODULE_ENTRYPOINT(mymodule) // generates PyInit_mymodule()

Definition at line 305 of file pyobject_macros.h.

PY_INJECT_MODULE

#define PY_INJECT_MODULE

(

i_module

)

Value:

    i_module.inject();

Inject a Python module so Python becomes aware of it.

Creates the actual Python module object with all accumulated definitions (functions, classes, enums, constants). This should be done at runtime, typically in your main() function or during Python initialization.

Note

This is a specialist function for embedding modules instead of writing extension modules.

Parameters

i_module

Module identifier declared by PY_DECLARE_MODULE_*

Returns

A new reference to the Python module object, or nullptr on error (with Python exception set)

Example

LASS_ASSERT(Py_IsInitialized());
LockGIL lock;
TPyObjPtr mod(PY_INJECT_MODULE(mymodule));
if (mod)
{
    PyObject* sysmodules = PyImport_GetModuleDict();
    PyDict_SetItemString(sysmodules, "mymodule", mod);
}
// now you can run `import mymodule`

Definition at line 333 of file pyobject_macros.h.

PY_INJECT_MODULE_EX

#define PY_INJECT_MODULE_EX	(		i_module,
			s_moduleName,
			s_doc )

Value:

    i_module.setName(s_moduleName); \
    i_module.setDoc(s_doc); \
    i_module.inject();

Inject a module with name and documentation override.

Deprecated

Use PY_DECLARE_MODULE_NAME_DOC and PY_INJECT_MODULE instead

Definition at line 341 of file pyobject_macros.h.

PY_INJECT_MODULE_NAME

#define PY_INJECT_MODULE_NAME	(		i_module,
			s_moduleName )

Value:

    i_module.setName(s_moduleName); \
    i_module.inject();

Inject a module with name override.

Deprecated

Use PY_DECLARE_MODULE_NAME and PY_INJECT_MODULE instead

Definition at line 351 of file pyobject_macros.h.

PY_INJECT_MODULE_DOC

#define PY_INJECT_MODULE_DOC	(		i_module,
			s_doc )

Value:

    i_module.setDoc(s_doc);\
    i_module.inject();

Inject a module with documentation override.

Deprecated

Use PY_DECLARE_MODULE_DOC and PY_INJECT_MODULE instead

Definition at line 360 of file pyobject_macros.h.

PY_EXTENSION_MODULE_EX

#define PY_EXTENSION_MODULE_EX	(		i_module,
			f_injection,
			s_doc )

Inject a python module so Python is aware of it and produce all necessary code so a module can be used as extension of Python.

A limitation in comparison with embedded modules is that the name of the module cannot be changed anymore upon injection.

Parameters

i_module	the identifier of a module declared by PY_DECLARE_MODULE
f_injection	the function that will inject all the classes for this module
s_doc	documentation of module as shown in Python (zero terminated C string)

Definition at line 378 of file pyobject_macros.h.

PY_EXTENSION_MODULE_DOC

#define PY_EXTENSION_MODULE_DOC	(		i_module,
			f_injection,
			s_doc )

Value:

    PY_EXTENSION_MODULE_EX( i_module, f_injection, s_doc)

Create an extension module with documentation.

Wraps PY_EXTENSION_MODULE_EX() with s_doc parameter.

Parameters

i_module	Module identifier declared by PY_DECLARE_MODULE_*()
f_injection	Injection function to call during module creation
s_doc	Module documentation string (const char* string with static storage duration)

Definition at line 393 of file pyobject_macros.h.

PY_EXTENSION_MODULE

#define PY_EXTENSION_MODULE	(		i_module,
			f_injection )

Value:

    PY_EXTENSION_MODULE_EX( i_module, f_injection, 0)

Create an extension module (no documentation).

Wraps PY_EXTENSION_MODULE_EX() with s_doc = nullptr.

Parameters

i_module	Module identifier declared by PY_DECLARE_MODULE_*()
f_injection	Injection function to call during module creation

Definition at line 403 of file pyobject_macros.h.