From 08f3d81bc04a0e4a5358c67414dd13c4b25b148f Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Mon, 21 Jun 2021 17:52:17 -0400 Subject: [PATCH 1/3] bpo-25381: Update explanation of exception globals This paragraph in extending/extending.rst was unchanged (except for NULL markup) since committed in 2007 Aug 15 for 2.6 alpha. --- Doc/extending/extending.rst | 8 ++++---- .../2021-06-21-17-51-51.bpo-25381.7Kn-_H.rst | 2 ++ 2 files changed, 6 insertions(+), 4 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2021-06-21-17-51-51.bpo-25381.7Kn-_H.rst diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 561d1c616cc10e..b566722cc86b34 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -127,10 +127,10 @@ Intermezzo: Errors and Exceptions An important convention throughout the Python interpreter is the following: when a function fails, it should set an exception condition and return an error value -(usually a ``NULL`` pointer). Exceptions are stored in a static global variable -inside the interpreter; if this variable is ``NULL`` no exception has occurred. A -second global variable stores the "associated value" of the exception (the -second argument to :keyword:`raise`). A third variable contains the stack +(usually a ``NULL`` pointer). Exception information is stored in 3 static +global variables inside the interpreter. The first is the exception type, +or ``NULL`` if no exception has occurred. The second is the exception +instance. The third variable contains the stack traceback in case the error originated in Python code. These three variables are the C equivalents of the result in Python of :meth:`sys.exc_info` (see the section on module :mod:`sys` in the Python Library Reference). It is important diff --git a/Misc/NEWS.d/next/Documentation/2021-06-21-17-51-51.bpo-25381.7Kn-_H.rst b/Misc/NEWS.d/next/Documentation/2021-06-21-17-51-51.bpo-25381.7Kn-_H.rst new file mode 100644 index 00000000000000..f009f880e917d5 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2021-06-21-17-51-51.bpo-25381.7Kn-_H.rst @@ -0,0 +1,2 @@ +In the extending chapter of the extending doc, update a paragraph about the +global variables containing exception information. From 5fffb6895d0a1a7ff6a12c0b9ecc08eaa1fec083 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Mon, 21 Jun 2021 20:05:30 -0400 Subject: [PATCH 2/3] Respond to reviews and remove duplication. --- Doc/extending/extending.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index b566722cc86b34..2815d848039952 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -127,13 +127,11 @@ Intermezzo: Errors and Exceptions An important convention throughout the Python interpreter is the following: when a function fails, it should set an exception condition and return an error value -(usually a ``NULL`` pointer). Exception information is stored in 3 static -global variables inside the interpreter. The first is the exception type, -or ``NULL`` if no exception has occurred. The second is the exception -instance. The third variable contains the stack -traceback in case the error originated in Python code. These three variables -are the C equivalents of the result in Python of :meth:`sys.exc_info` (see the -section on module :mod:`sys` in the Python Library Reference). It is important +(usually -1 or a ``NULL`` pointer). Exception information is stored in +three members of the interpreter's thread state. These are ``NULL`` if +there is no exception. Otherwise they are the C equivalents of the members +of the Python tuple returned by :meth:`sys.exc_info`. These are the +exception type, exception instance, and a traceback object. It is important to know about them to understand how errors are passed around. The Python API defines a number of functions to set various types of exceptions. From f77dd4585a8a076915d242bfd7b71f1fac78775b Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Mon, 21 Jun 2021 20:41:02 -0400 Subject: [PATCH 3/3] Update Doc/extending/extending.rst Co-authored-by: Serhiy Storchaka --- Doc/extending/extending.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 2815d848039952..2e3362b834e6fb 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -127,7 +127,7 @@ Intermezzo: Errors and Exceptions An important convention throughout the Python interpreter is the following: when a function fails, it should set an exception condition and return an error value -(usually -1 or a ``NULL`` pointer). Exception information is stored in +(usually ``-1`` or a ``NULL`` pointer). Exception information is stored in three members of the interpreter's thread state. These are ``NULL`` if there is no exception. Otherwise they are the C equivalents of the members of the Python tuple returned by :meth:`sys.exc_info`. These are the