From 1f8d65e0763b3c87f1b990c15d17bd49a99ffb7c Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 8 Nov 2025 10:05:02 -0500 Subject: [PATCH 1/8] Document missing PyCFunction APIs. --- Doc/c-api/structures.rst | 64 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 58dd915e04f619..b33878de4e698b 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -472,6 +472,24 @@ definition with the same method name. .. versionadded:: 3.9 +.. c:var:: PyTypeObject PyCFunction_Type + + The type object corresponding to Python C function objects. This is + available as :class:`types.BuiltinFunctionType` in the Python layer. + + +.. c:function:: int PyCFunction_Check(PyObject *f) + + Return true if *f* is an instance of the :c:type:`PyCFunction_Type` type + or a subtype of it. This function always succeeds. + + +.. c:function:: int PyCFunction_CheckExact(PyObject *f) + + This is the same as :c:func:`PyCFunction_Check`, but does not account for + subtypes. + + .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) Equivalent to ``PyCMethod_New(ml, self, module, NULL)``. @@ -482,6 +500,52 @@ definition with the same method name. Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``. +.. c:function:: int PyCFunction_GetFlags(PyObject *func) + + Get the function flags on *func* as they were passed to + :c:member:`~PyMethodDef.ml_flags`. + + This function returns the function's flags on success, and ``-1`` with an + exception set on failure. + + +.. c:function:: int PyCFunction_GET_FLAGS(PyObject *func) + + This is the same as :c:func:`PyCFunction_GetFlags`, but without error + checking. + + +.. c:function:: PyCFunction PyCFunction_GetFunction(PyObject *func) + + Get the function pointer on *func* as it was passed to + :c:member:`~PyMethodDef.ml_meth`. + + This function returns the function pointer on success, and ``NULL`` with an + exception set on failure. + + +.. c:function:: int PyCFunction_GET_FUNCTION(PyObject *func) + + This is the same as :c:func:`PyCFunction_GetFunction`, but without error + checking. + + +.. c:function:: PyObject *PyCFunction_GetSelf(PyObject *func) + + Get the "self" object on *func*. This is the object that would be passed + to the first argument of a :c:type:`PyCFunction`. In modules, this is the + module object. + + This function returns a :term:`borrowed reference` to the "self" object + on success, and ``NULL`` with an exception set on failure. + + +.. c:function:: PyObject *PyCFunction_GET_SELF(PyObject *func) + + This is the same as :c:func:`PyCFunction_GetSelf`, but without error + checking. + + Accessing attributes of extension types --------------------------------------- From a0cf7ecd9ae03786da1258aaa8881bf4821ff391 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 8 Nov 2025 10:06:58 -0500 Subject: [PATCH 2/8] Document missing PyCMethod APIs. --- Doc/c-api/structures.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index b33878de4e698b..c708a9f4381528 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -447,6 +447,25 @@ definition with the same method name. slot. This is helpful because calls to PyCFunctions are optimized more than wrapper object calls. + +.. c:var:: PyTypeObject PyCMethod_Type + + The type object corresponding to Python C method objects. This is + available as :class:`types.BuiltinMethodType` in the Python layer. + + +.. c:function:: int PyCMethod_Check(PyObject *f) + + Return true if *f* is an instance of the :c:type:`PyCMethod_Type` type + or a subtype of it. This function always succeeds. + + +.. c:function:: int PyCMethod_CheckExact(PyObject *f) + + This is the same as :c:func:`PyCMethod_Check`, but does not account for + subtypes. + + .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) Turn *ml* into a Python :term:`callable` object. From 4ac3cf6b5fd77ffd32e5876e72d44d99057b5594 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 15 Nov 2025 14:06:08 -0500 Subject: [PATCH 3/8] Apply suggestion from @picnixz MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/c-api/structures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index c708a9f4381528..188273160ef14a 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -521,7 +521,7 @@ definition with the same method name. .. c:function:: int PyCFunction_GetFlags(PyObject *func) - Get the function flags on *func* as they were passed to + Get the function's flags on *func* as they were passed to :c:member:`~PyMethodDef.ml_flags`. This function returns the function's flags on success, and ``-1`` with an From e059d661621fb1bc61b45f7f1c12eccdce3ded2d Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 15 Nov 2025 14:05:20 -0500 Subject: [PATCH 4/8] "f" -> "op" --- Doc/c-api/structures.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 188273160ef14a..23874d5d4b2fa3 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -454,13 +454,13 @@ definition with the same method name. available as :class:`types.BuiltinMethodType` in the Python layer. -.. c:function:: int PyCMethod_Check(PyObject *f) +.. c:function:: int PyCMethod_Check(PyObject *op) - Return true if *f* is an instance of the :c:type:`PyCMethod_Type` type + Return true if *op* is an instance of the :c:type:`PyCMethod_Type` type or a subtype of it. This function always succeeds. -.. c:function:: int PyCMethod_CheckExact(PyObject *f) +.. c:function:: int PyCMethod_CheckExact(PyObject *op) This is the same as :c:func:`PyCMethod_Check`, but does not account for subtypes. @@ -497,13 +497,13 @@ definition with the same method name. available as :class:`types.BuiltinFunctionType` in the Python layer. -.. c:function:: int PyCFunction_Check(PyObject *f) +.. c:function:: int PyCFunction_Check(PyObject *op) - Return true if *f* is an instance of the :c:type:`PyCFunction_Type` type + Return true if *op* is an instance of the :c:type:`PyCFunction_Type` type or a subtype of it. This function always succeeds. -.. c:function:: int PyCFunction_CheckExact(PyObject *f) +.. c:function:: int PyCFunction_CheckExact(PyObject *op) This is the same as :c:func:`PyCFunction_Check`, but does not account for subtypes. From ed05eba06e0246a08495c587e2f0c3c72ca344dd Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 15 Nov 2025 14:09:14 -0500 Subject: [PATCH 5/8] Clarify behavior of GET* vs Get* --- Doc/c-api/structures.rst | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 23874d5d4b2fa3..143c5945f32f99 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -524,6 +524,9 @@ definition with the same method name. Get the function's flags on *func* as they were passed to :c:member:`~PyMethodDef.ml_flags`. + If *func* is not a C function object, this fails with a + :class:`SystemError`. + This function returns the function's flags on success, and ``-1`` with an exception set on failure. @@ -531,7 +534,7 @@ definition with the same method name. .. c:function:: int PyCFunction_GET_FLAGS(PyObject *func) This is the same as :c:func:`PyCFunction_GetFlags`, but without error - checking. + or type checking. .. c:function:: PyCFunction PyCFunction_GetFunction(PyObject *func) @@ -539,14 +542,18 @@ definition with the same method name. Get the function pointer on *func* as it was passed to :c:member:`~PyMethodDef.ml_meth`. + If *func* is not a C function object, this fails with a + :class:`SystemError`. + This function returns the function pointer on success, and ``NULL`` with an exception set on failure. + .. c:function:: int PyCFunction_GET_FUNCTION(PyObject *func) This is the same as :c:func:`PyCFunction_GetFunction`, but without error - checking. + or type checking. .. c:function:: PyObject *PyCFunction_GetSelf(PyObject *func) @@ -555,14 +562,17 @@ definition with the same method name. to the first argument of a :c:type:`PyCFunction`. In modules, this is the module object. + If *func* is not a C function object, this fails with a + :class:`SystemError`. + This function returns a :term:`borrowed reference` to the "self" object on success, and ``NULL`` with an exception set on failure. .. c:function:: PyObject *PyCFunction_GET_SELF(PyObject *func) - This is the same as :c:func:`PyCFunction_GetSelf`, but without error - checking. + This is the same as :c:func:`PyCFunction_GetSelf`, but without error or + type checking. Accessing attributes of extension types From 7bf86c73ff68f572d754fe5112fb256a5a1a49c7 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 15 Nov 2025 14:10:29 -0500 Subject: [PATCH 6/8] Clarify behavior for modules. --- Doc/c-api/structures.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 143c5945f32f99..dad2b9f48d0f67 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -559,8 +559,9 @@ definition with the same method name. .. c:function:: PyObject *PyCFunction_GetSelf(PyObject *func) Get the "self" object on *func*. This is the object that would be passed - to the first argument of a :c:type:`PyCFunction`. In modules, this is the - module object. + to the first argument of a :c:type:`PyCFunction`. For C function objects + created through a :c:type:`PyMethodDef` on a :c:type:`PyModuleDef`, this + is the resulting module object. If *func* is not a C function object, this fails with a :class:`SystemError`. From 0067054675303d65dee69a5a1ebcb190c332cc27 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sun, 16 Nov 2025 13:31:48 -0500 Subject: [PATCH 7/8] Clarify arguments again. --- Doc/c-api/structures.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index dad2b9f48d0f67..e213444cc26293 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -524,8 +524,8 @@ definition with the same method name. Get the function's flags on *func* as they were passed to :c:member:`~PyMethodDef.ml_flags`. - If *func* is not a C function object, this fails with a - :class:`SystemError`. + If *func* is not a C function object, this fails with an exception. + *func* must not be ``NULL``. This function returns the function's flags on success, and ``-1`` with an exception set on failure. @@ -542,8 +542,8 @@ definition with the same method name. Get the function pointer on *func* as it was passed to :c:member:`~PyMethodDef.ml_meth`. - If *func* is not a C function object, this fails with a - :class:`SystemError`. + If *func* is not a C function object, this fails with an exception. + *func* must not be ``NULL``. This function returns the function pointer on success, and ``NULL`` with an exception set on failure. @@ -563,8 +563,8 @@ definition with the same method name. created through a :c:type:`PyMethodDef` on a :c:type:`PyModuleDef`, this is the resulting module object. - If *func* is not a C function object, this fails with a - :class:`SystemError`. + If *func* is not a C function object, this fails with an exception. + *func* must not be ``NULL``. This function returns a :term:`borrowed reference` to the "self" object on success, and ``NULL`` with an exception set on failure. From b9774f39a493162a6fddbfee0c1c349289c2e5ba Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sun, 16 Nov 2025 14:19:52 -0500 Subject: [PATCH 8/8] Fix extra newline. --- Doc/c-api/structures.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index e213444cc26293..414dfdc84e61c9 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -549,7 +549,6 @@ definition with the same method name. exception set on failure. - .. c:function:: int PyCFunction_GET_FUNCTION(PyObject *func) This is the same as :c:func:`PyCFunction_GetFunction`, but without error