Module Objects¶

PyTypeObjectPyModule_Type¶

Part of theStable ABI.

This instance ofPyTypeObject represents the Python module type. Thisis exposed to Python programs astypes.ModuleType.

intPyModule_Check(PyObject*p)¶

Return true ifp is a module object, or a subtype of a module object.This function always succeeds.

intPyModule_CheckExact(PyObject*p)¶

Return true ifp is a module object, but not a subtype ofPyModule_Type. This function always succeeds.

PyObject*PyModule_NewObject(PyObject*name)¶

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

Return a new module object withmodule.__name__ set toname.The module’s__name__,__doc__,__package__ and__loader__ attributes arefilled in (all but__name__ are set toNone). The caller isresponsible for setting a__file__ attribute.

ReturnNULL with an exception set on error.

Added in version 3.3.

Changed in version 3.4:__package__ and__loader__ are now set toNone.

PyObject*PyModule_New(constchar*name)¶

Return value: New reference. Part of theStable ABI.

Similar toPyModule_NewObject(), but the name is a UTF-8 encodedstring instead of a Unicode object.

PyObject*PyModule_GetDict(PyObject*module)¶

Return value: Borrowed reference. Part of theStable ABI.

Return the dictionary object that implementsmodule’s namespace; this objectis the same as the__dict__ attribute of the module object.Ifmodule is not a module object (or a subtype of a module object),SystemError is raised andNULL is returned.

It is recommended extensions use otherPyModule_* andPyObject_* functions rather than directly manipulate a module’s__dict__.

PyObject*PyModule_GetNameObject(PyObject*module)¶

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

Returnmodule’s__name__ value. If the module does notprovide one, or if it is not a string,SystemError is raised andNULL is returned.

Added in version 3.3.

constchar*PyModule_GetName(PyObject*module)¶

Part of theStable ABI.

Similar toPyModule_GetNameObject() but return the name encoded to'utf-8'.

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. SeePyModuleDef.m_size.

PyModuleDef*PyModule_GetDef(PyObject*module)¶

Part of theStable ABI.

Return a pointer to thePyModuleDef struct from which the module wascreated, orNULL if the module wasn’t created from a definition.

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

PyObject*PyModule_GetFilenameObject(PyObject*module)¶

Return value: New reference. Part of theStable ABI.

Return the name of the file from whichmodule was loaded usingmodule’s__file__ attribute. If this is not defined, or if it is not astring, raiseSystemError and returnNULL; otherwise returna reference to a Unicode object.

Added in version 3.2.

constchar*PyModule_GetFilename(PyObject*module)¶

Part of theStable ABI.

Similar toPyModule_GetFilenameObject() but return the filenameencoded to ‘utf-8’.

Deprecated since version 3.2:PyModule_GetFilename() raisesUnicodeEncodeError onunencodable filenames, usePyModule_GetFilenameObject() instead.

Module definitions¶

The functions in the previous section work on any module object, includingmodules imported from Python code.

Modules defined using the C API typically use amodule definition,PyModuleDef – a statically allocated, constant “description” ofhow a module should be created.

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

UnlikePyModule_New(), the definition allows management ofmodule state – a piece of memory that is allocated and cleared togetherwith the module object.Unlike the module’s Python attributes, Python code cannot replace or deletedata stored in module state.

typePyModuleDef¶

Part of theStable ABI (including all members).

The module definition struct, which holds all 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 module.

PyModuleDef_Basem_base¶

Always initialize this member toPyModuleDef_HEAD_INIT.

constchar*m_name¶

Name for the new module.

constchar*m_doc¶

Docstring for the module; usually a docstring variable created withPyDoc_STRVAR is used.

Py_ssize_tm_size¶

Module state may be kept in a per-module memory area that can beretrieved withPyModule_GetState(), rather than in static globals.This makes modules safe for use in multiple sub-interpreters.

This memory area is allocated based onm_size on module creation,and freed when the module object is deallocated, after them_free function has been called, if present.

Setting it to a non-negative value means that the module can bere-initialized and specifies the additional amount of memory it requiresfor its state.

Settingm_size to-1 means that the module does not supportsub-interpreters, because it has global state.Negativem_size is only allowed when usinglegacy single-phase initializationor whencreating modules dynamically.

SeePEP 3121 for more details.

PyMethodDef*m_methods¶

A pointer to a table of module-level functions, described byPyMethodDef values. Can beNULL if no functions are present.

PyModuleDef_Slot*m_slots¶

An array of slot definitions for multi-phase initialization, terminated bya{0,NULL} entry.When using legacy single-phase initialization,m_slots must beNULL.

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

inquirym_reload¶

traverseprocm_traverse¶

A traversal function to call during GC traversal of the module object, orNULL if not needed.

This function is not called if the module state was requested but is notallocated yet. This is the case immediately after the module is createdand before the module is executed (Py_mod_exec function). Moreprecisely, this function is not called ifm_size is greaterthan 0 and the module state (as returned byPyModule_GetState())isNULL.

Changed in version 3.9:No longer called before the module state is allocated.

inquirym_clear¶

A clear function to call during GC clearing of the module object, orNULL if not needed.

This function is not called if the module state was requested but is notallocated yet. This is the case immediately after the module is createdand before the module is executed (Py_mod_exec function). Moreprecisely, this function is not called ifm_size is greaterthan 0 and the module state (as returned byPyModule_GetState())isNULL.

LikePyTypeObject.tp_clear, this function is notalwayscalled before a module is deallocated. For example, when referencecounting is enough to determine that an object is no longer used,the cyclic garbage collector is not involved andm_free is called directly.

Changed in version 3.9:No longer called before the module state is allocated.

freefuncm_free¶

A function to call during deallocation of the module object, orNULLif not needed.

This function is not called if the module state was requested but is notallocated yet. This is the case immediately after the module is createdand before the module is executed (Py_mod_exec function). Moreprecisely, this function is not called ifm_size is greaterthan 0 and the module state (as returned byPyModule_GetState())isNULL.

Changed in version 3.9:No longer called before the module state is allocated.

Creating extension modules dynamically¶

The following functions may be used to create a module outside of anextension’sinitialization function.They are also used insingle-phase initialization.

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 modulestate.They are intended for a module’s execution slots (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.

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.