Module Objects — Python 3.4.3 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Python »
- 3.4.3 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_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.

  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`

    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.

### Navigation

- index
- modules |
- next |
- previous |
- Python »
- 3.4.3 Documentation »
- Python/C API Reference Manual »
- Concrete Objects Layer »