Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-08 06:10:17 +00:00
Code Issues Projects Releases Packages Wiki Activity

gh-140550: PEP 793 reference documentation (GH-141197)

Browse source 
* gh-140550: PEP 793 reference documentation

Since the PEP calls for soft-deprecation of the existing initialization
function, this reorganizes the relevant docs to put the new way of
doing things first, and de-emphasize the old.

Some bits, like the tutorial, are left out of this patch. (See the
issue for a list.)
This commit is contained in:
Petr Viktorin 2025-11-26 13:50:03 +01:00 • committed by GitHub
parent 8c33c6143e
commit d7f0214f13
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 772 additions and 321 deletions
Download patch file Download diff file Expand all files Collapse all files

257
Doc/c-api/extension-modules.rst
View file

@ -8,7 +8,8 @@ Defining extension modules
A C extension for CPython is a shared library (for example, a ``.so`` file A C extension for CPython is a shared library (for example, a ``.so`` file
on Linux, ``.pyd`` DLL on Windows), which is loadable into the Python process on Linux, ``.pyd`` DLL on Windows), which is loadable into the Python process
(for example, it is compiled with compatible compiler settings), and which (for example, it is compiled with compatible compiler settings), and which
exports an :ref:`initialization function <extension-export-hook>`. exports an :dfn:`export hook` function (or an
old-style :ref:`initialization function <extension-pyinit>`).
To be importable by default (that is, by To be importable by default (that is, by
:py:class:`importlib.machinery.ExtensionFileLoader`), :py:class:`importlib.machinery.ExtensionFileLoader`),
@ -23,25 +24,127 @@ and must be named after the module name plus an extension listed in
One suitable tool is Setuptools, whose documentation can be found at One suitable tool is Setuptools, whose documentation can be found at
https://setuptools.pypa.io/en/latest/setuptools.html. https://setuptools.pypa.io/en/latest/setuptools.html.
Normally, the initialization function returns a module definition initialized .. _extension-export-hook:
using :c:func:`PyModuleDef_Init`.
This allows splitting the creation process into several phases:
Extension export hook
.....................
.. versionadded:: next
Support for the :samp:`PyModExport_{<name>}` export hook was added in Python
3.15. The older way of defining modules is still available: consult either
the :ref:`extension-pyinit` section or earlier versions of this
documentation if you plan to support earlier Python versions.
The export hook must be an exported function with the following signature:
.. c:function:: PyModuleDef_Slot *PyModExport_modulename(void)
For modules with ASCII-only names, the :ref:`export hook <extension-export-hook>`
must be named :samp:`PyModExport_{<name>}`,
with ``<name>`` replaced by the module's name.
For non-ASCII module names, the export hook must instead be named
:samp:`PyModExportU_{<name>}` (note the ``U``), with ``<name>`` encoded using
Python's *punycode* encoding with hyphens replaced by underscores. In Python:
.. code-block:: python
def hook_name(name):
try:
suffix = b'_' + name.encode('ascii')
except UnicodeEncodeError:
suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
return b'PyModExport' + suffix
The export hook returns an array of :c:type:`PyModuleDef_Slot` entries,
terminated by an entry with a slot ID of ``0``.
These slots describe how the module should be created and initialized.
This array must remain valid and constant until interpreter shutdown.
Typically, it should use ``static`` storage.
Prefer using the :c:macro:`Py_mod_create` and :c:macro:`Py_mod_exec` slots
for any dynamic behavior.
The export hook may return ``NULL`` with an exception set to signal failure.
It is recommended to define the export hook function using a helper macro:
.. c:macro:: PyMODEXPORT_FUNC
Declare an extension module export hook.
This macro:
* specifies the :c:expr:`PyModuleDef_Slot*` return type,
* adds any special linkage declarations required by the platform, and
* for C++, declares the function as ``extern "C"``.
For example, a module called ``spam`` would be defined like this::
PyABIInfo_VAR(abi_info);
static PyModuleDef_Slot spam_slots[] = {
{Py_mod_abi, &abi_info},
{Py_mod_name, "spam"},
{Py_mod_init, spam_init_function},
...
{0, NULL},
};
PyMODEXPORT_FUNC
PyModExport_spam(void)
{
return spam_slots;
}
The export hook is typically the only non-\ ``static``
item defined in the module's C source.
The hook should be kept short -- ideally, one line as above.
If you do need to use Python C API in this function, it is recommended to call
``PyABIInfo_Check(&abi_info, "modulename")`` first to raise an exception,
rather than crash, in common cases of ABI mismatch.
.. note::
It is possible to export multiple modules from a single shared library by
defining multiple export hooks.
However, importing them requires a custom importer or suitably named
copies/links of the extension file, because Python's import machinery only
finds the function corresponding to the filename.
See the `Multiple modules in one library <https://peps.python.org/pep-0489/#multiple-modules-in-one-library>`__
section in :pep:`489` for details.
.. _multi-phase-initialization:
Multi-phase initialization
..........................
The process of creating an extension module follows several phases:
- Python finds and calls the export hook to get information on how to
create the module.
- Before any substantial code is executed, Python can determine which - Before any substantial code is executed, Python can determine which
capabilities the module supports, and it can adjust the environment or capabilities the module supports, and it can adjust the environment or
refuse loading an incompatible extension. refuse loading an incompatible extension.
- By default, Python itself creates the module object -- that is, it does Slots like :c:data:`Py_mod_abi`, :c:data:`Py_mod_gil` and
the equivalent of :py:meth:`object.__new__` for classes. :c:data:`Py_mod_multiple_interpreters` influence this step.
It also sets initial attributes like :attr:`~module.__package__` and - By default, Python itself then creates the module object -- that is, it does
:attr:`~module.__loader__`. the equivalent of calling :py:meth:`~object.__new__` when creating an object.
- Afterwards, the module object is initialized using extension-specific This step can be overridden using the :c:data:`Py_mod_create` slot.
code -- the equivalent of :py:meth:`~object.__init__` on classes. - Python sets initial module attributes like :attr:`~module.__package__` and
:attr:`~module.__loader__`, and inserts the module object into
:py:attr:`sys.modules`.
- Afterwards, the module object is initialized in an extension-specific way
-- the equivalent of :py:meth:`~object.__init__` when creating an object,
or of executing top-level code in a Python-language module.
The behavior is specified using the :c:data:`Py_mod_exec` slot.
This is called *multi-phase initialization* to distinguish it from the legacy This is called *multi-phase initialization* to distinguish it from the legacy
(but still supported) *single-phase initialization* scheme, (but still supported) :ref:`single-phase initialization <single-phase-initialization>`,
where the initialization function returns a fully constructed module. where an initialization function returns a fully constructed module.
See the :ref:`single-phase-initialization section below <single-phase-initialization>`
for details.
.. versionchanged:: 3.5 .. versionchanged:: 3.5
@ -53,7 +156,7 @@ Multiple module instances
By default, extension modules are not singletons. By default, extension modules are not singletons.
For example, if the :py:attr:`sys.modules` entry is removed and the module For example, if the :py:attr:`sys.modules` entry is removed and the module
is re-imported, a new module object is created, and typically populated with is re-imported, a new module object is created and, typically, populated with
fresh method and type objects. fresh method and type objects.
The old module is subject to normal garbage collection. The old module is subject to normal garbage collection.
This mirrors the behavior of pure-Python modules. This mirrors the behavior of pure-Python modules.
@ -83,36 +186,34 @@ A module may also be limited to the main interpreter using
the :c:data:`Py_mod_multiple_interpreters` slot. the :c:data:`Py_mod_multiple_interpreters` slot.
.. _extension-export-hook: .. _extension-pyinit:
Initialization function ``PyInit`` function
....................... ...................
The initialization function defined by an extension module has the .. deprecated:: next
following signature:
This functionality is :term:`soft deprecated`.
It will not get new features, but there are no plans to remove it.
Instead of :c:func:`PyModExport_modulename`, an extension module can define
an older-style :dfn:`initialization function` with the signature:
.. c:function:: PyObject* PyInit_modulename(void) .. c:function:: PyObject* PyInit_modulename(void)
Its name should be :samp:`PyInit_{<name>}`, with ``<name>`` replaced by the Its name should be :samp:`PyInit_{<name>}`, with ``<name>`` replaced by the
name of the module. name of the module.
For non-ASCII module names, use :samp:`PyInitU_{<name>}` instead, with
``<name>`` encoded in the same way as for the
:ref:`export hook <extension-export-hook>` (that is, using Punycode
with underscores).
For modules with ASCII-only names, the function must instead be named If a module exports both :samp:`PyInit_{<name>}` and
:samp:`PyInit_{<name>}`, with ``<name>`` replaced by the name of the module. :samp:`PyModExport_{<name>}`, the :samp:`PyInit_{<name>}` function
When using :ref:`multi-phase-initialization`, non-ASCII module names is ignored.
are allowed. In this case, the initialization function name is
:samp:`PyInitU_{<name>}`, with ``<name>`` encoded using Python's
*punycode* encoding with hyphens replaced by underscores. In Python:
.. code-block:: python Like with :c:macro:`PyMODEXPORT_FUNC`, it is recommended to define the
initialization function using a helper macro:
def initfunc_name(name):
try:
suffix = b'_' + name.encode('ascii')
except UnicodeEncodeError:
suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
return b'PyInit' + suffix
It is recommended to define the initialization function using a helper macro:
.. c:macro:: PyMODINIT_FUNC .. c:macro:: PyMODINIT_FUNC
@ -123,6 +224,34 @@ It is recommended to define the initialization function using a helper macro:
* adds any special linkage declarations required by the platform, and * adds any special linkage declarations required by the platform, and
* for C++, declares the function as ``extern "C"``. * for C++, declares the function as ``extern "C"``.
Normally, the initialization function (``PyInit_modulename``) returns
a :c:type:`PyModuleDef` instance with non-``NULL``
:c:member:`~PyModuleDef.m_slots`. This allows Python to use
:ref:`multi-phase initialization <multi-phase-initialization>`.
Before it is returned, the ``PyModuleDef`` instance must be initialized
using the following function:
.. c:function:: PyObject* PyModuleDef_Init(PyModuleDef *def)
Ensure a module definition is a properly initialized Python object that
correctly reports its type and a reference count.
Return *def* cast to ``PyObject*``, or ``NULL`` if an error occurred.
Calling this function is required before returning a :c:type:`PyModuleDef`
from a module initialization function.
It should not be used in other contexts.
Note that Python assumes that ``PyModuleDef`` structures are statically
allocated.
This function may return either a new reference or a borrowed one;
this reference must not be released.
.. versionadded:: 3.5
For example, a module called ``spam`` would be defined like this:: For example, a module called ``spam`` would be defined like this::
static struct PyModuleDef spam_module = { static struct PyModuleDef spam_module = {
@ -137,59 +266,23 @@ For example, a module called ``spam`` would be defined like this::
return PyModuleDef_Init(&spam_module); return PyModuleDef_Init(&spam_module);
} }
It is possible to export multiple modules from a single shared library by
defining multiple initialization functions. However, importing them requires
using symbolic links or a custom importer, because by default only the
function corresponding to the filename is found.
See the `Multiple modules in one library <https://peps.python.org/pep-0489/#multiple-modules-in-one-library>`__
section in :pep:`489` for details.
The initialization function is typically the only non-\ ``static``
item defined in the module's C source.
.. _multi-phase-initialization:
Multi-phase initialization
..........................
Normally, the :ref:`initialization function <extension-export-hook>`
(``PyInit_modulename``) returns a :c:type:`PyModuleDef` instance with
non-``NULL`` :c:member:`~PyModuleDef.m_slots`.
Before it is returned, the ``PyModuleDef`` instance must be initialized
using the following function:
.. c:function:: PyObject* PyModuleDef_Init(PyModuleDef *def)
Ensure a module definition is a properly initialized Python object that
correctly reports its type and a reference count.
Return *def* cast to ``PyObject*``, or ``NULL`` if an error occurred.
Calling this function is required for :ref:`multi-phase-initialization`.
It should not be used in other contexts.
Note that Python assumes that ``PyModuleDef`` structures are statically
allocated.
This function may return either a new reference or a borrowed one;
this reference must not be released.
.. versionadded:: 3.5
.. _single-phase-initialization: .. _single-phase-initialization:
Legacy single-phase initialization Legacy single-phase initialization
.................................. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. attention:: .. deprecated:: next
Single-phase initialization is a legacy mechanism to initialize extension
Single-phase initialization is :term:`soft deprecated`.
It is a legacy mechanism to initialize extension
modules, with known drawbacks and design flaws. Extension module authors modules, with known drawbacks and design flaws. Extension module authors
are encouraged to use multi-phase initialization instead. are encouraged to use multi-phase initialization instead.
In single-phase initialization, the However, there are no plans to remove support for it.
:ref:`initialization function <extension-export-hook>` (``PyInit_modulename``)
In single-phase initialization, the old-style
:ref:`initializaton function <extension-pyinit>` (``PyInit_modulename``)
should create, populate and return a module object. should create, populate and return a module object.
This is typically done using :c:func:`PyModule_Create` and functions like This is typically done using :c:func:`PyModule_Create` and functions like
:c:func:`PyModule_AddObjectRef`. :c:func:`PyModule_AddObjectRef`.
@ -242,6 +335,8 @@ in the following ways:
* Single-phase modules support module lookup functions like * Single-phase modules support module lookup functions like
:c:func:`PyState_FindModule`. :c:func:`PyState_FindModule`.
* The module's :c:member:`PyModuleDef.m_slots` must be NULL.
.. [#testsinglephase] ``_testsinglephase`` is an internal module used .. [#testsinglephase] ``_testsinglephase`` is an internal module used
in CPython's self-test suite; your installation may or may not in CPython's self-test suite; your installation may or may not
include it. include it.

2
Doc/c-api/import.rst
View file

@ -353,7 +353,7 @@ Importing Modules
the same as for :c:func:`PyImport_AppendInittab`. the same as for :c:func:`PyImport_AppendInittab`.
On success, create and return a module object. On success, create and return a module object.
This module will not be initialized; call :c:func:`!PyModule_Exec` This module will not be initialized; call :c:func:`PyModule_Exec`
to initialize it. to initialize it.
(Custom importers should do this in their (Custom importers should do this in their
:py:meth:`~importlib.abc.Loader.exec_module` method.) :py:meth:`~importlib.abc.Loader.exec_module` method.)

3
Doc/c-api/init.rst
View file

@ -1717,7 +1717,8 @@ function. You can create and destroy them using the following functions:
Only C-level static and global variables are shared between these Only C-level static and global variables are shared between these
module objects. module objects.
* For modules using single-phase initialization, * For modules using legacy
:ref:`single-phase initialization <single-phase-initialization>`,
e.g. :c:func:`PyModule_Create`, the first time a particular extension e.g. :c:func:`PyModule_Create`, the first time a particular extension
is imported, it is initialized normally, and a (shallow) copy of its is imported, it is initialized normally, and a (shallow) copy of its
module's dictionary is squirreled away. module's dictionary is squirreled away.

755
Doc/c-api/module.rst
View file

@ -3,11 +3,10 @@
.. _moduleobjects: .. _moduleobjects:
Module Objects Module Objects
-------------- ==============
.. index:: pair: object; module .. index:: pair: object; module
.. c:var:: PyTypeObject PyModule_Type .. c:var:: PyTypeObject PyModule_Type
.. index:: single: ModuleType (in module types) .. index:: single: ModuleType (in module types)
@ -97,13 +96,6 @@ Module Objects
Note that Python code may rename a module by setting its :py:attr:`~module.__name__` Note that Python code may rename a module by setting its :py:attr:`~module.__name__`
attribute. attribute.
.. c:function:: 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
:c:member:`PyModuleDef.m_size`.
.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module) .. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
Return a pointer to the :c:type:`PyModuleDef` struct from which the module was Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
@ -141,214 +133,108 @@ Module Objects
unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead. unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
.. _pymoduledef: .. _pymoduledef_slot:
Module definitions Module definition
------------------ -----------------
The functions in the previous section work on any module object, including Modules created using the C API are typically defined using an
modules imported from Python code. array of :dfn:`slots`.
The slots provide a "description" of how a module should be created.
Modules defined using the C API typically use a *module definition*, .. versionchanged:: next
:c:type:`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 Previously, a :c:type:`PyModuleDef` struct was necessary to define modules.
(see :ref:`extension-modules` for details). The older way of defining modules is still available: consult either the
It is also used to :ref:`pymoduledef` section or earlier versions of this documentation
:ref:`create extension modules dynamically <moduledef-dynamic>`. if you plan to support earlier Python versions.
Unlike :c:func:`PyModule_New`, the definition allows management of The slots array is usually used to define an extension module's “main”
*module state* -- a piece of memory that is allocated and cleared together module object (see :ref:`extension-modules` for details).
with the module object. It can also be used to
Unlike the module's Python attributes, Python code cannot replace or delete :ref:`create extension modules dynamically <module-from-slots>`.
data stored in module state.
.. c:type:: PyModuleDef Unless specified otherwise, the same slot ID may not be repeated
in an array of slots.
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.
.. c:member:: PyModuleDef_Base m_base
Always initialize this member to :c:macro:`PyModuleDef_HEAD_INIT`.
.. c:member:: const char *m_name
Name for the new module.
.. c:member:: const char *m_doc
Docstring for the module; usually a docstring variable created with
:c:macro:`PyDoc_STRVAR` is used.
.. c:member:: Py_ssize_t m_size
Module state may be kept in a per-module memory area that can be
retrieved with :c:func:`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
:c:member:`~PyModuleDef.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
:ref:`legacy single-phase initialization <single-phase-initialization>`
or when :ref:`creating modules dynamically <moduledef-dynamic>`.
See :PEP:`3121` for more details.
.. c:member:: PyMethodDef* m_methods
A pointer to a table of module-level functions, described by
:c:type:`PyMethodDef` values. Can be ``NULL`` if no functions are present.
.. c:member:: 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``.
.. versionchanged:: 3.5
Prior to version 3.5, this member was always set to ``NULL``,
and was defined as:
.. c:member:: inquiry m_reload
.. c:member:: 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 (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if :c:member:`~PyModuleDef.m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
.. versionchanged:: 3.9
No longer called before the module state is allocated.
.. c:member:: inquiry m_clear
A clear function to call during GC clearing 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 (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if :c:member:`~PyModuleDef.m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
Like :c:member:`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
:c:member:`~PyModuleDef.m_free` is called directly.
.. versionchanged:: 3.9
No longer called before the module state is allocated.
.. c:member:: freefunc m_free
A function to call during deallocation 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 (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if :c:member:`~PyModuleDef.m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
.. versionchanged:: 3.9
No longer called before the module state is allocated.
Module slots
............
.. c:type:: PyModuleDef_Slot .. c:type:: PyModuleDef_Slot
.. c:member:: int slot .. c:member:: int slot
A slot ID, chosen from the available values explained below. A slot ID, chosen from the available ``Py_mod_*`` values explained below.
An ID of 0 marks the end of a :c:type:`!PyModuleDef_Slot` array.
.. c:member:: void* value .. c:member:: void* value
Value of the slot, whose meaning depends on the slot ID. Value of the slot, whose meaning depends on the slot ID.
.. versionadded:: 3.5 The value may not be NULL.
To leave a slot out, omit the :c:type:`PyModuleDef_Slot` entry entirely.
The available slot types are:
.. c:macro:: Py_mod_create
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:
.. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
:no-index-entry:
:no-contents-entry:
The function receives a :py:class:`~importlib.machinery.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 :c:func:`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
:c:type:`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``.
.. versionadded:: 3.5 .. versionadded:: 3.5
.. c:macro:: Py_mod_exec
Specifies a function that is called to *execute* the module. Metadata slots
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:
.. c:function:: int exec_module(PyObject* module) .. c:macro:: Py_mod_name
:no-index-entry:
:no-contents-entry:
If multiple ``Py_mod_exec`` slots are specified, they are processed in the :c:type:`Slot ID <PyModuleDef_Slot.slot>` for the name of the new module,
order they appear in the *m_slots* array. as a NUL-terminated UTF8-encoded ``const char *``.
.. versionadded:: 3.5 Note that modules are typically created using a
:py:class:`~importlib.machinery.ModuleSpec`, and when they are, the
name from the spec will be used instead of :c:data:`!Py_mod_name`.
However, it is still recommended to include this slot for introspection
and debugging purposes.
.. versionadded:: next
Use :c:member:`PyModuleDef.m_name` instead to support previous versions.
.. c:macro:: Py_mod_doc
:c:type:`Slot ID <PyModuleDef_Slot.slot>` for the docstring of the new
module, as a NUL-terminated UTF8-encoded ``const char *``.
Usually it is set to a variable created with :c:macro:`PyDoc_STRVAR`.
.. versionadded:: next
Use :c:member:`PyModuleDef.m_doc` instead to support previous versions.
Feature slots
.............
.. c:macro:: Py_mod_abi
:c:type:`Slot ID <PyModuleDef_Slot.slot>` whose value points to
a :c:struct:`PyABIInfo` structure describing the ABI that
the extension is using.
A suitable :c:struct:`!PyABIInfo` variable can be defined using the
:c:macro:`PyABIInfo_VAR` macro, as in:
.. code-block:: c
PyABIInfo_VAR(abi_info);
static PyModuleDef_Slot mymodule_slots[] = {
{Py_mod_abi, &abi_info},
...
};
When creating a module, Python checks the value of this slot
using :c:func:`PyABIInfo_Check`.
.. versionadded:: 3.15
.. c:macro:: Py_mod_multiple_interpreters .. c:macro:: Py_mod_multiple_interpreters
Specifies one of the following values: :c:type:`Slot ID <PyModuleDef_Slot.slot>` whose value is one of:
.. c:namespace:: NULL .. c:namespace:: NULL
@ -371,9 +257,6 @@ The available slot types are:
This slot determines whether or not importing this module This slot determines whether or not importing this module
in a subinterpreter will fail. 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 If ``Py_mod_multiple_interpreters`` is not specified, the import
machinery defaults to ``Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED``. machinery defaults to ``Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED``.
@ -381,7 +264,7 @@ The available slot types are:
.. c:macro:: Py_mod_gil .. c:macro:: Py_mod_gil
Specifies one of the following values: :c:type:`Slot ID <PyModuleDef_Slot.slot>` whose value is one of:
.. c:namespace:: NULL .. c:namespace:: NULL
@ -399,45 +282,482 @@ The available slot types are:
this module will cause the GIL to be automatically enabled. See this module will cause the GIL to be automatically enabled. See
:ref:`whatsnew313-free-threaded-cpython` for more detail. :ref:`whatsnew313-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 If ``Py_mod_gil`` is not specified, the import machinery defaults to
``Py_MOD_GIL_USED``. ``Py_MOD_GIL_USED``.
.. versionadded:: 3.13 .. versionadded:: 3.13
.. c:macro:: Py_mod_abi
A pointer to a :c:struct:`PyABIInfo` structure that describes the ABI that Creation and initialization slots
the extension is using. .................................
When the module is loaded, the :c:struct:`!PyABIInfo` in this slot is checked .. c:macro:: Py_mod_create
using :c:func:`PyABIInfo_Check`.
A suitable :c:struct:`!PyABIInfo` variable can be defined using the :c:type:`Slot ID <PyModuleDef_Slot.slot>` for a function that creates
:c:macro:`PyABIInfo_VAR` macro, as in: the module object itself.
The function must have the signature:
.. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
:no-index-entry:
:no-contents-entry:
The function will be called with:
- *spec*: a ``ModuleSpec``-like object, meaning that any attributes defined
for :py:class:`importlib.machinery.ModuleSpec` have matching semantics.
However, any of the attributes may be missing.
- *def*: ``NULL``, or the module definition if the module is created from one.
The function 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.
If ``Py_mod_create`` is not specified, the import machinery will create
a normal module object using :c:func:`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
:c:type:`PyModule_Type`.
However, some slots may only be used with
:c:type:`!PyModule_Type` instances; in particular:
- :c:macro:`Py_mod_exec`,
- :ref:`module state slots <ext-module-state-slots>` (``Py_mod_state_*``),
- :c:macro:`Py_mod_token`.
.. versionadded:: 3.5
.. versionchanged:: next
The *slots* argument may be a ``ModuleSpec``-like object, rather than
a true :py:class:`~importlib.machinery.ModuleSpec` instance.
Note that previous versions of CPython did not enforce this.
The *def* argument may now be ``NULL``, since modules are not necessarily
made from definitions.
.. c:macro:: Py_mod_exec
:c:type:`Slot ID <PyModuleDef_Slot.slot>` for a function that will
:dfn:`execute`, or initialize, the module.
This function does the equivalent to executing the code of a Python module:
typically, it adds classes and constants to the module.
The signature of the function is:
.. c:function:: int exec_module(PyObject* module)
:no-index-entry:
:no-contents-entry:
See the :ref:`capi-module-support-functions` section for some useful
functions to call.
For backwards compatibility, the :c:type:`PyModuleDef.m_slots` array may
contain multiple :c:macro:`!Py_mod_exec` slots; these are processed in the
order they appear in the array.
Elsewhere (that is, in arguments to :c:func:`PyModule_FromSlotsAndSpec`
and in return values of :samp:`PyModExport_{<name>}`), repeating the slot
is not allowed.
.. versionadded:: 3.5
.. versionchanged:: next
Repeated ``Py_mod_exec`` slots are disallowed, except in
:c:type:`PyModuleDef.m_slots`.
.. c:macro:: Py_mod_methods
:c:type:`Slot ID <PyModuleDef_Slot.slot>` for a table of module-level
functions, as an array of :c:type:`PyMethodDef` values suitable as the
*functions* argument to :c:func:`PyModule_AddFunctions`.
Like other slot IDs, a slots array may only contain one
:c:macro:`!Py_mod_methods` entry.
To add functions from multiple :c:type:`PyMethodDef` arrays, call
:c:func:`PyModule_AddFunctions` in the :c:macro:`Py_mod_exec` function.
The table must be statically allocated (or otherwise guaranteed to outlive
the module object).
.. versionadded:: next
Use :c:member:`PyModuleDef.m_methods` instead to support previous versions.
.. _ext-module-state:
Module state
------------
Extension modules can have *module state* -- a
piece of memory that is allocated on module creation,
and freed when the module object is deallocated.
The module state is specified using :ref:`dedicated slots <ext-module-state-slots>`.
A typical use of module state is storing an exception type -- or indeed *any*
type object defined by the module --
Unlike the module's Python attributes, Python code cannot replace or delete
data stored in module state.
Keeping per-module information in attributes and module state, rather than in
static globals, makes module objects *isolated* and safer for use in
multiple sub-interpreters.
It also helps Python do an orderly clean-up when it shuts down.
Extensions that keep references to Python objects as part of module state must
implement :c:macro:`Py_mod_state_traverse` and :c:macro:`Py_mod_state_clear`
functions to avoid reference leaks.
To retrieve the state from a given module, use the following functions:
.. c:function:: 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
:c:macro:`Py_mod_state_size`.
On error, return ``NULL`` with an exception set.
Use :c:func:`PyErr_Occurred` to tell this case apart from missing
module state.
.. c:function:: int PyModule_GetStateSize(PyObject *, Py_ssize_t *result)
Set *\*result* to the size of the module's state, as specified using
:c:macro:`Py_mod_state_size` (or :c:member:`PyModuleDef.m_size`),
and return 0.
On error, set *\*result* to -1, and return -1 with an exception set.
.. versionadded:: next
.. _ext-module-state-slots:
Slots for defining module state
...............................
The following :c:member:`PyModuleDef_Slot.slot` IDs are available for
defining the module state.
.. c:macro:: Py_mod_state_size
:c:type:`Slot ID <PyModuleDef_Slot.slot>` for the size of the module state,
in bytes.
Setting the value 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.
Use :c:func:`PyModule_GetStateSize` to retrieve the size of a given module.
.. versionadded:: next
Use :c:member:`PyModuleDef.m_size` instead to support previous versions.
.. c:macro:: Py_mod_state_traverse
:c:type:`Slot ID <PyModuleDef_Slot.slot>` for a traversal function to call
during GC traversal of the module object.
The signature of the function, and meanings of the arguments,
is similar as for :c:member:`PyTypeObject.tp_traverse`:
.. c:function:: int traverse_module_state(PyObject *module, visitproc visit, void *arg)
:no-index-entry:
:no-contents-entry:
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 (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if the state size
(:c:data:`Py_mod_state_size`) is greater than 0 and the module state
(as returned by :c:func:`PyModule_GetState`) is ``NULL``.
.. versionadded:: next
Use :c:member:`PyModuleDef.m_size` instead to support previous versions.
.. c:macro:: Py_mod_state_clear
:c:type:`Slot ID <PyModuleDef_Slot.slot>` for a clear function to call
during GC clearing of the module object.
The signature of the function is:
.. c:function:: int clear_module_state(PyObject* module)
:no-index-entry:
:no-contents-entry:
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 (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if the state size
(:c:data:`Py_mod_state_size`) is greater than 0 and the module state
(as returned by :c:func:`PyModule_GetState`) is ``NULL``.
Like :c:member:`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
the :c:macro:`Py_mod_state_free` function is called directly.
.. versionadded:: next
Use :c:member:`PyModuleDef.m_clear` instead to support previous versions.
.. c:macro:: Py_mod_state_free
:c:type:`Slot ID <PyModuleDef_Slot.slot>` for a function to call during
deallocation of the module object.
The signature of the function is:
.. c:function:: int free_module_state(PyObject* module)
:no-index-entry:
:no-contents-entry:
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 (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if the state size
(:c:data:`Py_mod_state_size`) is greater than 0 and the module state
(as returned by :c:func:`PyModule_GetState`) is ``NULL``.
.. versionadded:: next
Use :c:member:`PyModuleDef.m_free` instead to support previous versions.
.. _ext-module-token:
Module token
............
Each module may have an associated *token*: a pointer-sized value intended to
identify of the module state's memory layout.
This means that if you have a module object, but you are not sure if it
“belongs” to your extension, you can check using code like this:
.. code-block:: c .. code-block:: c
PyABIInfo_VAR(abi_info); PyObject *module = <the module in question>
static PyModuleDef_Slot mymodule_slots[] = { void *module_token;
{Py_mod_abi, &abi_info}, if (PyModule_GetToken(module, &module_token) < 0) {
... return NULL;
}; }
if (module_token != your_token) {
PyErr_SetString(PyExc_ValueError, "unexpected module")
return NULL;
}
.. versionadded:: 3.15 // This module's state has the expected memory layout; it's safe to cast
struct my_state state = (struct my_state*)PyModule_GetState(module)
A module's token -- and the *your_token* value to use in the above code -- is:
- For modules created with :c:type:`PyModuleDef`: the address of that
:c:type:`PyModuleDef`;
- For modules defined with the :c:macro:`Py_mod_token` slot: the value
of that slot;
- For modules created from an ``PyModExport_*``
:ref:`export hook <extension-export-hook>`: the slots array that the export
hook returned (unless overriden with :c:macro:`Py_mod_token`).
.. c:macro:: Py_mod_token
:c:type:`Slot ID <PyModuleDef_Slot.slot>` for the module token.
If you use this slot to set the module token (rather than rely on the
default), you must ensure that:
* The pointer outlives the class, so it's not reused for something else
while the class exists.
* It "belongs" to the extension module where the class lives, so it will not
clash with other extensions.
* If the token points to a :c:type:`PyModuleDef` struct, the module should
behave as if it was created from that :c:type:`PyModuleDef`.
In particular, the module state must have matching layout and semantics.
Modules created from :c:type:`PyModuleDef` allways use the address of
the :c:type:`PyModuleDef` as the token.
This means that :c:macro:`!Py_mod_token` cannot be used in
:c:member:`PyModuleDef.m_slots`.
.. versionadded:: next
.. c:function:: int PyModule_GetToken(PyObject *module, void** result)
Set *\*result* to the module's token and return 0.
On error, set *\*result* to NULL, and return -1 with an exception set.
.. versionadded:: next
See also :c:func:`PyType_GetModuleByToken`.
.. _moduledef-dynamic: .. _module-from-slots:
Creating extension modules dynamically Creating extension modules dynamically
-------------------------------------- --------------------------------------
The following functions may be used to create a module outside of an The following functions may be used to create an extension module dynamically,
extension's :ref:`initialization function <extension-export-hook>`. rather than from an extension's :ref:`export hook <extension-export-hook>`.
They are also used in
:ref:`single-phase initialization <single-phase-initialization>`. .. c:function:: PyObject *PyModule_FromSlotsAndSpec(const PyModuleDef_Slot *slots, PyObject *spec)
Create a new module object, given an array of :ref:`slots <pymoduledef_slot>`
and the :py:class:`~importlib.machinery.ModuleSpec` *spec*.
The *slots* argument must point to an array of :c:type:`PyModuleDef_Slot`
structures, terminated by an entry slot with slot ID of 0
(typically written as ``{0}`` or ``{0, NULL}`` in C).
The *slots* argument may not be ``NULL``.
The *spec* argument may be any ``ModuleSpec``-like object, as described
in :c:macro:`Py_mod_create` documentation.
Currently, the *spec* must have a ``name`` attribute.
On success, return the new module.
On error, return ``NULL`` with an exception set.
Note that this does not process the module's execution slot
(:c:data:`Py_mod_exec`).
Both :c:func:`!PyModule_FromSlotsAndSpec` and :c:func:`PyModule_Exec`
must be called to fully initialize a module.
(See also :ref:`multi-phase-initialization`.)
The *slots* array only needs to be valid for the duration of the
:c:func:`!PyModule_FromSlotsAndSpec` call.
In particular, it may be heap-allocated.
.. versionadded:: next
.. c:function:: int PyModule_Exec(PyObject *module)
Execute the :c:data:`Py_mod_exec` slot(s) of the given *module*.
On success, return 0.
On error, return -1 with an exception set.
For clarity: If *module* has no slots, for example if it uses
:ref:`legacy single-phase initialization <single-phase-initialization>`,
this function does nothing and returns 0.
.. versionadded:: next
.. _pymoduledef:
Module definition struct
------------------------
Traditionally, extension modules were defined using a *module definition*
as the “description" of how a module should be created.
Rather than using an array of :ref:`slots <pymoduledef_slot>` directly,
the definition has dedicated members for most common functionality,
and allows additional slots as an extension mechanism.
This way of defining modules is still available and there are no plans to
remove it.
.. c:type:: PyModuleDef
The module definition struct, which holds 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
defined this way.
.. c:member:: PyModuleDef_Base m_base
Always initialize this member to :c:macro:`PyModuleDef_HEAD_INIT`:
.. c:namespace:: NULL
.. c:type:: PyModuleDef_Base
The type of :c:member:`!PyModuleDef.m_base`.
.. c:macro:: PyModuleDef_HEAD_INIT
The required initial value for :c:member:`!PyModuleDef.m_base`.
.. c:member:: const char *m_name
Corresponds to the :c:macro:`Py_mod_name` slot.
.. c:member:: const char *m_doc
These members correspond to the :c:macro:`Py_mod_doc` slot.
Setting this to NULL is equivalent to omitting the slot.
.. c:member:: Py_ssize_t m_size
Corresponds to the :c:macro:`Py_mod_state_size` slot.
Setting this to zero is equivalent to omitting the slot.
When using :ref:`legacy single-phase initialization <single-phase-initialization>`
or when creating modules dynamically using :c:func:`PyModule_Create`
or :c:func:`PyModule_Create2`, :c:member:`!m_size` may be set to -1.
This indicates that the module does not support sub-interpreters,
because it has global state.
.. c:member:: PyMethodDef *m_methods
Corresponds to the :c:macro:`Py_mod_methods` slot.
Setting this to NULL is equivalent to omitting the slot.
.. c:member:: PyModuleDef_Slot* m_slots
An array of additional slots, terminated by a ``{0, NULL}`` entry.
This array may not contain slots corresponding to :c:type:`PyModuleDef`
members.
For example, you cannot use :c:macro:`Py_mod_name` in :c:member:`!m_slots`;
the module name must be given as :c:member:`PyModuleDef.m_name`.
.. versionchanged:: 3.5
Prior to version 3.5, this member was always set to ``NULL``,
and was defined as:
.. c:member:: inquiry m_reload
.. c:member:: traverseproc m_traverse
inquiry m_clear
freefunc m_free
These members correspond to the :c:macro:`Py_mod_state_traverse`,
:c:macro:`Py_mod_state_clear`, and :c:macro:`Py_mod_state_free` slots,
respectively.
Setting these members to NULL is equivalent to omitting the
corresponding slots.
.. versionchanged:: 3.9
:c:member:`m_traverse`, :c:member:`m_clear` and :c:member:`m_free`
functions are longer called before the module state is allocated.
.. _moduledef-dynamic:
The following API can be used to create modules from a :c:type:`!PyModuleDef`
struct:
.. c:function:: PyObject* PyModule_Create(PyModuleDef *def) .. c:function:: PyObject* PyModule_Create(PyModuleDef *def)
@ -514,12 +834,13 @@ They are also used in
useful for versioning. This may change in the future. useful for versioning. This may change in the future.
.. _capi-module-support-functions:
Support functions Support functions
----------------- -----------------
The following functions are provided to help initialize a module The following functions are provided to help initialize a module object.
state. They are intended for a module's execution slot (:c:data:`Py_mod_exec`),
They are intended for a module's execution slots (:c:data:`Py_mod_exec`),
the initialization function for legacy :ref:`single-phase initialization <single-phase-initialization>`, the initialization function for legacy :ref:`single-phase initialization <single-phase-initialization>`,
or code that creates modules dynamically. or code that creates modules dynamically.

2
Doc/c-api/structures.rst
View file

@ -280,6 +280,8 @@ Implementing functions and methods
Name of the method. Name of the method.
A ``NULL`` *ml_name* marks the end of a :c:type:`!PyMethodDef` array.
.. c:member:: PyCFunction ml_meth .. c:member:: PyCFunction ml_meth
Pointer to the C implementation. Pointer to the C implementation.

33
Doc/c-api/type.rst
View file

@ -283,8 +283,8 @@ Type Objects
``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses ``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
are not necessarily defined in the same module as their superclass. are not necessarily defined in the same module as their superclass.
See :c:type:`PyCMethod` to get the class that defines the method. See :c:type:`PyCMethod` to get the class that defines the method.
See :c:func:`PyType_GetModuleByDef` for cases when :c:type:`!PyCMethod` cannot See :c:func:`PyType_GetModuleByToken` for cases when :c:type:`!PyCMethod`
be used. cannot be used.
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -304,10 +304,10 @@ Type Objects
.. versionadded:: 3.9 .. versionadded:: 3.9
.. c:function:: PyObject* PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def) .. c:function:: PyObject* PyType_GetModuleByToken(PyTypeObject *type, const void *mod_token)
Find the first superclass whose module was created from Find the first superclass whose module has the given
the given :c:type:`PyModuleDef` *def*, and return that module. :ref:`module token <ext-module-token>`, and return that module.
If no module is found, raises a :py:class:`TypeError` and returns ``NULL``. If no module is found, raises a :py:class:`TypeError` and returns ``NULL``.
@ -317,6 +317,23 @@ Type Objects
and other places where a method's defining class cannot be passed using the and other places where a method's defining class cannot be passed using the
:c:type:`PyCMethod` calling convention. :c:type:`PyCMethod` calling convention.
.. versionadded:: next
.. c:function:: PyObject* PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
Find the first superclass whose module was created from the given
:c:type:`PyModuleDef` *def*, or whose :ref:`module token <ext-module-token>`
is equal to *def*, and return that module.
Note that modules created from a :c:type:`PyModuleDef` always have their
token set to the :c:type:`PyModuleDef`'s address.
In other words, this function is equivalent to
:c:func:`PyType_GetModuleByToken`, except that it:
- returns a borrowed reference, and
- has a non-``void*`` argument type (which is a cosmetic difference in C).
The returned reference is :term:`borrowed <borrowed reference>` from *type*, The returned reference is :term:`borrowed <borrowed reference>` from *type*,
and will be valid as long as you hold a reference to *type*. and will be valid as long as you hold a reference to *type*.
Do not release it with :c:func:`Py_DECREF` or similar. Do not release it with :c:func:`Py_DECREF` or similar.
@ -324,10 +341,10 @@ Type Objects
.. versionadded:: 3.11 .. versionadded:: 3.11
.. c:function:: int PyType_GetBaseByToken(PyTypeObject *type, void *token, PyTypeObject **result) .. c:function:: int PyType_GetBaseByToken(PyTypeObject *type, void *tp_token, PyTypeObject **result)
Find the first superclass in *type*'s :term:`method resolution order` whose Find the first superclass in *type*'s :term:`method resolution order` whose
:c:macro:`Py_tp_token` token is equal to the given one. :c:macro:`Py_tp_token` token is equal to *tp_token*.
* If found, set *\*result* to a new :term:`strong reference` * If found, set *\*result* to a new :term:`strong reference`
to it and return ``1``. to it and return ``1``.
@ -338,7 +355,7 @@ Type Objects
The *result* argument may be ``NULL``, in which case *\*result* is not set. The *result* argument may be ``NULL``, in which case *\*result* is not set.
Use this if you need only the return value. Use this if you need only the return value.
The *token* argument may not be ``NULL``. The *tp_token* argument may not be ``NULL``.
.. versionadded:: 3.14 .. versionadded:: 3.14

19
Doc/data/refcounts.dat
View file

@ -1472,6 +1472,9 @@ PyModule_Create2:PyObject*::+1:
PyModule_Create2:PyModuleDef*:def:: PyModule_Create2:PyModuleDef*:def::
PyModule_Create2:int:module_api_version:: PyModule_Create2:int:module_api_version::
PyModule_Exec:int:::
PyModule_ExecDef:PyObject*:module:0:
PyModule_ExecDef:int::: PyModule_ExecDef:int:::
PyModule_ExecDef:PyObject*:module:0: PyModule_ExecDef:PyObject*:module:0:
PyModule_ExecDef:PyModuleDef*:def:: PyModule_ExecDef:PyModuleDef*:def::
@ -1485,6 +1488,10 @@ PyModule_FromDefAndSpec2:PyModuleDef*:def::
PyModule_FromDefAndSpec2:PyObject*:spec:0: PyModule_FromDefAndSpec2:PyObject*:spec:0:
PyModule_FromDefAndSpec2:int:module_api_version:: PyModule_FromDefAndSpec2:int:module_api_version::
PyModule_FromSlotsAndSpec:PyObject*::+1:
PyModule_FromSlotsAndSpec:const PyModuleDef_Slot *:slots::
PyModule_FromSlotsAndSpec:PyObject*:spec:0:
PyModule_GetDef:PyModuleDef*::0: PyModule_GetDef:PyModuleDef*::0:
PyModule_GetDef:PyObject*:module:0: PyModule_GetDef:PyObject*:module:0:
@ -1506,6 +1513,14 @@ PyModule_GetNameObject:PyObject*:module:0:
PyModule_GetState:void*::: PyModule_GetState:void*:::
PyModule_GetState:PyObject*:module:0: PyModule_GetState:PyObject*:module:0:
PyModule_GetStateSize:int:::
PyModule_GetStateSize:PyObject*:module:0:
PyModule_GetToken:Py_ssize_t**:result::
PyModule_GetToken:int:::
PyModule_GetToken:PyObject*:module:0:
PyModule_GetToken:void**:result::
PyModule_New:PyObject*::+1: PyModule_New:PyObject*::+1:
PyModule_New:char*:name:: PyModule_New:char*:name::
@ -2412,6 +2427,10 @@ PyType_GetFlags:PyTypeObject*:type:0:
PyType_GetName:PyObject*::+1: PyType_GetName:PyObject*::+1:
PyType_GetName:PyTypeObject*:type:0: PyType_GetName:PyTypeObject*:type:0:
PyType_GetModuleByToken:PyObject*::+1:
PyType_GetModuleByToken:PyTypeObject*:type:0:
PyType_GetModuleByToken:PyModuleDef*:def::
PyType_GetModuleByDef:PyObject*::0: PyType_GetModuleByDef:PyObject*::0:
PyType_GetModuleByDef:PyTypeObject*:type:0: PyType_GetModuleByDef:PyTypeObject*:type:0:
PyType_GetModuleByDef:PyModuleDef*:def:: PyType_GetModuleByDef:PyModuleDef*:def::

19
Doc/howto/free-threading-extensions.rst
View file

@ -45,9 +45,12 @@ single-phase initialization.
Multi-Phase Initialization Multi-Phase Initialization
.......................... ..........................
Extensions that use multi-phase initialization (i.e., Extensions that use :ref:`multi-phase initialization <multi-phase-initialization>`
:c:func:`PyModuleDef_Init`) should add a :c:data:`Py_mod_gil` slot in the (functions like :c:func:`PyModuleDef_Init`,
module definition. If your extension supports older versions of CPython, :c:func:`PyModExport_* <PyModExport_modulename>` export hook,
:c:func:`PyModule_FromSlotsAndSpec`) should add a
:c:data:`Py_mod_gil` slot in the module definition.
If your extension supports older versions of CPython,
you should guard the slot with a :c:data:`PY_VERSION_HEX` check. you should guard the slot with a :c:data:`PY_VERSION_HEX` check.
:: ::
@ -60,18 +63,12 @@ you should guard the slot with a :c:data:`PY_VERSION_HEX` check.
{0, NULL} {0, NULL}
}; };
static struct PyModuleDef moduledef = {
PyModuleDef_HEAD_INIT,
.m_slots = module_slots,
...
};
Single-Phase Initialization Single-Phase Initialization
........................... ...........................
Extensions that use single-phase initialization (i.e., Extensions that use legacy :ref:`single-phase initialization <single-phase-initialization>`
:c:func:`PyModule_Create`) should call :c:func:`PyUnstable_Module_SetGIL` to (that is, :c:func:`PyModule_Create`) should call :c:func:`PyUnstable_Module_SetGIL` to
indicate that they support running with the GIL disabled. The function is indicate that they support running with the GIL disabled. The function is
only defined in the free-threaded build, so you should guard the call with only defined in the free-threaded build, so you should guard the call with
``#ifdef Py_GIL_DISABLED`` to avoid compilation errors in the regular build. ``#ifdef Py_GIL_DISABLED`` to avoid compilation errors in the regular build.

1
Doc/tools/.nitignore
View file

@ -6,7 +6,6 @@ Doc/c-api/descriptor.rst
Doc/c-api/float.rst Doc/c-api/float.rst
Doc/c-api/init_config.rst Doc/c-api/init_config.rst
Doc/c-api/intro.rst Doc/c-api/intro.rst
Doc/c-api/module.rst
Doc/c-api/stable.rst Doc/c-api/stable.rst
Doc/c-api/typeobj.rst Doc/c-api/typeobj.rst
Doc/library/ast.rst Doc/library/ast.rst