This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

Module Objects

There are only a few functions special to module objects.

PyTypeObject PyModule_Type

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.

int PyModule_CheckExact(PyObject *p)

Return true if p is a module object, but not a subtype of PyModule_Type.

PyObject* PyModule_NewObject(PyObject *name)

Return a new module object with the __name__ attribute 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 providing a __file__ attribute.

New in version 3.3.

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

PyObject* PyModule_New(const char *name)
Return value: New reference.

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

PyObject* PyModule_GetDict(PyObject *module)
Return value: Borrowed reference.

Return the dictionary object that implements module‘s namespace; this object is the same as the __dict__ attribute of the module object. This function never fails. It is recommended extensions use other PyModule_*() and PyObject_*() functions rather than directly manipulate a module’s __dict__.

PyObject* PyModule_GetNameObject(PyObject *module)

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.

New in version 3.3.

char* PyModule_GetName(PyObject *module)

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

PyObject* PyModule_GetFilenameObject(PyObject *module)

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 unicode string, raise SystemError and return NULL; otherwise return a reference to a Unicode object.

New in version 3.2.

char* PyModule_GetFilename(PyObject *module)

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

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

void* PyModule_GetState(PyObject *module)

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)

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

PyObject* PyState_FindModule(PyModuleDef *def)

Returns the module object that was created from def for the current interpreter. This method requires that the module object has been attached to the interpreter state with PyState_AddModule() beforehand. In case the corresponding module object is not found or has not been attached to the interpreter state yet, it returns NULL.

int PyState_AddModule(PyObject *module, PyModuleDef *def)

Attaches the module object passed to the function to the interpreter state. This allows the module object to be accessible via PyState_FindModule().

New in version 3.3.

int PyState_RemoveModule(PyModuleDef *def)

Removes the module object created from def from the interpreter state.

New in version 3.3.

Initializing C modules

These functions are usually used in the module initialization function.

PyObject* PyModule_Create(PyModuleDef *module)

Create a new module object, given the definition in module. This behaves like PyModule_Create2() with module_api_version set to PYTHON_API_VERSION.

PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)

Create a new module object, given the definition in module, assuming the API version module_api_version. If that version does not match the version of the running interpreter, a RuntimeWarning is emitted.


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


This struct holds all information that is needed to create a module object. There is usually only one static variable of that type for each module, which is statically initialized and then passed to PyModule_Create() in the module initialization function.

PyModuleDef_Base m_base

Always initialize this member to PyModuleDef_HEAD_INIT.

char* m_name

Name for the new module.

char* m_doc

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

Py_ssize_t m_size

Some modules allow re-initialization (calling their PyInit_* function more than once). These modules should keep their state in a per-module memory area that can be retrieved with PyModule_GetState().

This memory should be used, rather than static globals, to hold per-module state, since it is then safe for use in multiple sub-interpreters. It is freed when the module object is deallocated, after the m_free function has been called, if present.

Setting m_size to -1 means that the module can not be re-initialized because it has global state. Setting it to a non-negative value means that the module can be re-initialized and specifies the additional amount of memory it requires for its state.

See PEP 3121 for more details.

PyMethodDef* m_methods

A pointer to a table of module-level functions, described by PyMethodDef values. Can be NULL if no functions are present.

inquiry m_reload

Currently unused, should be NULL.

traverseproc m_traverse

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

inquiry m_clear

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

freefunc m_free

A function to call during deallocation of the module object, or NULL if not needed.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)

Add an object to module as name. This is a convenience function which can be used from the module’s initialization function. This steals a reference to value. Return -1 on error, 0 on success.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

Add an integer constant to module as name. This convenience function can be used from the module’s initialization function. Return -1 on error, 0 on success.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)

Add a string constant to module as name. This convenience function can be used from the module’s initialization function. The string value must be null-terminated. Return -1 on error, 0 on success.

int PyModule_AddIntMacro(PyObject *module, macro)

Add an int constant to module. The name and the value are taken from macro. For example PyModule_AddIntMacro(module, AF_INET) adds the int constant AF_INET with the value of AF_INET to module. Return -1 on error, 0 on success.

int PyModule_AddStringMacro(PyObject *module, macro)

Add a string constant to module.

Table Of Contents

Previous topic

File Objects

Next topic

Iterator Objects

This Page