Single-phase initialization¶

The module initialization function may create and return the module objectdirectly. This is referred to as “single-phase initialization”, and uses oneof the following two module creation functions:

PyObject*PyModule_Create(PyModuleDef*def)¶

Return value: New reference.

Create a new module object, given the definition indef. This behaveslikePyModule_Create2() withmodule_api_version set toPYTHON_API_VERSION.

PyObject*PyModule_Create2(PyModuleDef*def,intmodule_api_version)¶

Return value: New reference. Part of theStable ABI.

Create a new module object, given the definition indef, assuming theAPI versionmodule_api_version. If that version does not match the versionof the running interpreter, aRuntimeWarning is emitted.

ReturnNULL with an exception set on error.

Note

Most uses of this function should be usingPyModule_Create()instead; only use this if you are sure you need it.

Before it is returned from in the initialization function, the resulting moduleobject is typically populated using functions likePyModule_AddObjectRef().

Multi-phase initialization¶

An alternate way to specify extensions is to request “multi-phase initialization”.Extension modules created this way behave more like Python modules: theinitialization is split between thecreation phase, when the module objectis created, and theexecution phase, when it is populated.The distinction is similar to the__new__() and__init__() methodsof classes.

Unlike modules created using single-phase initialization, these modules are notsingletons: if thesys.modules entry is removed and the module is re-imported,a new module object is created, and the old module is subject to normal garbagecollection – as with Python modules.By default, multiple modules created from the same definition should beindependent: changes to one should not affect the others.This means that all state should be specific to the module object (using e.g.usingPyModule_GetState()), or its contents (such as the module’s__dict__ or individual classes created withPyType_FromSpec()).

All modules created using multi-phase initialization are expected to supportsub-interpreters. Making sure multiple modulesare independent is typically enough to achieve this.

To request multi-phase initialization, the initialization function(PyInit_modulename) returns aPyModuleDef instance with non-emptym_slots. Before it is returned, thePyModuleDefinstance must be initialized with the following function:

PyObject*PyModuleDef_Init(PyModuleDef*def)¶

Return value: Borrowed reference. Part of theStable ABI since version 3.5.

Ensures a module definition is a properly initialized Python object thatcorrectly reports its type and reference count.

Returnsdef cast toPyObject*, orNULL if an error occurred.

Added in version 3.5.

Them_slots member of the module definition must point to an array ofPyModuleDef_Slot structures:

typePyModuleDef_Slot¶

intslot¶

A slot ID, chosen from the available values explained below.

void*value¶

Value of the slot, whose meaning depends on the slot ID.

Added in version 3.5.

Them_slots array must be terminated by a slot with id 0.

The available slot types are:

Py_mod_create¶

Specifies a function that is called to create the module object itself.Thevalue pointer of this slot must point to a function of the signature:

PyObject*create_module(PyObject*spec,PyModuleDef*def)¶

The function receives aModuleSpecinstance, as defined inPEP 451, and the module definition.It should return a new module object, or set an errorand returnNULL.

This function should be kept minimal. In particular, it should notcall arbitrary Python code, as trying to import the same module again mayresult in an infinite loop.

MultiplePy_mod_create slots may not be specified in one moduledefinition.

IfPy_mod_create is not specified, the import machinery will createa normal module object usingPyModule_New(). The name is taken fromspec, not the definition, to allow extension modules to dynamically adjustto their place in the module hierarchy and be imported under differentnames through symlinks, all while sharing a single module definition.

There is no requirement for the returned object to be an instance ofPyModule_Type. Any type can be used, as long as it supportssetting and getting import-related attributes.However, onlyPyModule_Type instances may be returned if thePyModuleDef has non-NULLm_traverse,m_clear,m_free; non-zerom_size; or slots other thanPy_mod_create.

Py_mod_exec¶

Specifies a function that is called toexecute the module.This is equivalent to executing the code of a Python module: typically,this function adds classes and constants to the module.The signature of the function is:

intexec_module(PyObject*module)¶

If multiplePy_mod_exec slots are specified, they are processed in theorder they appear in them_slots array.

Py_mod_multiple_interpreters¶

Specifies one of the following values:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED¶

The module does not support being imported in subinterpreters.

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED¶

The module supports being imported in subinterpreters,but only when they share the main interpreter’s GIL.(SeeIsolating Extension Modules.)

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED¶

The module supports being imported in subinterpreters,even when they have their own GIL.(SeeIsolating Extension Modules.)

This slot determines whether or not importing this modulein a subinterpreter will fail.

MultiplePy_mod_multiple_interpreters slots may not be specifiedin one module definition.

IfPy_mod_multiple_interpreters is not specified, the importmachinery defaults toPy_MOD_MULTIPLE_INTERPRETERS_SUPPORTED.

Added in version 3.12.

Py_mod_gil¶

Specifies one of the following values:

Py_MOD_GIL_USED¶

The module depends on the presence of the global interpreter lock (GIL),and may access global state without synchronization.

Py_MOD_GIL_NOT_USED¶

The module is safe to run without an active GIL.

This slot is ignored by Python builds not configured with--disable-gil. Otherwise, it determines whether or not importingthis module will cause the GIL to be automatically enabled. SeeFree-threaded CPython for more detail.

MultiplePy_mod_gil slots may not be specified in one module definition.

IfPy_mod_gil is not specified, the import machinery defaults toPy_MOD_GIL_USED.

Added in version 3.13.

SeePEP 489 for more details on multi-phase initialization.

Low-level module creation functions¶

The following functions are called under the hood when using multi-phaseinitialization. They can be used directly, for example when creating moduleobjects dynamically. Note that bothPyModule_FromDefAndSpec andPyModule_ExecDef must be called to fully initialize a module.

PyObject*PyModule_FromDefAndSpec(PyModuleDef*def,PyObject*spec)¶

Return value: New reference.

Create a new module object, given the definition indef and theModuleSpecspec. This behaves likePyModule_FromDefAndSpec2()withmodule_api_version set toPYTHON_API_VERSION.

Added in version 3.5.

PyObject*PyModule_FromDefAndSpec2(PyModuleDef*def,PyObject*spec,intmodule_api_version)¶

Return value: New reference. Part of theStable ABI since version 3.7.

Create a new module object, given the definition indef and theModuleSpecspec, assuming the API versionmodule_api_version.If that version does not match the version of the running interpreter,aRuntimeWarning is emitted.

ReturnNULL with an exception set on error.

Note

Most uses of this function should be usingPyModule_FromDefAndSpec()instead; only use this if you are sure you need it.

Added in version 3.5.

intPyModule_ExecDef(PyObject*module,PyModuleDef*def)¶

Part of theStable ABI since version 3.7.

Process any execution slots (Py_mod_exec) given indef.

Added in version 3.5.

intPyModule_SetDocString(PyObject*module,constchar*docstring)¶

Part of theStable ABI since version 3.7.

Set the docstring formodule todocstring.This function is called automatically when creating a module fromPyModuleDef, using eitherPyModule_Create orPyModule_FromDefAndSpec.

Added in version 3.5.

intPyModule_AddFunctions(PyObject*module,PyMethodDef*functions)¶

Part of theStable ABI since version 3.7.

Add the functions from theNULL terminatedfunctions array tomodule.Refer to thePyMethodDef documentation for details on individualentries (due to the lack of a shared module namespace, module level“functions” implemented in C typically receive the module as their firstparameter, making them similar to instance methods on Python classes).This function is called automatically when creating a module fromPyModuleDef, using eitherPyModule_Create orPyModule_FromDefAndSpec.

Added in version 3.5.

Support functions¶

The module initialization function (if using single phase initialization) ora function called from a module execution slot (if using multi-phaseinitialization), can use the following functions to help initialize the modulestate:

intPyModule_AddObjectRef(PyObject*module,constchar*name,PyObject*value)¶

Part of theStable ABI since version 3.10.

Add an object tomodule asname. This is a convenience function whichcan be used from the module’s initialization function.

On success, return0. On error, raise an exception and return-1.

Example usage:

staticintadd_spam(PyObject*module,intvalue){PyObject*obj=PyLong_FromLong(value);if(obj==NULL){return-1;}intres=PyModule_AddObjectRef(module,"spam",obj);Py_DECREF(obj);returnres;}

To be convenient, the function acceptsNULLvalue with an exceptionset. In this case, return-1 and just leave the raised exceptionunchanged.

The example can also be written without checking explicitly ifobj isNULL:

staticintadd_spam(PyObject*module,intvalue){PyObject*obj=PyLong_FromLong(value);intres=PyModule_AddObjectRef(module,"spam",obj);Py_XDECREF(obj);returnres;}

Note thatPy_XDECREF() should be used instead ofPy_DECREF() inthis case, sinceobj can beNULL.

The number of differentname strings passed to this functionshould be kept small, usually by only using statically allocated stringsasname.For names that aren’t known at compile time, prefer callingPyUnicode_FromString() andPyObject_SetAttr() directly.For more details, seePyUnicode_InternFromString(), which may beused internally to create a key object.

Added in version 3.10.

intPyModule_Add(PyObject*module,constchar*name,PyObject*value)¶

Part of theStable ABI since version 3.13.

Similar toPyModule_AddObjectRef(), but “steals” a referencetovalue.It can be called with a result of function that returns a new referencewithout bothering to check its result or even saving it to a variable.

Example usage:

if(PyModule_Add(module,"spam",PyBytes_FromString(value))<0){gotoerror;}

Added in version 3.13.

intPyModule_AddObject(PyObject*module,constchar*name,PyObject*value)¶

Part of theStable ABI.

Similar toPyModule_AddObjectRef(), but steals a reference tovalue on success (if it returns0).

The newPyModule_Add() orPyModule_AddObjectRef()functions are recommended, since it iseasy to introduce reference leaks by misusing thePyModule_AddObject() function.

Note

Unlike other functions that steal references,PyModule_AddObject()only releases the reference tovalueon success.

This means that its return value must be checked, and calling code mustPy_XDECREF()value manually on error.

Example usage:

PyObject*obj=PyBytes_FromString(value);if(PyModule_AddObject(module,"spam",obj)<0){// If 'obj' is not NULL and PyModule_AddObject() failed,// 'obj' strong reference must be deleted with Py_XDECREF().// If 'obj' is NULL, Py_XDECREF() does nothing.Py_XDECREF(obj);gotoerror;}// PyModule_AddObject() stole a reference to obj:// Py_XDECREF(obj) is not needed here.

Deprecated since version 3.13:PyModule_AddObject() issoft deprecated.

intPyModule_AddIntConstant(PyObject*module,constchar*name,longvalue)¶

Part of theStable ABI.

Add an integer constant tomodule asname. This convenience function can beused from the module’s initialization function.Return-1 with an exception set on error,0 on success.

This is a convenience function that callsPyLong_FromLong() andPyModule_AddObjectRef(); see their documentation for details.

intPyModule_AddStringConstant(PyObject*module,constchar*name,constchar*value)¶

Part of theStable ABI.

Add a string constant tomodule asname. This convenience function can beused from the module’s initialization function. The stringvalue must beNULL-terminated.Return-1 with an exception set on error,0 on success.

This is a convenience function that callsPyUnicode_InternFromString() andPyModule_AddObjectRef();see their documentation for details.

PyModule_AddIntMacro(module,macro)¶

Add an int constant tomodule. The name and the value are taken frommacro. For examplePyModule_AddIntMacro(module,AF_INET) adds the intconstantAF_INET with the value ofAF_INET tomodule.Return-1 with an exception set on error,0 on success.

PyModule_AddStringMacro(module,macro)¶

Add a string constant tomodule.

intPyModule_AddType(PyObject*module,PyTypeObject*type)¶

Part of theStable ABI since version 3.10.

Add a type object tomodule.The type object is finalized by calling internallyPyType_Ready().The name of the type object is taken from the last component oftp_name after dot.Return-1 with an exception set on error,0 on success.

Added in version 3.9.

intPyUnstable_Module_SetGIL(PyObject*module,void*gil)¶

This isUnstable API. It may change without warning in minor releases.

Indicate thatmodule does or does not support running without the globalinterpreter lock (GIL), using one of the values fromPy_mod_gil. It must be called duringmodule’s initializationfunction. If this function is not called during module initialization, theimport machinery assumes the module does not support running without theGIL. This function is only available in Python builds configured with--disable-gil.Return-1 with an exception set on error,0 on success.

Added in version 3.13.