mirror of
https://github.com/python/cpython.git
synced 2025-12-07 13:50:06 +00:00
gh-140550: PEP 793 reference documentation (GH-141197)
* 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
GitHub
parent
8c33c6143e
commit
d7f0214f13
9 changed files with 772 additions and 321 deletions
|
|
@ -8,7 +8,8 @@ Defining extension modules
|
|||
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
|
||||
(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
|
||||
: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
|
||||
https://setuptools.pypa.io/en/latest/setuptools.html.
|
||||
|
||||
Normally, the initialization function returns a module definition initialized
|
||||
using :c:func:`PyModuleDef_Init`.
|
||||
This allows splitting the creation process into several phases:
|
||||
.. _extension-export-hook:
|
||||
|
||||
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
|
||||
capabilities the module supports, and it can adjust the environment or
|
||||
refuse loading an incompatible extension.
|
||||
- By default, Python itself creates the module object -- that is, it does
|
||||
the equivalent of :py:meth:`object.__new__` for classes.
|
||||
It also sets initial attributes like :attr:`~module.__package__` and
|
||||
:attr:`~module.__loader__`.
|
||||
- Afterwards, the module object is initialized using extension-specific
|
||||
code -- the equivalent of :py:meth:`~object.__init__` on classes.
|
||||
Slots like :c:data:`Py_mod_abi`, :c:data:`Py_mod_gil` and
|
||||
:c:data:`Py_mod_multiple_interpreters` influence this step.
|
||||
- By default, Python itself then creates the module object -- that is, it does
|
||||
the equivalent of calling :py:meth:`~object.__new__` when creating an object.
|
||||
This step can be overridden using the :c:data:`Py_mod_create` slot.
|
||||
- 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
|
||||
(but still supported) *single-phase initialization* scheme,
|
||||
where the initialization function returns a fully constructed module.
|
||||
See the :ref:`single-phase-initialization section below <single-phase-initialization>`
|
||||
for details.
|
||||
(but still supported) :ref:`single-phase initialization <single-phase-initialization>`,
|
||||
where an initialization function returns a fully constructed module.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
|
||||
|
|
@ -53,7 +156,7 @@ Multiple module instances
|
|||
|
||||
By default, extension modules are not singletons.
|
||||
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.
|
||||
The old module is subject to normal garbage collection.
|
||||
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.
|
||||
|
||||
|
||||
.. _extension-export-hook:
|
||||
.. _extension-pyinit:
|
||||
|
||||
Initialization function
|
||||
.......................
|
||||
``PyInit`` function
|
||||
...................
|
||||
|
||||
The initialization function defined by an extension module has the
|
||||
following signature:
|
||||
.. deprecated:: next
|
||||
|
||||
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)
|
||||
|
||||
Its name should be :samp:`PyInit_{<name>}`, with ``<name>`` replaced by the
|
||||
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
|
||||
:samp:`PyInit_{<name>}`, with ``<name>`` replaced by the name of the module.
|
||||
When using :ref:`multi-phase-initialization`, non-ASCII module names
|
||||
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:
|
||||
If a module exports both :samp:`PyInit_{<name>}` and
|
||||
:samp:`PyModExport_{<name>}`, the :samp:`PyInit_{<name>}` function
|
||||
is ignored.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
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:
|
||||
Like with :c:macro:`PyMODEXPORT_FUNC`, it is recommended to define the
|
||||
initialization function using a helper macro:
|
||||
|
||||
.. 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
|
||||
* 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::
|
||||
|
||||
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);
|
||||
}
|
||||
|
||||
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:
|
||||
|
||||
Legacy single-phase initialization
|
||||
..................................
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. attention::
|
||||
Single-phase initialization is a legacy mechanism to initialize extension
|
||||
.. deprecated:: next
|
||||
|
||||
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
|
||||
are encouraged to use multi-phase initialization instead.
|
||||
|
||||
In single-phase initialization, the
|
||||
:ref:`initialization function <extension-export-hook>` (``PyInit_modulename``)
|
||||
However, there are no plans to remove support for it.
|
||||
|
||||
In single-phase initialization, the old-style
|
||||
:ref:`initializaton function <extension-pyinit>` (``PyInit_modulename``)
|
||||
should create, populate and return a module object.
|
||||
This is typically done using :c:func:`PyModule_Create` and functions like
|
||||
:c:func:`PyModule_AddObjectRef`.
|
||||
|
|
@ -242,6 +335,8 @@ in the following ways:
|
|||
* Single-phase modules support module lookup functions like
|
||||
:c:func:`PyState_FindModule`.
|
||||
|
||||
* The module's :c:member:`PyModuleDef.m_slots` must be NULL.
|
||||
|
||||
.. [#testsinglephase] ``_testsinglephase`` is an internal module used
|
||||
in CPython's self-test suite; your installation may or may not
|
||||
include it.
|
||||
|
|
|
|||
|
|
@ -353,7 +353,7 @@ Importing Modules
|
|||
the same as for :c:func:`PyImport_AppendInittab`.
|
||||
|
||||
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.
|
||||
(Custom importers should do this in their
|
||||
:py:meth:`~importlib.abc.Loader.exec_module` method.)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
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
|
||||
is imported, it is initialized normally, and a (shallow) copy of its
|
||||
module's dictionary is squirreled away.
|
||||
|
|
|
|||
|
|
@ -3,11 +3,10 @@
|
|||
.. _moduleobjects:
|
||||
|
||||
Module Objects
|
||||
--------------
|
||||
==============
|
||||
|
||||
.. index:: pair: object; module
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyModule_Type
|
||||
|
||||
.. 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__`
|
||||
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)
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _pymoduledef:
|
||||
.. _pymoduledef_slot:
|
||||
|
||||
Module definitions
|
||||
------------------
|
||||
Module definition
|
||||
-----------------
|
||||
|
||||
The functions in the previous section work on any module object, including
|
||||
modules imported from Python code.
|
||||
Modules created using the C API are typically defined using an
|
||||
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*,
|
||||
:c:type:`PyModuleDef` -- a statically allocated, constant “description" of
|
||||
how a module should be created.
|
||||
.. versionchanged:: next
|
||||
|
||||
The definition is usually used to define an extension's “main” module object
|
||||
(see :ref:`extension-modules` for details).
|
||||
It is also used to
|
||||
:ref:`create extension modules dynamically <moduledef-dynamic>`.
|
||||
Previously, a :c:type:`PyModuleDef` struct was necessary to define modules.
|
||||
The older way of defining modules is still available: consult either the
|
||||
:ref:`pymoduledef` section or earlier versions of this documentation
|
||||
if you plan to support earlier Python versions.
|
||||
|
||||
Unlike :c:func:`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.
|
||||
The slots array is usually used to define an extension module's “main”
|
||||
module object (see :ref:`extension-modules` for details).
|
||||
It can also be used to
|
||||
:ref:`create extension modules dynamically <module-from-slots>`.
|
||||
|
||||
.. 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: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
|
||||
|
||||
Value of the slot, whose meaning depends on the slot ID.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
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``.
|
||||
The value may not be NULL.
|
||||
To leave a slot out, omit the :c:type:`PyModuleDef_Slot` entry entirely.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. c:macro:: Py_mod_exec
|
||||
|
||||
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:
|
||||
Metadata slots
|
||||
..............
|
||||
|
||||
.. c:function:: int exec_module(PyObject* module)
|
||||
:no-index-entry:
|
||||
:no-contents-entry:
|
||||
.. c:macro:: Py_mod_name
|
||||
|
||||
If multiple ``Py_mod_exec`` slots are specified, they are processed in the
|
||||
order they appear in the *m_slots* array.
|
||||
:c:type:`Slot ID <PyModuleDef_Slot.slot>` for the name of the new module,
|
||||
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
|
||||
|
||||
Specifies one of the following values:
|
||||
:c:type:`Slot ID <PyModuleDef_Slot.slot>` whose value is one of:
|
||||
|
||||
.. c:namespace:: NULL
|
||||
|
||||
|
|
@ -371,9 +257,6 @@ The available slot types are:
|
|||
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``.
|
||||
|
||||
|
|
@ -381,7 +264,7 @@ The available slot types are:
|
|||
|
||||
.. 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
|
||||
|
||||
|
|
@ -399,45 +282,482 @@ The available slot types are:
|
|||
this module will cause the GIL to be automatically enabled. See
|
||||
: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
|
||||
``Py_MOD_GIL_USED``.
|
||||
|
||||
.. versionadded:: 3.13
|
||||
|
||||
.. c:macro:: Py_mod_abi
|
||||
|
||||
A pointer to a :c:struct:`PyABIInfo` structure that describes the ABI that
|
||||
the extension is using.
|
||||
Creation and initialization slots
|
||||
.................................
|
||||
|
||||
When the module is loaded, the :c:struct:`!PyABIInfo` in this slot is checked
|
||||
using :c:func:`PyABIInfo_Check`.
|
||||
.. c:macro:: Py_mod_create
|
||||
|
||||
A suitable :c:struct:`!PyABIInfo` variable can be defined using the
|
||||
:c:macro:`PyABIInfo_VAR` macro, as in:
|
||||
:c:type:`Slot ID <PyModuleDef_Slot.slot>` for a function that creates
|
||||
the module object itself.
|
||||
The function must have the signature:
|
||||
|
||||
.. code-block:: c
|
||||
.. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
|
||||
:no-index-entry:
|
||||
:no-contents-entry:
|
||||
|
||||
PyABIInfo_VAR(abi_info);
|
||||
The function will be called with:
|
||||
|
||||
static PyModuleDef_Slot mymodule_slots[] = {
|
||||
{Py_mod_abi, &abi_info},
|
||||
...
|
||||
};
|
||||
- *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.
|
||||
|
||||
.. versionadded:: 3.15
|
||||
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.
|
||||
|
||||
|
||||
.. _moduledef-dynamic:
|
||||
.. 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
|
||||
|
||||
PyObject *module = <the module in question>
|
||||
|
||||
void *module_token;
|
||||
if (PyModule_GetToken(module, &module_token) < 0) {
|
||||
return NULL;
|
||||
}
|
||||
if (module_token != your_token) {
|
||||
PyErr_SetString(PyExc_ValueError, "unexpected module")
|
||||
return NULL;
|
||||
}
|
||||
|
||||
// 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`.
|
||||
|
||||
|
||||
.. _module-from-slots:
|
||||
|
||||
Creating extension modules dynamically
|
||||
--------------------------------------
|
||||
|
||||
The following functions may be used to create a module outside of an
|
||||
extension's :ref:`initialization function <extension-export-hook>`.
|
||||
They are also used in
|
||||
:ref:`single-phase initialization <single-phase-initialization>`.
|
||||
The following functions may be used to create an extension module dynamically,
|
||||
rather than from an extension's :ref:`export hook <extension-export-hook>`.
|
||||
|
||||
.. 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)
|
||||
|
||||
|
|
@ -514,12 +834,13 @@ They are also used in
|
|||
useful for versioning. This may change in the future.
|
||||
|
||||
|
||||
.. _capi-module-support-functions:
|
||||
|
||||
Support functions
|
||||
-----------------
|
||||
|
||||
The following functions are provided to help initialize a module
|
||||
state.
|
||||
They are intended for a module's execution slots (:c:data:`Py_mod_exec`),
|
||||
The following functions are provided to help initialize a module object.
|
||||
They are intended for a module's execution slot (:c:data:`Py_mod_exec`),
|
||||
the initialization function for legacy :ref:`single-phase initialization <single-phase-initialization>`,
|
||||
or code that creates modules dynamically.
|
||||
|
||||
|
|
|
|||
|
|
@ -280,6 +280,8 @@ Implementing functions and methods
|
|||
|
||||
Name of the method.
|
||||
|
||||
A ``NULL`` *ml_name* marks the end of a :c:type:`!PyMethodDef` array.
|
||||
|
||||
.. c:member:: PyCFunction ml_meth
|
||||
|
||||
Pointer to the C implementation.
|
||||
|
|
|
|||
|
|
@ -283,8 +283,8 @@ Type Objects
|
|||
``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
|
||||
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:func:`PyType_GetModuleByDef` for cases when :c:type:`!PyCMethod` cannot
|
||||
be used.
|
||||
See :c:func:`PyType_GetModuleByToken` for cases when :c:type:`!PyCMethod`
|
||||
cannot be used.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
|
|
@ -304,10 +304,10 @@ Type Objects
|
|||
.. 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
|
||||
the given :c:type:`PyModuleDef` *def*, and return that module.
|
||||
Find the first superclass whose module has the given
|
||||
:ref:`module token <ext-module-token>`, and return that module.
|
||||
|
||||
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
|
||||
: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*,
|
||||
and will be valid as long as you hold a reference to *type*.
|
||||
Do not release it with :c:func:`Py_DECREF` or similar.
|
||||
|
|
@ -324,10 +341,10 @@ Type Objects
|
|||
.. 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
|
||||
: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`
|
||||
to it and return ``1``.
|
||||
|
|
@ -338,7 +355,7 @@ Type Objects
|
|||
The *result* argument may be ``NULL``, in which case *\*result* is not set.
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -1472,6 +1472,9 @@ PyModule_Create2:PyObject*::+1:
|
|||
PyModule_Create2:PyModuleDef*:def::
|
||||
PyModule_Create2:int:module_api_version::
|
||||
|
||||
PyModule_Exec:int:::
|
||||
PyModule_ExecDef:PyObject*:module:0:
|
||||
|
||||
PyModule_ExecDef:int:::
|
||||
PyModule_ExecDef:PyObject*:module:0:
|
||||
PyModule_ExecDef:PyModuleDef*:def::
|
||||
|
|
@ -1485,6 +1488,10 @@ PyModule_FromDefAndSpec2:PyModuleDef*:def::
|
|||
PyModule_FromDefAndSpec2:PyObject*:spec:0:
|
||||
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:PyObject*:module:0:
|
||||
|
||||
|
|
@ -1506,6 +1513,14 @@ PyModule_GetNameObject:PyObject*:module:0:
|
|||
PyModule_GetState:void*:::
|
||||
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:char*:name::
|
||||
|
||||
|
|
@ -2412,6 +2427,10 @@ PyType_GetFlags:PyTypeObject*:type:0:
|
|||
PyType_GetName:PyObject*::+1:
|
||||
PyType_GetName:PyTypeObject*:type:0:
|
||||
|
||||
PyType_GetModuleByToken:PyObject*::+1:
|
||||
PyType_GetModuleByToken:PyTypeObject*:type:0:
|
||||
PyType_GetModuleByToken:PyModuleDef*:def::
|
||||
|
||||
PyType_GetModuleByDef:PyObject*::0:
|
||||
PyType_GetModuleByDef:PyTypeObject*:type:0:
|
||||
PyType_GetModuleByDef:PyModuleDef*:def::
|
||||
|
|
|
|||
|
|
@ -45,9 +45,12 @@ single-phase initialization.
|
|||
Multi-Phase Initialization
|
||||
..........................
|
||||
|
||||
Extensions that use multi-phase initialization (i.e.,
|
||||
:c:func:`PyModuleDef_Init`) should add a :c:data:`Py_mod_gil` slot in the
|
||||
module definition. If your extension supports older versions of CPython,
|
||||
Extensions that use :ref:`multi-phase initialization <multi-phase-initialization>`
|
||||
(functions like :c:func:`PyModuleDef_Init`,
|
||||
: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.
|
||||
|
||||
::
|
||||
|
|
@ -60,18 +63,12 @@ you should guard the slot with a :c:data:`PY_VERSION_HEX` check.
|
|||
{0, NULL}
|
||||
};
|
||||
|
||||
static struct PyModuleDef moduledef = {
|
||||
PyModuleDef_HEAD_INIT,
|
||||
.m_slots = module_slots,
|
||||
...
|
||||
};
|
||||
|
||||
|
||||
Single-Phase Initialization
|
||||
...........................
|
||||
|
||||
Extensions that use single-phase initialization (i.e.,
|
||||
:c:func:`PyModule_Create`) should call :c:func:`PyUnstable_Module_SetGIL` to
|
||||
Extensions that use legacy :ref:`single-phase initialization <single-phase-initialization>`
|
||||
(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
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,6 @@ Doc/c-api/descriptor.rst
|
|||
Doc/c-api/float.rst
|
||||
Doc/c-api/init_config.rst
|
||||
Doc/c-api/intro.rst
|
||||
Doc/c-api/module.rst
|
||||
Doc/c-api/stable.rst
|
||||
Doc/c-api/typeobj.rst
|
||||
Doc/library/ast.rst
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue