Single-phase initialization¶

The module initialization function may create and return the module objectdirectly. This is referred to as "single-phase initialization", and uses oneof the following two module creation functions:

PyObject*PyModule_Create(PyModuleDef*def)¶

回傳值：新的參照。

Create a new module object, given the definition indef. This behaveslikePyModule_Create2() withmodule_api_version set toPYTHON_API_VERSION.

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 並設定例外。

備註

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

Before it is returned from in the initialization function, the resulting moduleobject is typically populated using functions likePyModule_AddObjectRef().

Multi-phase initialization¶

An alternate way to specify extensions is to request "multi-phase initialization".Extension modules created this way behave more like Python modules: theinitialization is split between thecreation phase, when the module objectis created, and theexecution phase, when it is populated.The distinction is similar to the__new__() and__init__() methodsof classes.

Unlike modules created using single-phase initialization, these modules are notsingletons: if thesys.modules entry is removed and the module is re-imported,a new module object is created, and the old module is subject to normal garbagecollection -- as with Python modules.By default, multiple modules created from the same definition should beindependent: changes to one should not affect the others.This means that all state should be specific to the module object (using e.g.usingPyModule_GetState()), or its contents (such as the module's__dict__ or individual classes created withPyType_FromSpec()).

All modules created using multi-phase initialization are expected to supportsub-interpreters. Making sure multiple modulesare independent is typically enough to achieve this.

To request multi-phase initialization, the initialization function(PyInit_modulename) returns aPyModuleDef instance with non-emptym_slots. Before it is returned, thePyModuleDefinstance must be initialized with the following function:

PyObject*PyModuleDef_Init(PyModuleDef*def)¶

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

Ensures a module definition is a properly initialized Python object thatcorrectly reports its type and reference count.

Returnsdef cast toPyObject*, orNULL if an error occurred.

在 3.5 版被加入.

Them_slots member of the module definition must point to an array ofPyModuleDef_Slot structures:

typePyModuleDef_Slot¶

intslot¶

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 版被加入.

Them_slots array must be terminated by a slot with id 0.

The available slot types are:

Py_mod_create¶

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

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

The function receives aModuleSpecinstance, as defined inPEP 451, and the module definition.It should return a new module object, or set an errorand returnNULL.

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

MultiplePy_mod_create slots may not be specified in one moduledefinition.

IfPy_mod_create is not specified, the import machinery will createa normal module object usingPyModule_New(). The name is taken fromspec, not the definition, to allow extension modules to dynamically adjustto their place in the module hierarchy and be imported under differentnames through symlinks, all while sharing a single module definition.

There is no requirement for the returned object to be an instance ofPyModule_Type. Any type can be used, as long as it supportssetting and getting import-related attributes.However, onlyPyModule_Type instances may be returned if thePyModuleDef has non-NULLm_traverse,m_clear,m_free; non-zerom_size; or slots other thanPy_mod_create.

Py_mod_exec¶

Specifies a function that is called toexecute 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:

intexec_module(PyObject*module)¶

If multiplePy_mod_exec slots are specified, they are processed in theorder they appear in them_slots array.

Py_mod_multiple_interpreters¶

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 modulein a subinterpreter will fail.

MultiplePy_mod_multiple_interpreters slots may not be specifiedin one module definition.

IfPy_mod_multiple_interpreters is not specified, the importmachinery defaults toPy_MOD_MULTIPLE_INTERPRETERS_SUPPORTED.

在 3.12 版被加入.

Py_mod_gil¶

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 importingthis module will cause the GIL to be automatically enabled. SeeFree-threaded CPython for more detail.

MultiplePy_mod_gil slots may not be specified in one module definition.

IfPy_mod_gil is not specified, the import machinery defaults toPy_MOD_GIL_USED.

在 3.13 版被加入.

SeePEP 489 for more details on multi-phase initialization.

Low-level module creation functions¶

The following functions are called under the hood when using multi-phaseinitialization. They can be used directly, for example when creating moduleobjects dynamically. Note that bothPyModule_FromDefAndSpec andPyModule_ExecDef must be called to fully initialize a module.

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

回傳值：新的參照。

Create a new module object, given the definition indef and theModuleSpecspec. This behaves likePyModule_FromDefAndSpec2()withmodule_api_version set toPYTHON_API_VERSION.

在 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 並設定例外。

備註

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 版被加入.

intPyModule_SetDocString(PyObject*module,constchar*docstring)¶

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

Set the docstring formodule todocstring.This function is called automatically when creating a module fromPyModuleDef, using eitherPyModule_Create orPyModule_FromDefAndSpec.

在 3.5 版被加入.

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, using eitherPyModule_Create orPyModule_FromDefAndSpec.

在 3.5 版被加入.

支援的函式¶

The module initialization function (if using single phase initialization) ora function called from a module execution slot (if using multi-phaseinitialization), can use the following functions to help initialize the modulestate:

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 的一部分.

Similar toPyModule_AddObjectRef(), but steals a reference tovalue on success (if it returns0).

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() issoft deprecated.

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 版被加入.

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. 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 版被加入.