Module definition¶

Modules created using the C API are typically defined using anarray ofslots.The slots provide a “description” of how a module should be created.

The slots array is usually used to define an extension module’s “main”module object (seeDefining extension modules for details).It can also be used tocreate extension modules dynamically.

Unless specified otherwise, the same slot ID may not be repeatedin an array of slots.

typePyModuleDef_Slot¶

Part of theStable ABI (including all members) since version 3.5.

intslot¶

A slot ID, chosen from the availablePy_mod_* values explained below.

An ID of 0 marks the end of aPyModuleDef_Slot array.

void*value¶

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

The value may not be NULL.To leave a slot out, omit thePyModuleDef_Slot entry entirely.

Added in version 3.5.

Module state¶

Extension modules can havemodule state – apiece of memory that is allocated on module creation,and freed when the module object is deallocated.The module state is specified usingdedicated slots.

A typical use of module state is storing an exception type – or indeedanytype object defined by the module –

Unlike the module’s Python attributes, Python code cannot replace or deletedata stored in module state.

Keeping per-module information in attributes and module state, rather than instatic globals, makes module objectsisolated and safer for use inmultiple sub-interpreters.It also helps Python do an orderly clean-up when it shuts down.

Extensions that keep references to Python objects as part of module state mustimplementPy_mod_state_traverse andPy_mod_state_clearfunctions to avoid reference leaks.

To retrieve the state from a given module, use the following functions:

void*PyModule_GetState(PyObject*module)¶

Part of theStable ABI.

Return the “state” of the module, that is, a pointer to the block of memoryallocated at module creation time, orNULL. SeePy_mod_state_size.

On error, returnNULL with an exception set.UsePyErr_Occurred() to tell this case apart from missingmodule state.

intPyModule_GetStateSize(PyObject*,Py_ssize_t*result)¶

Part of theStable ABI since version 3.15.

Set*result to the size of the module’s state, as specified usingPy_mod_state_size (orPyModuleDef.m_size),and return 0.

On error, set*result to -1, and return -1 with an exception set.

Added in version 3.15.0a2 (unreleased).

PyObject*module=<themoduleinquestion>void*module_token;if(PyModule_GetToken(module,&module_token)<0){returnNULL;}if(module_token!=your_token){PyErr_SetString(PyExc_ValueError,"unexpected module")returnNULL;}// This module's state has the expected memory layout; it's safe to caststructmy_statestate=(structmy_state*)PyModule_GetState(module)

Creating extension modules dynamically¶

The following functions may be used to create an extension module dynamically,rather than from an extension’sexport hook.

PyObject*PyModule_FromSlotsAndSpec(constPyModuleDef_Slot*slots,PyObject*spec)¶

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

Create a new module object, given an array ofslotsand theModuleSpecspec.

Theslots argument must point to an array ofPyModuleDef_Slotstructures, terminated by an entry slot with slot ID of 0(typically written as{0} or{0,NULL} in C).Theslots argument may not beNULL.

Thespec argument may be anyModuleSpec-like object, as describedinPy_mod_create documentation.Currently, thespec must have aname attribute.

On success, return the new module.On error, returnNULL with an exception set.

Note that this does not process the module’s execution slot(Py_mod_exec).BothPyModule_FromSlotsAndSpec() andPyModule_Exec()must be called to fully initialize a module.(See alsoMulti-phase initialization.)

Theslots array only needs to be valid for the duration of thePyModule_FromSlotsAndSpec() call.In particular, it may be heap-allocated.

Added in version 3.15.0a2 (unreleased).

intPyModule_Exec(PyObject*module)¶

Part of theStable ABI since version 3.15.

Execute thePy_mod_exec slot(s) of the givenmodule.

On success, return 0.On error, return -1 with an exception set.

For clarity: Ifmodule has no slots, for example if it useslegacy single-phase initialization,this function does nothing and returns 0.

Added in version 3.15.0a2 (unreleased).

Module definition struct¶

Traditionally, extension modules were defined using amodule definitionas the “description” of how a module should be created.Rather than using an array ofslots directly,the definition has dedicated members for most common functionality,and allows additional slots as an extension mechanism.

This way of defining modules is still available and there are no plans toremove it.

typePyModuleDef¶

Part of theStable ABI (including all members).

The module definition struct, which holds information needed to createa module object.

This structure must be statically allocated (or be otherwise guaranteedto be valid while any modules created from it exist).Usually, there is only one variable of this type for each extension moduledefined this way.

PyModuleDef_Basem_base¶

Always initialize this member toPyModuleDef_HEAD_INIT:

typePyModuleDef_Base¶

Part of theStable ABI (including all members).

The type ofPyModuleDef.m_base.

PyModuleDef_HEAD_INIT¶

The required initial value forPyModuleDef.m_base.

constchar*m_name¶

Corresponds to thePy_mod_name slot.

constchar*m_doc¶

These members correspond to thePy_mod_doc slot.Setting this to NULL is equivalent to omitting the slot.

Py_ssize_tm_size¶

Corresponds to thePy_mod_state_size slot.Setting this to zero is equivalent to omitting the slot.

When usinglegacy single-phase initializationor when creating modules dynamically usingPyModule_Create()orPyModule_Create2(),m_size may be set to -1.This indicates that the module does not support sub-interpreters,because it has global state.

PyMethodDef*m_methods¶

Corresponds to thePy_mod_methods slot.Setting this to NULL is equivalent to omitting the slot.

PyModuleDef_Slot*m_slots¶

An array of additional slots, terminated by a{0,NULL} entry.

This array may not contain slots corresponding toPyModuleDefmembers.For example, you cannot usePy_mod_name inm_slots;the module name must be given asPyModuleDef.m_name.

Changed in version 3.5:Prior to version 3.5, this member was always set toNULL,and was defined as:

inquirym_reload¶

traverseprocm_traverse¶

inquirym_clear¶

freefuncm_free¶

These members correspond to thePy_mod_state_traverse,Py_mod_state_clear, andPy_mod_state_free slots,respectively.

Setting these members to NULL is equivalent to omitting thecorresponding slots.

Changed in version 3.9:m_traverse,m_clear andm_freefunctions are longer called before the module state is allocated.

The following API can be used to create modules from aPyModuleDefstruct:

PyObject*PyModule_Create(PyModuleDef*def)¶

Return value: New reference.

Create a new module object, given the definition indef.This is a macro that callsPyModule_Create2() withmodule_api_version set toPYTHON_API_VERSION, ortoPYTHON_ABI_VERSION if using thelimited API.

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.

This function does not support slots.Them_slots member ofdef must beNULL.

Note

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

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

Return value: New reference.

This macro callsPyModule_FromDefAndSpec2() withmodule_api_version set toPYTHON_API_VERSION, ortoPYTHON_ABI_VERSION if using thelimited API.

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 that this does not process execution slots (Py_mod_exec).BothPyModule_FromDefAndSpec andPyModule_ExecDef must be calledto fully initialize a module.

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.

PYTHON_API_VERSION¶

The C API version. Defined for backwards compatibility.

Currently, this constant is not updated in new Python versions, and is notuseful for versioning. This may change in the future.

PYTHON_ABI_VERSION¶

Defined as3 for backwards compatibility.

Currently, this constant is not updated in new Python versions, and is notuseful for versioning. This may change in the future.

Support functions¶

The following functions are provided to help initialize a module object.They are intended for a module’s execution slot (Py_mod_exec),the initialization function for legacysingle-phase initialization,or code that creates modules dynamically.

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.

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 (such as when usingMulti-phase initialization,PyModule_Create, orPyModule_FromDefAndSpec).Some module authors may prefer defining functions in multiplePyMethodDef arrays; in that case they should call this functiondirectly.

Thefunctions array must be statically allocated (or otherwise guaranteedto outlive the module object).

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 (such as when usingMulti-phase initialization,PyModule_Create, orPyModule_FromDefAndSpec).

Added in version 3.5.

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 when usingLegacy single-phase initialization.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.