From 9240c4459f5d05307a48486a5f8c850c96ed1967 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 20 Jun 2025 10:35:17 -0400 Subject: [PATCH 1/7] 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 2/7] 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 3/7] 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 4/7] 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 5/7] 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 6/7] 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 7/7] 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: