Module Objects

PyTypeObject PyModule_Type

Part of the Stable ABI.

This instance of PyTypeObject represents the Python module type. This is exposed to Python programs as types.ModuleType.

int PyModule_Check(PyObject *p)

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

int PyModule_CheckExact(PyObject *p)

Return true if p is a module object, but not a subtype of PyModule_Type. This function always succeeds.

PyObject *PyModule_NewObject(PyObject *name)

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

Return a new module object with module.__name__ set to name. The module’s __name__, __doc__, __package__ and __loader__ attributes are filled in (all but __name__ are set to None). The caller is responsible for setting a __file__ attribute.

Return NULL with an exception set on error.

Added in version 3.3.

Changed in version 3.4: __package__ and __loader__ are now set to None.

PyObject *PyModule_New(const char *name)

Return value: New reference. Part of the Stable ABI.

Similar to PyModule_NewObject(), but the name is a UTF-8 encoded string instead of a Unicode object.

PyObject *PyModule_GetDict(PyObject *module)

Return value: Borrowed reference. Part of the Stable ABI.

Return the dictionary object that implements module’s namespace; this object is the same as the __dict__ attribute of the module object. If module is not a module object (or a subtype of a module object), SystemError is raised and NULL is returned.

It is recommended extensions use other PyModule_* and PyObject_* functions rather than directly manipulate a module’s __dict__.

The returned reference is borrowed from the module; it is valid until the module is destroyed.

PyObject *PyModule_GetNameObject(PyObject *module)

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

Return module’s __name__ value. If the module does not provide one, or if it is not a string, SystemError is raised and NULL is returned.

Added in version 3.3.

const char *PyModule_GetName(PyObject *module)

Part of the Stable ABI.

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

The returned buffer is only valid until the module is renamed or destroyed. Note that Python code may rename a module by setting its __name__ attribute.

void *PyModule_GetState(PyObject *module)

Part of the Stable ABI.

Return the “state” of the module, that is, a pointer to the block of memory allocated at module creation time, or NULL. See PyModuleDef.m_size.

PyModuleDef *PyModule_GetDef(PyObject *module)

Part of the Stable ABI.

Return a pointer to the PyModuleDef struct from which the module was created, or NULL if the module wasn’t created from a definition.

On error, return NULL with an exception set. Use PyErr_Occurred() to tell this case apart from a missing PyModuleDef.

PyObject *PyModule_GetFilenameObject(PyObject *module)

Return value: New reference. Part of the Stable ABI.

Return the name of the file from which module was loaded using module’s __file__ attribute. If this is not defined, or if it is not a string, raise SystemError and return NULL; otherwise return a reference to a Unicode object.

Added in version 3.2.

const char *PyModule_GetFilename(PyObject *module)

Part of the Stable ABI.

Similar to PyModule_GetFilenameObject() but return the filename encoded to ‘utf-8’.

The returned buffer is only valid until the module’s __file__ attribute is reassigned or the module is destroyed.

Deprecated since version 3.2: PyModule_GetFilename() raises UnicodeEncodeError on unencodable filenames, use PyModule_GetFilenameObject() instead.

Module definitions

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

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

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

Unlike PyModule_New(), the definition allows management of module state – a piece of memory that is allocated and cleared together with the module object. Unlike the module’s Python attributes, Python code cannot replace or delete data stored in module state.

type PyModuleDef

Part of the Stable ABI (including all members).

The module definition struct, which holds all information needed to create a module object. This structure must be statically allocated (or be otherwise guaranteed to be valid while any modules created from it exist). Usually, there is only one variable of this type for each extension module.

PyModuleDef_Base m_base

Always initialize this member to PyModuleDef_HEAD_INIT.

const char *m_name

Name for the new module.

const char *m_doc

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

Py_ssize_t m_size