模組物件¶

PyTypeObject PyModule_Type¶: 為穩定 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)¶

回傳值：新的參照。 為穩定 ABI 的一部分自 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.

在失敗時回傳 NULL 並設定例外。

在 3.3 版被加入.

在 3.4 版的變更: __package__ 和 __loader__ 現在被設為 None。

PyObject *PyModule_New(const char *name)¶: 回傳值：新的參照。 為穩定 ABI 的一部分.
類似於 PyModule_NewObject()，但名稱是以 UTF-8 編碼的字串，而非 Unicode 物件。

PyObject *PyModule_GetDict(PyObject *module)¶

回傳值：借用參照。 為穩定 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)¶: 回傳值：新的參照。 為穩定 ABI 的一部分自 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.

在 3.3 版被加入.

const char *PyModule_GetName(PyObject *module)¶

為穩定 ABI 的一部分.

類似於 PyModule_GetNameObject()，但回傳以 '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)¶: 為穩定 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)¶

為穩定 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)¶: 回傳值：新的參照。 為穩定 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.

在 3.2 版被加入.

const char *PyModule_GetFilename(PyObject *module)¶

為穩定 ABI 的一部分.

類似於 PyModule_GetFilenameObject()，但回傳以 'utf-8' 編碼的檔案名稱。

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

在 3.2 版之後被棄用: PyModule_GetFilename() raises UnicodeEncodeError on unencodable filenames, use PyModule_GetFilenameObject() instead.

模組定義¶

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¶

為穩定 ABI 的一部分（包含所有成員）.

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¶

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

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

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.

Setting m_size to -1 means that the module does not support sub-interpreters, because it has global state. Negative m_size is only allowed when using legacy single-phase initialization or when creating modules dynamically.

更多詳情請見 PEP 3121。

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

PyModuleDef_Slot *m_slots¶

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

在 3.5 版的變更: 在 3.5 版本之前，這個成員總是被設為 NULL，並被定義為：

inquiry m_reload¶

traverseproc m_traverse¶

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

This function is not called if the module state was requested but is not allocated yet. This is the case immediately after the module is created and before the module is executed (Py_mod_exec function). More precisely, this function is not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

在 3.9 版的變更: No longer called before the module state is allocated.

inquiry m_clear¶

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

Like PyTypeObject.tp_clear, this function is not always called before a module is deallocated. For example, when reference counting is enough to determine that an object is no longer used, the cyclic garbage collector is not involved and m_free is called directly.

在 3.9 版的變更: No longer called before the module state is allocated.

freefunc m_free¶

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

在 3.9 版的變更: No longer called before the module state is allocated.

PyTypeObject PyModuleDef_Type¶: 為穩定 ABI 的一部分自 3.5 版本開始.
The type of PyModuleDef objects.

模組槽 (Module slots)¶

type PyModuleDef_Slot¶

為穩定 ABI 的一部分（包含所有成員）自 3.5 版本開始.

int slot¶: A slot ID, chosen from the available values explained below.

void *value¶: Value of the slot, whose meaning depends on the slot ID.

在 3.5 版被加入.

The available slot types are:

Py_mod_create¶

為穩定 ABI 的一部分自 3.5 版本開始.

Specifies a function that is called to create the module object itself. The value pointer of this slot must point to a function of the signature:

PyObject *create_module(PyObject *spec, PyModuleDef *def)¶

The function receives a ModuleSpec instance, as defined in PEP 451, and the module definition. It should return a new module object, or set an error and return NULL.

This function should be kept minimal. In particular, it should not call arbitrary Python code, as trying to import the same module again may result in an infinite loop.

Multiple Py_mod_create slots may not be specified in one module definition.

If Py_mod_create is not specified, the import machinery will create a normal module object using PyModule_New(). The name is taken from spec, not the definition, to allow extension modules to dynamically adjust to their place in the module hierarchy and be imported under different names through symlinks, all while sharing a single module definition.

There is no requirement for the returned object to be an instance of PyModule_Type. Any type can be used, as long as it supports setting and getting import-related attributes. However, only PyModule_Type instances may be returned if the PyModuleDef has non-NULL m_traverse, m_clear, m_free; non-zero m_size; or slots other than Py_mod_create.

在 3.5 版被加入.

Py_mod_exec¶

為穩定 ABI 的一部分自 3.5 版本開始.

Specifies a function that is called to execute the module. This is equivalent to executing the code of a Python module: typically, this function adds classes and constants to the module. The signature of the function is:

int exec_module(PyObject *module)¶

If multiple Py_mod_exec slots are specified, they are processed in the order they appear in the m_slots array.

在 3.5 版被加入.

Py_mod_multiple_interpreters¶

為穩定 ABI 的一部分自 3.12 版本開始.

Specifies one of the following values:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED¶: The module does not support being imported in subinterpreters.

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED¶: The module supports being imported in subinterpreters, but only when they share the main interpreter's GIL. (See 隔離擴充模組.)

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED¶: The module supports being imported in subinterpreters, even when they have their own GIL. (See 隔離擴充模組.)

This slot determines whether or not importing this module in a subinterpreter will fail.

Multiple Py_mod_multiple_interpreters slots may not be specified in one module definition.

If Py_mod_multiple_interpreters is not specified, the import machinery defaults to Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED.

在 3.12 版被加入.

Py_mod_gil¶

為穩定 ABI 的一部分自 3.13 版本開始.

Specifies one of the following values:

Py_MOD_GIL_USED¶: The module depends on the presence of the global interpreter lock (GIL), and may access global state without synchronization.

Py_MOD_GIL_NOT_USED¶: The module is safe to run without an active GIL.

This slot is ignored by Python builds not configured with --disable-gil. Otherwise, it determines whether or not importing this module will cause the GIL to be automatically enabled. See Free-threaded CPython for more detail.

Multiple Py_mod_gil slots may not be specified in one module definition.

If Py_mod_gil is not specified, the import machinery defaults to Py_MOD_GIL_USED.

在 3.13 版被加入.

Creating extension modules dynamically¶

The following functions may be used to create a module outside of an extension's initialization function. They are also used in single-phase initialization.

PyObject *PyModule_Create(PyModuleDef *def)¶: 回傳值：新的參照。
Create a new module object, given the definition in def. This is a macro that calls PyModule_Create2() with module_api_version set to PYTHON_API_VERSION, or to PYTHON_ABI_VERSION if using the limited API.

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

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

在失敗時回傳 NULL 並設定例外。

This function does not support slots. The m_slots member of def must be NULL.

備註

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

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)¶: 回傳值：新的參照。
This macro calls PyModule_FromDefAndSpec2() with module_api_version set to PYTHON_API_VERSION, or to PYTHON_ABI_VERSION if using the limited API.

在 3.5 版被加入.

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def,