From 9240c4459f5d05307a48486a5f8c850c96ed1967 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 20 Jun 2025 10:35:17 -0400 Subject: [PATCH 01/11] Add documentation for missing PyFunction_GET* macros --- Doc/c-api/function.rst | 43 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst index 63b78f677674e9..44d69e2900b777 100644 --- a/Doc/c-api/function.rst +++ b/Doc/c-api/function.rst @@ -57,11 +57,21 @@ There are a few functions specific to Python functions. Return the code object associated with the function object *op*. +.. c:function:: PyObject *PyFunction_GET_CODE(PyObject *op) + + Equivalent to :c:func:`PyFunction_GetCode`, but without error checking. + + .. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op) Return the globals dictionary associated with the function object *op*. +.. c:function:: PyObject *PyFunction_GET_GLOBALS(PyObject *op) + + Equivalent to :c:func:`PyFunction_GetGlobals`, but without error checking. + + .. c:function:: PyObject* PyFunction_GetModule(PyObject *op) Return a :term:`borrowed reference` to the :attr:`~function.__module__` @@ -72,12 +82,22 @@ There are a few functions specific to Python functions. but can be set to any other object by Python code. +.. c:function:: PyObject *PyFunction_GET_MODULE(PyObject *op) + + Equivalent to :c:func:`PyFunction_GetModule`, but without error checking. + + .. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op) Return the argument default values of the function object *op*. This can be a tuple of arguments or ``NULL``. +.. c:function:: PyObject *PyFunction_GET_DEFAULTS(PyObject *op) + + Equivalent to :c:func:`PyFunction_GetDefaults`, but without error checking. + + .. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults) Set the argument default values for the function object *op*. *defaults* must be @@ -95,12 +115,29 @@ There are a few functions specific to Python functions. .. versionadded:: 3.12 + +.. c:function:: PyObject* PyFunction_GetKwDefaults(PyObject *op) + + Return the keyword-argument default values of the function object *op*. This can be a + tuple of arguments or ``NULL``. + + +.. c:function:: PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op) + + Equivalent to :c:func:`PyFunction_GetKwDefaults`, but without error checking. + + .. c:function:: PyObject* PyFunction_GetClosure(PyObject *op) Return the closure associated with the function object *op*. This can be ``NULL`` or a tuple of cell objects. +.. c:function:: PyObject *PyFunction_GET_CLOSURE(PyObject *op) + + Equivalent to :c:func:`PyFunction_GetClosure`, but without error checking. + + .. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure) Set the closure associated with the function object *op*. *closure* must be @@ -115,6 +152,11 @@ There are a few functions specific to Python functions. mutable dictionary or ``NULL``. +.. c:function:: PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op) + + Equivalent to :c:func:`PyFunction_GetAnnotations`, but without error checking. + + .. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations) Set the annotations for the function object *op*. *annotations* @@ -193,3 +235,4 @@ There are a few functions specific to Python functions. it before returning. .. versionadded:: 3.12 + From 2e0b172a98aa852e5ef1212ed414aead27ebf450 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 20 Jun 2025 10:35:56 -0400 Subject: [PATCH 02/11] Mark PyFunction_GetKwDefaults as returning a borrowed reference. --- Doc/data/refcounts.dat | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index 99cc823c0c3772..4d09c2c6b9383a 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -972,6 +972,9 @@ PyFunction_GetCode:PyObject*:op:0: PyFunction_GetDefaults:PyObject*::0: PyFunction_GetDefaults:PyObject*:op:0: +PyFunction_GetKwDefaults:PyObject*::0: +PyFunction_GetKwDefaults:PyObject*:op:0: + PyFunction_GetGlobals:PyObject*::0: PyFunction_GetGlobals:PyObject*:op:0: From 0c254cff6fe8020bccdc20f7e28e1b8ce11b069e Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 20 Jun 2025 10:42:32 -0400 Subject: [PATCH 03/11] Add versionadded and fix description. --- Doc/c-api/function.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst index 44d69e2900b777..7588db44b1b428 100644 --- a/Doc/c-api/function.rst +++ b/Doc/c-api/function.rst @@ -118,14 +118,18 @@ There are a few functions specific to Python functions. .. c:function:: PyObject* PyFunction_GetKwDefaults(PyObject *op) - Return the keyword-argument default values of the function object *op*. This can be a - tuple of arguments or ``NULL``. + Return the keyword-only argument default values of the function object *op*. This can be a + dictionary of arguments or ``NULL``. + + .. versionadded:: 3.0 .. c:function:: PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op) Equivalent to :c:func:`PyFunction_GetKwDefaults`, but without error checking. + .. versionadded:: 3.0 + .. c:function:: PyObject* PyFunction_GetClosure(PyObject *op) From b0176a7bf720fde262080bdb63dfbad5f037fef3 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 20 Jun 2025 10:45:57 -0400 Subject: [PATCH 04/11] Add missing versionadded directive. --- Doc/c-api/function.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst index 7588db44b1b428..54d220484a708c 100644 --- a/Doc/c-api/function.rst +++ b/Doc/c-api/function.rst @@ -155,11 +155,15 @@ There are a few functions specific to Python functions. Return the annotations of the function object *op*. This can be a mutable dictionary or ``NULL``. + .. versionadded:: 3.0 + .. c:function:: PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op) Equivalent to :c:func:`PyFunction_GetAnnotations`, but without error checking. + .. versionadded:: 3.0 + .. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations) @@ -168,6 +172,8 @@ There are a few functions specific to Python functions. Raises :exc:`SystemError` and returns ``-1`` on failure. + .. versionadded:: 3.0 + .. c:function:: int PyFunction_AddWatcher(PyFunction_WatchCallback callback) From 6969427a8b5066c5191013e4aa7b6378e1199031 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 20 Jun 2025 10:47:17 -0400 Subject: [PATCH 05/11] Remove stray newline change. --- Doc/c-api/function.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst index 54d220484a708c..7f265700010fa3 100644 --- a/Doc/c-api/function.rst +++ b/Doc/c-api/function.rst @@ -245,4 +245,3 @@ There are a few functions specific to Python functions. it before returning. .. versionadded:: 3.12 - From 184e7e21d22fc5662e2c549a6ef71bab4ca44d7d Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 20 Jun 2025 11:02:17 -0400 Subject: [PATCH 06/11] Apply suggestions from code review Co-authored-by: Brian Schubert --- Doc/c-api/function.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst index 7f265700010fa3..bd27d604b8bd70 100644 --- a/Doc/c-api/function.rst +++ b/Doc/c-api/function.rst @@ -59,7 +59,7 @@ There are a few functions specific to Python functions. .. c:function:: PyObject *PyFunction_GET_CODE(PyObject *op) - Equivalent to :c:func:`PyFunction_GetCode`, but without error checking. + Similar to :c:func:`PyFunction_GetCode`, but without error checking. .. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op) @@ -69,7 +69,7 @@ There are a few functions specific to Python functions. .. c:function:: PyObject *PyFunction_GET_GLOBALS(PyObject *op) - Equivalent to :c:func:`PyFunction_GetGlobals`, but without error checking. + Similar to :c:func:`PyFunction_GetGlobals`, but without error checking. .. c:function:: PyObject* PyFunction_GetModule(PyObject *op) @@ -84,7 +84,7 @@ There are a few functions specific to Python functions. .. c:function:: PyObject *PyFunction_GET_MODULE(PyObject *op) - Equivalent to :c:func:`PyFunction_GetModule`, but without error checking. + Similar to :c:func:`PyFunction_GetModule`, but without error checking. .. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op) @@ -95,7 +95,7 @@ There are a few functions specific to Python functions. .. c:function:: PyObject *PyFunction_GET_DEFAULTS(PyObject *op) - Equivalent to :c:func:`PyFunction_GetDefaults`, but without error checking. + Similar to :c:func:`PyFunction_GetDefaults`, but without error checking. .. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults) @@ -126,7 +126,7 @@ There are a few functions specific to Python functions. .. c:function:: PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op) - Equivalent to :c:func:`PyFunction_GetKwDefaults`, but without error checking. + Similar to :c:func:`PyFunction_GetKwDefaults`, but without error checking. .. versionadded:: 3.0 @@ -139,7 +139,7 @@ There are a few functions specific to Python functions. .. c:function:: PyObject *PyFunction_GET_CLOSURE(PyObject *op) - Equivalent to :c:func:`PyFunction_GetClosure`, but without error checking. + Similar to :c:func:`PyFunction_GetClosure`, but without error checking. .. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure) @@ -160,7 +160,7 @@ There are a few functions specific to Python functions. .. c:function:: PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op) - Equivalent to :c:func:`PyFunction_GetAnnotations`, but without error checking. + Similar to :c:func:`PyFunction_GetAnnotations`, but without error checking. .. versionadded:: 3.0 From 6bd56af92b373c66c0dc68f5ee976a13be1e4de8 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 20 Jun 2025 12:03:14 -0400 Subject: [PATCH 07/11] Document the reference count effect of the macros. --- Doc/data/refcounts.dat | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index 4d09c2c6b9383a..144c5608e07426 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -963,24 +963,45 @@ PyFunction_Check:PyObject*:o:0: PyFunction_GetAnnotations:PyObject*::0: PyFunction_GetAnnotations:PyObject*:op:0: +PyFunction_GET_ANNOTATIONS:PyObject*::0: +PyFunction_GET_ANNOTATIONS:PyObject*:op:0: + PyFunction_GetClosure:PyObject*::0: PyFunction_GetClosure:PyObject*:op:0: +PyFunction_GET_CLOSURE:PyObject*::0: +PyFunction_GET_CLOSURE:PyObject*:op:0: + PyFunction_GetCode:PyObject*::0: PyFunction_GetCode:PyObject*:op:0: +PyFunction_GET_CODE:PyObject*::0: +PyFunction_GET_CODE:PyObject*:op:0: + PyFunction_GetDefaults:PyObject*::0: PyFunction_GetDefaults:PyObject*:op:0: +PyFunction_GET_DEFAULTS:PyObject*::0: +PyFunction_GET_DEFAULTS:PyObject*:op:0: + PyFunction_GetKwDefaults:PyObject*::0: PyFunction_GetKwDefaults:PyObject*:op:0: +PyFunction_GET_KW_DEFAULTS:PyObject*::0: +PyFunction_GET_KW_DEFAULTS:PyObject*:op:0: + PyFunction_GetGlobals:PyObject*::0: PyFunction_GetGlobals:PyObject*:op:0: +PyFunction_GET_GLOBALS:PyObject*::0: +PyFunction_GET_GLOBALS:PyObject*:op:0: + PyFunction_GetModule:PyObject*::0: PyFunction_GetModule:PyObject*:op:0: +PyFunction_GET_MODULE:PyObject*::0: +PyFunction_GET_MODULE:PyObject*:op:0: + PyFunction_New:PyObject*::+1: PyFunction_New:PyObject*:code:+1: PyFunction_New:PyObject*:globals:+1: From 5dd09739886b7659ae9b071c3e95b29e1dd52d36 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 23 Jun 2025 14:50:28 -0400 Subject: [PATCH 08/11] Flatten things down. --- Doc/c-api/function.rst | 54 ++++++++++-------------------------------- 1 file changed, 13 insertions(+), 41 deletions(-) diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst index bd27d604b8bd70..b609db037ccff2 100644 --- a/Doc/c-api/function.rst +++ b/Doc/c-api/function.rst @@ -57,21 +57,11 @@ There are a few functions specific to Python functions. Return the code object associated with the function object *op*. -.. c:function:: PyObject *PyFunction_GET_CODE(PyObject *op) - - Similar to :c:func:`PyFunction_GetCode`, but without error checking. - - .. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op) Return the globals dictionary associated with the function object *op*. -.. c:function:: PyObject *PyFunction_GET_GLOBALS(PyObject *op) - - Similar to :c:func:`PyFunction_GetGlobals`, but without error checking. - - .. c:function:: PyObject* PyFunction_GetModule(PyObject *op) Return a :term:`borrowed reference` to the :attr:`~function.__module__` @@ -82,22 +72,12 @@ There are a few functions specific to Python functions. but can be set to any other object by Python code. -.. c:function:: PyObject *PyFunction_GET_MODULE(PyObject *op) - - Similar to :c:func:`PyFunction_GetModule`, but without error checking. - - .. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op) Return the argument default values of the function object *op*. This can be a tuple of arguments or ``NULL``. -.. c:function:: PyObject *PyFunction_GET_DEFAULTS(PyObject *op) - - Similar to :c:func:`PyFunction_GetDefaults`, but without error checking. - - .. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults) Set the argument default values for the function object *op*. *defaults* must be @@ -121,15 +101,6 @@ There are a few functions specific to Python functions. Return the keyword-only argument default values of the function object *op*. This can be a dictionary of arguments or ``NULL``. - .. versionadded:: 3.0 - - -.. c:function:: PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op) - - Similar to :c:func:`PyFunction_GetKwDefaults`, but without error checking. - - .. versionadded:: 3.0 - .. c:function:: PyObject* PyFunction_GetClosure(PyObject *op) @@ -137,11 +108,6 @@ There are a few functions specific to Python functions. or a tuple of cell objects. -.. c:function:: PyObject *PyFunction_GET_CLOSURE(PyObject *op) - - Similar to :c:func:`PyFunction_GetClosure`, but without error checking. - - .. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure) Set the closure associated with the function object *op*. *closure* must be @@ -158,13 +124,6 @@ There are a few functions specific to Python functions. .. versionadded:: 3.0 -.. c:function:: PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op) - - Similar to :c:func:`PyFunction_GetAnnotations`, but without error checking. - - .. versionadded:: 3.0 - - .. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations) Set the annotations for the function object *op*. *annotations* @@ -175,6 +134,19 @@ There are a few functions specific to Python functions. .. versionadded:: 3.0 +.. c:function:: PyObject *PyFunction_GET_CODE(PyObject *op) + PyObject *PyFunction_GET_GLOBALS(PyObject *op) + PyObject *PyFunction_GET_MODULE(PyObject *op) + PyObject *PyFunction_GET_DEFAULTS(PyObject *op) + PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op) + PyObject *PyFunction_GET_CLOSURE(PyObject *op) + PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op) + + Similar to their ``PyFunction_Get*`` counterparts, but do not do type + checking. Passing anything other than an instance of + :c:type:`PyFunction_type` is undefined behavior. + + .. c:function:: int PyFunction_AddWatcher(PyFunction_WatchCallback callback) Register *callback* as a function watcher for the current interpreter. From dfaa6ff4751d31787134b4aa94c3e7694f4164fa Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 23 Jun 2025 16:35:36 -0400 Subject: [PATCH 09/11] Update function.rst Co-authored-by: Brian Schubert --- Doc/c-api/function.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst index b609db037ccff2..95ea1167439914 100644 --- a/Doc/c-api/function.rst +++ b/Doc/c-api/function.rst @@ -144,7 +144,7 @@ There are a few functions specific to Python functions. Similar to their ``PyFunction_Get*`` counterparts, but do not do type checking. Passing anything other than an instance of - :c:type:`PyFunction_type` is undefined behavior. + :c:data:`PyFunction_Type` is undefined behavior. .. c:function:: int PyFunction_AddWatcher(PyFunction_WatchCallback callback) From 9ce8dbce7d99f38d1f84fc0f467be782e5370c07 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 24 Jun 2025 05:38:58 -0400 Subject: [PATCH 10/11] Fix English. --- Doc/c-api/function.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst index 95ea1167439914..103e59ac6d1cb9 100644 --- a/Doc/c-api/function.rst +++ b/Doc/c-api/function.rst @@ -142,8 +142,8 @@ There are a few functions specific to Python functions. PyObject *PyFunction_GET_CLOSURE(PyObject *op) PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op) - Similar to their ``PyFunction_Get*`` counterparts, but do not do type - checking. Passing anything other than an instance of + These functions are similar to their ``PyFunction_Get*`` counterparts, but + do not do type checking. Passing anything other than an instance of :c:data:`PyFunction_Type` is undefined behavior. From bb685cdb3fc2a0f599acc1a16bf84e205a3377e4 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 25 Jun 2025 10:38:56 +0200 Subject: [PATCH 11/11] Remove more versionadded:: 3.0 --- Doc/c-api/function.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst index 103e59ac6d1cb9..5fb8567ef8c95f 100644 --- a/Doc/c-api/function.rst +++ b/Doc/c-api/function.rst @@ -121,8 +121,6 @@ There are a few functions specific to Python functions. Return the annotations of the function object *op*. This can be a mutable dictionary or ``NULL``. - .. versionadded:: 3.0 - .. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations) @@ -131,8 +129,6 @@ There are a few functions specific to Python functions. Raises :exc:`SystemError` and returns ``-1`` on failure. - .. versionadded:: 3.0 - .. c:function:: PyObject *PyFunction_GET_CODE(PyObject *op) PyObject *PyFunction_GET_GLOBALS(PyObject *op)