模組物件¶

PyTypeObjectPyModule_Type¶

為穩定 ABI 的一部分.

This instance ofPyTypeObject represents the Python module type. Thisis exposed to Python programs astypes.ModuleType.

intPyModule_Check(PyObject*p)¶

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

intPyModule_CheckExact(PyObject*p)¶

Return true ifp is a module object, but not a subtype ofPyModule_Type. This function always succeeds.

PyObject*PyModule_NewObject(PyObject*name)¶

回傳值：新的參照。 為穩定 ABI 的一部分 自 3.7 版本開始.

Return a new module object withmodule.__name__ set toname.The module's__name__,__doc__,__package__ and__loader__ attributes arefilled in (all but__name__ are set toNone). The caller isresponsible for setting a__file__ attribute.

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

在 3.3 版被加入.

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

PyObject*PyModule_New(constchar*name)¶

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

類似於PyModule_NewObject()，但名稱是以 UTF-8 編碼的字串，而非 Unicode 物件。

PyObject*PyModule_GetDict(PyObject*module)¶

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

Return the dictionary object that implementsmodule's namespace; this objectis the same as the__dict__ attribute of the module object.Ifmodule is not a module object (or a subtype of a module object),SystemError is raised andNULL is returned.

It is recommended extensions use otherPyModule_* andPyObject_* functions rather than directly manipulate a module's__dict__.

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

PyObject*PyModule_GetNameObject(PyObject*module)¶

回傳值：新的參照。 為穩定 ABI 的一部分 自 3.7 版本開始.

Returnmodule's__name__ value. If the module does notprovide one, or if it is not a string,SystemError is raised andNULL is returned.

在 3.3 版被加入.

constchar*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 memoryallocated at module creation time, orNULL. SeePyModuleDef.m_size.

PyModuleDef*PyModule_GetDef(PyObject*module)¶

為穩定 ABI 的一部分.

Return a pointer to thePyModuleDef struct from which the module wascreated, orNULL if the module wasn't created from a definition.

On error, returnNULL with an exception set.UsePyErr_Occurred() to tell this case apart from a missingPyModuleDef.

PyObject*PyModule_GetFilenameObject(PyObject*module)¶

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

Return the name of the file from whichmodule was loaded usingmodule's__file__ attribute. If this is not defined, or if it is not astring, raiseSystemError and returnNULL; otherwise returna reference to a Unicode object.

在 3.2 版被加入.

constchar*PyModule_GetFilename(PyObject*module)¶

為穩定 ABI 的一部分.

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

The returned buffer is only valid until the module's__file__ attributeis reassigned or the module is destroyed.

在 3.2 版之後被棄用:PyModule_GetFilename() raisesUnicodeEncodeError onunencodable filenames, usePyModule_GetFilenameObject() instead.

模組定義¶

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

Modules defined using the C API typically use amodule definition,PyModuleDef -- a statically allocated, constant “description" ofhow a module should be created.

The definition is usually used to define an extension's “main” module object(seeDefining extension modules for details).It is also used tocreate extension modules dynamically.

UnlikePyModule_New(), the definition allows management ofmodule state -- a piece of memory that is allocated and cleared togetherwith the module object.Unlike the module's Python attributes, Python code cannot replace or deletedata stored in module state.

typePyModuleDef¶

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

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

PyModuleDef_Basem_base¶

Always initialize this member toPyModuleDef_HEAD_INIT.

constchar*m_name¶

Name for the new module.

constchar*m_doc¶

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

Py_ssize_tm_size¶

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

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

Setting it to a non-negative value means that the module can bere-initialized and specifies the additional amount of memory it requiresfor its state.

Settingm_size to-1 means that the module does not supportsub-interpreters, because it has global state.Negativem_size is only allowed when usinglegacy single-phase initializationor whencreating modules dynamically.

更多詳情請見PEP 3121。

PyMethodDef*m_methods¶

A pointer to a table of module-level functions, described byPyMethodDef values. Can beNULL if no functions are present.

PyModuleDef_Slot*m_slots¶

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

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

inquirym_reload¶

traverseprocm_traverse¶

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

This function is not called if the module state was requested but is notallocated yet. This is the case immediately after the module is createdand before the module is executed (Py_mod_exec function). Moreprecisely, this function is not called ifm_size is greaterthan 0 and the module state (as returned byPyModule_GetState())isNULL.

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

inquirym_clear¶

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

This function is not called if the module state was requested but is notallocated yet. This is the case immediately after the module is createdand before the module is executed (Py_mod_exec function). Moreprecisely, this function is not called ifm_size is greaterthan 0 and the module state (as returned byPyModule_GetState())isNULL.

LikePyTypeObject.tp_clear, this function is notalwayscalled before a module is deallocated. For example, when referencecounting is enough to determine that an object is no longer used,the cyclic garbage collector is not involved andm_free is called directly.

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

freefuncm_free¶

A function to call during deallocation of the module object, orNULLif not needed.

This function is not called if the module state was requested but is notallocated yet. This is the case immediately after the module is createdand before the module is executed (Py_mod_exec function). Moreprecisely, this function is not called ifm_size is greaterthan 0 and the module state (as returned byPyModule_GetState())isNULL.

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

Creating extension modules dynamically¶

The following functions may be used to create a module outside of anextension'sinitialization function.They are also used insingle-phase initialization.

PyObject*PyModule_Create(PyModuleDef*def)¶

回傳值：新的參照。

Create a new module object, given the definition indef.This is a macro that callsPyModule_Create2() withmodule_api_version set toPYTHON_API_VERSION, ortoPYTHON_ABI_VERSION if using thelimited API.

PyObject*PyModule_Create2(PyModuleDef*def,intmodule_api_version)¶

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

Create a new module object, given the definition indef, assuming theAPI versionmodule_api_version. If that version does not match the versionof the running interpreter, aRuntimeWarning is emitted.

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

This function does not support slots.Them_slots member ofdef must beNULL.

備註

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

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

回傳值：新的參照。

This macro callsPyModule_FromDefAndSpec2() withmodule_api_version set toPYTHON_API_VERSION, ortoPYTHON_ABI_VERSION if using thelimited API.

在 3.5 版被加入.

PyObject*PyModule_FromDefAndSpec2(PyModuleDef*def,PyObject*spec,intmodule_api_version)¶

回傳值：新的參照。 為穩定 ABI 的一部分 自 3.7 版本開始.

Create a new module object, given the definition indef and theModuleSpecspec, assuming the API versionmodule_api_version.If that version does not match the version of the running interpreter,aRuntimeWarning is emitted.

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

Note that this does not process execution slots (Py_mod_exec).BothPyModule_FromDefAndSpec andPyModule_ExecDef must be calledto fully initialize a module.

備註

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

在 3.5 版被加入.

intPyModule_ExecDef(PyObject*module,PyModuleDef*def)¶

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

Process any execution slots (Py_mod_exec) given indef.

在 3.5 版被加入.

PYTHON_API_VERSION¶

The C API version. Defined for backwards compatibility.

Currently, this constant is not updated in new Python versions, and is notuseful for versioning. This may change in the future.

PYTHON_ABI_VERSION¶

Defined as3 for backwards compatibility.

Currently, this constant is not updated in new Python versions, and is notuseful for versioning. This may change in the future.

支援的函式¶

The following functions are provided to help initialize a modulestate.They are intended for a module's execution slots (Py_mod_exec),the initialization function for legacysingle-phase initialization,or code that creates modules dynamically.

intPyModule_AddObjectRef(PyObject*module,constchar*name,PyObject*value)¶

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

Add an object tomodule asname. This is a convenience function whichcan be used from the module's initialization function.

On success, return0. On error, raise an exception and return-1.

用法範例：

staticintadd_spam(PyObject*module,intvalue){PyObject*obj=PyLong_FromLong(value);if(obj==NULL){return-1;}intres=PyModule_AddObjectRef(module,"spam",obj);Py_DECREF(obj);returnres;}

To be convenient, the function acceptsNULLvalue with an exceptionset. In this case, return-1 and just leave the raised exceptionunchanged.

The example can also be written without checking explicitly ifobj isNULL:

staticintadd_spam(PyObject*module,intvalue){PyObject*obj=PyLong_FromLong(value);intres=PyModule_AddObjectRef(module,"spam",obj);Py_XDECREF(obj);returnres;}

Note thatPy_XDECREF() should be used instead ofPy_DECREF() inthis case, sinceobj can beNULL.

The number of differentname strings passed to this functionshould be kept small, usually by only using statically allocated stringsasname.For names that aren't known at compile time, prefer callingPyUnicode_FromString() andPyObject_SetAttr() directly.For more details, seePyUnicode_InternFromString(), which may beused internally to create a key object.

在 3.10 版被加入.

intPyModule_Add(PyObject*module,constchar*name,PyObject*value)¶

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

Similar toPyModule_AddObjectRef(), but "steals" a referencetovalue.It can be called with a result of function that returns a new referencewithout bothering to check its result or even saving it to a variable.

用法範例：

if(PyModule_Add(module,"spam",PyBytes_FromString(value))<0){gotoerror;}

在 3.13 版被加入.

intPyModule_AddObject(PyObject*module,constchar*name,PyObject*value)¶

為穩定 ABI 的一部分.

類似於PyModule_AddObjectRef()，但在成功時（如果回傳0）會偷走對value 的參照。

The newPyModule_Add() orPyModule_AddObjectRef()functions are recommended, since it iseasy to introduce reference leaks by misusing thePyModule_AddObject() function.

備註

Unlike other functions that steal references,PyModule_AddObject()only releases the reference tovalueon success.

This means that its return value must be checked, and calling code mustPy_XDECREF()value manually on error.

用法範例：

PyObject*obj=PyBytes_FromString(value);if(PyModule_AddObject(module,"spam",obj)<0){// If 'obj' is not NULL and PyModule_AddObject() failed,// 'obj' strong reference must be deleted with Py_XDECREF().// If 'obj' is NULL, Py_XDECREF() does nothing.Py_XDECREF(obj);gotoerror;}// PyModule_AddObject() stole a reference to obj:// Py_XDECREF(obj) is not needed here.

在 3.13 版之後被棄用:PyModule_AddObject() 已被軟性棄用。

intPyModule_AddIntConstant(PyObject*module,constchar*name,longvalue)¶

為穩定 ABI 的一部分.

Add an integer constant tomodule asname. This convenience function can beused from the module's initialization function.Return-1 with an exception set on error,0 on success.

This is a convenience function that callsPyLong_FromLong() andPyModule_AddObjectRef(); see their documentation for details.

intPyModule_AddStringConstant(PyObject*module,constchar*name,constchar*value)¶

為穩定 ABI 的一部分.

Add a string constant tomodule asname. This convenience function can beused from the module's initialization function. The stringvalue must beNULL-terminated.Return-1 with an exception set on error,0 on success.

This is a convenience function that callsPyUnicode_InternFromString() andPyModule_AddObjectRef();see their documentation for details.

PyModule_AddIntMacro(module,macro)¶

Add an int constant tomodule. The name and the value are taken frommacro. For examplePyModule_AddIntMacro(module,AF_INET) adds the intconstantAF_INET with the value ofAF_INET tomodule.Return-1 with an exception set on error,0 on success.

PyModule_AddStringMacro(module,macro)¶

將字串常數加入到module 中。

intPyModule_AddType(PyObject*module,PyTypeObject*type)¶

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

Add a type object tomodule.The type object is finalized by calling internallyPyType_Ready().The name of the type object is taken from the last component oftp_name after dot.Return-1 with an exception set on error,0 on success.

在 3.9 版被加入.

intPyModule_AddFunctions(PyObject*module,PyMethodDef*functions)¶

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

Add the functions from theNULL terminatedfunctions array tomodule.Refer to thePyMethodDef documentation for details on individualentries (due to the lack of a shared module namespace, module level"functions" implemented in C typically receive the module as their firstparameter, making them similar to instance methods on Python classes).

This function is called automatically when creating a module fromPyModuleDef (such as when usingMulti-phase initialization,PyModule_Create, orPyModule_FromDefAndSpec).Some module authors may prefer defining functions in multiplePyMethodDef arrays; in that case they should call this functiondirectly.

Thefunctions array must be statically allocated (or otherwise guaranteedto outlive the module object).

在 3.5 版被加入.

intPyModule_SetDocString(PyObject*module,constchar*docstring)¶

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

Set the docstring formodule todocstring.This function is called automatically when creating a module fromPyModuleDef (such as when usingMulti-phase initialization,PyModule_Create, orPyModule_FromDefAndSpec).

在 3.5 版被加入.

intPyUnstable_Module_SetGIL(PyObject*module,void*gil)¶

這是不穩定 API，它可能在小版本發布中沒有任何警告地被變更。

Indicate thatmodule does or does not support running without the globalinterpreter lock (GIL), using one of the values fromPy_mod_gil. It must be called duringmodule's initializationfunction when usingLegacy single-phase initialization.If this function is not called during module initialization, theimport machinery assumes the module does not support running without theGIL. This function is only available in Python builds configured with--disable-gil.Return-1 with an exception set on error,0 on success.

在 3.13 版被加入.