### Navigation

- index
- modules |
- next |
- previous |
- Python v3.1 documentation »
- Python/C API Reference Manual »
- Concrete Objects Layer »

# 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_New`(const char *name)
  Return value: New reference.

  Return a new module object with the `__name__` attribute set to name. Only the module’s `__doc__` and `__name__` attributes are filled in; the caller is responsible for providing a `__file__` attribute.

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__`.

char* `PyModule_GetName`(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.

char* `PyModule_GetFilename`(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 string, raise `SystemError` and return NULL.

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`.

## 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.

  Note

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

`PyModuleDef`

  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`

    If the module object needs additional memory, this should be set to the number of bytes to allocate; a pointer to the block of memory can be retrieved with `PyModule_GetState`. If no memory is needed, set this to `-1`.

    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.

  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_AddConstant(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.

### Navigation

- index
- modules |
- next |
- previous |
- Python v3.1 documentation »
- Python/C API Reference Manual »
- Concrete Objects Layer »