From fd0dde1e0c599e1e4bde0ee2a02ca806745449e0 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 16 Feb 2023 22:28:46 +0100 Subject: [PATCH 1/6] gh-101578: Amend PyErr_{Set,Get}RaisedException docs --- Doc/c-api/exceptions.rst | 49 ++++++++++++++++------------------------ Doc/data/refcounts.dat | 3 +++ 2 files changed, 22 insertions(+), 30 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index de9b15edd6859a..f1bd7c13d8524e 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -402,51 +402,40 @@ Querying the error indicator .. c:function:: PyObject *PyErr_GetRaisedException(void) - Returns the exception currently being raised, clearing the exception at - the same time. Do not confuse this with the exception currently being - handled which can be accessed with :c:func:`PyErr_GetHandledException`. + Return the exception currently being raised, clearing the error indicator at + the same time. - .. note:: + This function is used by code that needs to catch exceptions, + or code that needs to save and restore the error indicator temporarily. - This function is normally only used by code that needs to catch exceptions or - by code that needs to save and restore the error indicator temporarily, e.g.:: + Example:: - { - PyObject *exc = PyErr_GetRaisedException(); + { + PyObject *exc = PyErr_GetRaisedException(); - /* ... code that might produce other errors ... */ + /* ... code that might produce other errors ... */ - PyErr_SetRaisedException(exc); - } + PyErr_SetRaisedException(exc); + } + + Use :c:func:`PyErr_GetHandledException` to fetch the exception + currently being handled. + + .. seealso:: :c:func:`PyErr_SetRaisedException` .. versionadded:: 3.12 .. c:function:: void PyErr_SetRaisedException(PyObject *exc) - Sets the exception currently being raised ``exc``. - If the exception is already set, it is cleared first. - - ``exc`` must be a valid exception. - (Violating this rules will cause subtle problems later.) - This call consumes a reference to the ``exc`` object: you must own a - reference to that object before the call and after the call you no longer own - that reference. - (If you don't understand this, don't use this function. I warned you.) + Set *exc* as the exception currently being raised. + If another exception is already raised, it is cleared first. .. note:: - This function is normally only used by code that needs to save and restore the - error indicator temporarily. Use :c:func:`PyErr_GetRaisedException` to save - the current exception, e.g.:: - - { - PyObject *exc = PyErr_GetRaisedException(); + This call steals a reference to *exc*, which must be a valid exception. - /* ... code that might produce other errors ... */ - - PyErr_SetRaisedException(exc); - } + .. seealso:: :c:func:`PyErr_GetRaisedException` .. versionadded:: 3.12 diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index 349c4dd5be3d81..ed2958f8cd2205 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -606,6 +606,9 @@ PyErr_GetExcInfo:PyObject**:ptype:+1: PyErr_GetExcInfo:PyObject**:pvalue:+1: PyErr_GetExcInfo:PyObject**:ptraceback:+1: +PyErr_GetRaisedException:PyObject*::+1: +PyErr_SetRaisedException:::: + PyErr_GivenExceptionMatches:int::: PyErr_GivenExceptionMatches:PyObject*:given:0: PyErr_GivenExceptionMatches:PyObject*:exc:0: From 415a70d044e997e88abe3727cc4f030c87e49564 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 17 Feb 2023 09:31:46 +0100 Subject: [PATCH 2/6] Address CAM's first round of review --- Doc/c-api/exceptions.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index f1bd7c13d8524e..1335b5c3d58670 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -408,7 +408,7 @@ Querying the error indicator This function is used by code that needs to catch exceptions, or code that needs to save and restore the error indicator temporarily. - Example:: + For example:: { PyObject *exc = PyErr_GetRaisedException(); @@ -418,10 +418,13 @@ Querying the error indicator PyErr_SetRaisedException(exc); } - Use :c:func:`PyErr_GetHandledException` to fetch the exception - currently being handled. + .. seealso:: - .. seealso:: :c:func:`PyErr_SetRaisedException` + * :c:func:`PyErr_SetRaisedException`, + to set the current raised exception. + + * :c:func:`PyErr_GetHandledException`, + to fetch the exception currently being handled. .. versionadded:: 3.12 @@ -431,11 +434,12 @@ Querying the error indicator Set *exc* as the exception currently being raised. If another exception is already raised, it is cleared first. - .. note:: + .. caution:: This call steals a reference to *exc*, which must be a valid exception. - .. seealso:: :c:func:`PyErr_GetRaisedException` + .. seealso:: :c:func:`PyErr_GetRaisedException`, + to save the current raised exception. .. versionadded:: 3.12 From 45ecfe57d7909f8d3e059c2d21e83eafd366b0a0 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 17 Feb 2023 11:12:42 +0100 Subject: [PATCH 3/6] Address CAM's second round of review --- Doc/c-api/exceptions.rst | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 1335b5c3d58670..3c39d8b46a01ff 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -418,14 +418,6 @@ Querying the error indicator PyErr_SetRaisedException(exc); } - .. seealso:: - - * :c:func:`PyErr_SetRaisedException`, - to set the current raised exception. - - * :c:func:`PyErr_GetHandledException`, - to fetch the exception currently being handled. - .. versionadded:: 3.12 @@ -434,7 +426,7 @@ Querying the error indicator Set *exc* as the exception currently being raised. If another exception is already raised, it is cleared first. - .. caution:: + .. warning:: This call steals a reference to *exc*, which must be a valid exception. From 02334f4efbe02aaf373ce0dffb3904b62040cfba Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 17 Feb 2023 11:26:31 +0100 Subject: [PATCH 4/6] Move seealso to get API --- Doc/c-api/exceptions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 3c39d8b46a01ff..14e5addd52d616 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -418,6 +418,9 @@ Querying the error indicator PyErr_SetRaisedException(exc); } + .. seealso:: :c:func:`PyErr_GetRaisedException`, + to save the current raised exception. + .. versionadded:: 3.12 @@ -430,9 +433,6 @@ Querying the error indicator This call steals a reference to *exc*, which must be a valid exception. - .. seealso:: :c:func:`PyErr_GetRaisedException`, - to save the current raised exception. - .. versionadded:: 3.12 From 3cf91f80c839bd174ee7036d05c6f53590db5984 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 17 Feb 2023 11:29:33 +0100 Subject: [PATCH 5/6] Fixup seealo, hopefully for real this time --- Doc/c-api/exceptions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 14e5addd52d616..668c3aa602cbba 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -418,8 +418,8 @@ Querying the error indicator PyErr_SetRaisedException(exc); } - .. seealso:: :c:func:`PyErr_GetRaisedException`, - to save the current raised exception. + .. seealso:: :c:func:`PyErr_GetHandledException`, + to save the exception currently being handled. .. versionadded:: 3.12 From fd94dd8d4fa4b5cc142553e2a122146585a2863a Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sun, 19 Feb 2023 20:49:37 +0100 Subject: [PATCH 6/6] Update Doc/c-api/exceptions.rst Co-authored-by: C.A.M. Gerlach --- Doc/c-api/exceptions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 668c3aa602cbba..e735f8db402363 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -426,8 +426,8 @@ Querying the error indicator .. c:function:: void PyErr_SetRaisedException(PyObject *exc) - Set *exc* as the exception currently being raised. - If another exception is already raised, it is cleared first. + Set *exc* as the exception currently being raised, + clearing the existing exception if one is set. .. warning::