bpo-38787: C API for module state access from extension methods (PEP 573) (GH-19936)
Module C state is now accessible from C-defined heap type methods (PEP 573).
Patch by Marcel Plch and Petr Viktorin.
Co-authored-by: Marcel Plch <mplch@redhat.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index fc3467b..72c9445 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -147,23 +147,56 @@
value of the function as exposed in Python. The function must return a new
reference.
+ The function signature is::
+
+ PyObject *PyCFunction(PyObject *self,
+ PyObject *const *args);
.. c:type:: PyCFunctionWithKeywords
Type of the functions used to implement Python callables in C
with signature :const:`METH_VARARGS | METH_KEYWORDS`.
+ The function signature is::
+
+ PyObject *PyCFunctionWithKeywords(PyObject *self,
+ PyObject *const *args,
+ PyObject *kwargs);
.. c:type:: _PyCFunctionFast
Type of the functions used to implement Python callables in C
with signature :const:`METH_FASTCALL`.
+ The function signature is::
+ PyObject *_PyCFunctionFast(PyObject *self,
+ PyObject *const *args,
+ Py_ssize_t nargs);
.. c:type:: _PyCFunctionFastWithKeywords
Type of the functions used to implement Python callables in C
with signature :const:`METH_FASTCALL | METH_KEYWORDS`.
+ The function signature is::
+
+ PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
+ PyObject *const *args,
+ Py_ssize_t nargs,
+ PyObject *kwnames);
+
+.. c:type:: PyCMethod
+
+ Type of the functions used to implement Python callables in C
+ with signature :const:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`.
+ The function signature is::
+
+ PyObject *PyCMethod(PyObject *self,
+ PyTypeObject *defining_class,
+ PyObject *const *args,
+ Py_ssize_t nargs,
+ PyObject *kwnames)
+
+ .. versionadded:: 3.9
.. c:type:: PyMethodDef
@@ -197,9 +230,7 @@
The individual flags indicate either a calling convention or a binding
convention.
-There are four basic calling conventions for positional arguments
-and two of them can be combined with :const:`METH_KEYWORDS` to support
-also keyword arguments. So there are a total of 6 calling conventions:
+There are these calling conventions:
.. data:: METH_VARARGS
@@ -250,6 +281,19 @@
.. versionadded:: 3.7
+.. data:: METH_METHOD | METH_FASTCALL | METH_KEYWORDS
+
+ Extension of :const:`METH_FASTCALL | METH_KEYWORDS` supporting the *defining
+ class*, that is, the class that contains the method in question.
+ The defining class might be a superclass of ``Py_TYPE(self)``.
+
+ The method needs to be of type :c:type:`PyCMethod`, the same as for
+ ``METH_FASTCALL | METH_KEYWORDS`` with ``defining_class`` argument added after
+ ``self``.
+
+ .. versionadded:: 3.9
+
+
.. data:: METH_NOARGS
Methods without parameters don't need to check whether arguments are given if
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index f774ca3..7dd393f 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -109,6 +109,30 @@
.. versionadded:: 3.4
+.. c:function:: PyObject* PyType_GetModule(PyTypeObject *type)
+
+ Return the module object associated with the given type when the type was
+ created using :c:func:`PyType_FromModuleAndSpec`.
+
+ If no module is associated with the given type, sets :py:class:`TypeError`
+ and returns ``NULL``.
+
+ .. versionadded:: 3.9
+
+.. c:function:: void* PyType_GetModuleState(PyTypeObject *type)
+
+ Return the state of the module object associated with the given type.
+ This is a shortcut for calling :c:func:`PyModule_GetState()` on the result
+ of :c:func:`PyType_GetModule`.
+
+ If no module is associated with the given type, sets :py:class:`TypeError`
+ and returns ``NULL``.
+
+ If the *type* has an associated module but its state is ``NULL``,
+ returns ``NULL`` without setting an exception.
+
+ .. versionadded:: 3.9
+
Creating Heap-Allocated Types
.............................
@@ -116,7 +140,7 @@
The following functions and structs are used to create
:ref:`heap types <heap-types>`.
-.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
+.. c:function:: PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
Creates and returns a heap type object from the *spec*
(:const:`Py_TPFLAGS_HEAPTYPE`).
@@ -127,8 +151,18 @@
If *bases* is ``NULL``, the *Py_tp_base* slot is used instead.
If that also is ``NULL``, the new type derives from :class:`object`.
+ The *module* must be a module object or ``NULL``.
+ If not ``NULL``, the module is associated with the new type and can later be
+ retreived with :c:func:`PyType_GetModule`.
+
This function calls :c:func:`PyType_Ready` on the new type.
+ .. versionadded:: 3.9
+
+.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
+
+ Equivalent to ``PyType_FromModuleAndSpec(NULL, spec, bases)``.
+
.. versionadded:: 3.3
.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)