From: Thomas Grainger <tagrain@gmail.com>
Date: Fri, 6 Aug 2021 20:44:15 +0000 (+0100)
Subject: bpo-41576: document BaseException in favor of bare except (GH-21917)
X-Git-Tag: v3.11.0a1~453
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e9a6f1b78bf57d9f3f99547bd007d7cfc9724cfb;p=thirdparty%2FPython%2Fcpython.git

bpo-41576: document BaseException in favor of bare except (GH-21917)
---

diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst
index 27e39dfe2577..e7a45a302c65 100644
--- a/Doc/tutorial/errors.rst
+++ b/Doc/tutorial/errors.rst
@@ -147,10 +147,10 @@ For example, the following code will print B, C, D in that order::
 Note that if the *except clauses* were reversed (with ``except B`` first), it
 would have printed B, B, B --- the first matching *except clause* is triggered.
 
-The last *except clause* may omit the exception name(s), to serve as a wildcard.
-Use this with extreme caution, since it is easy to mask a real programming error
-in this way!  It can also be used to print an error message and then re-raise
-the exception (allowing a caller to handle the exception as well)::
+All exceptions inherit from :exc:`BaseException`, and so it can be used to serve
+as a wildcard. Use this with extreme caution, since it is easy to mask a real
+programming error in this way!  It can also be used to print an error message and
+then re-raise the exception (allowing a caller to handle the exception as well)::
 
    import sys
 
@@ -162,10 +162,13 @@ the exception (allowing a caller to handle the exception as well)::
        print("OS error: {0}".format(err))
    except ValueError:
        print("Could not convert data to an integer.")
-   except:
-       print("Unexpected error:", sys.exc_info()[0])
+   except BaseException as err:
+       print(f"Unexpected {err=}, {type(err)=}")
        raise
 
+Alternatively the last except clause may omit the exception name(s), however the exception
+value must then be retrieved from ``sys.exc_info()[1]``.
+
 The :keyword:`try` ... :keyword:`except` statement has an optional *else
 clause*, which, when present, must follow all *except clauses*.  It is useful
 for code that must be executed if the *try clause* does not raise an exception.
@@ -493,5 +496,3 @@ used in a way that ensures they are always cleaned up promptly and correctly. ::
 After the statement is executed, the file *f* is always closed, even if a
 problem was encountered while processing the lines. Objects which, like files,
 provide predefined clean-up actions will indicate this in their documentation.
-
-
diff --git a/Misc/NEWS.d/next/Documentation/2020-08-21-22-59-37.bpo-41576.7a6CQR.rst b/Misc/NEWS.d/next/Documentation/2020-08-21-22-59-37.bpo-41576.7a6CQR.rst
new file mode 100644
index 000000000000..f74ef62ca47a
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2020-08-21-22-59-37.bpo-41576.7a6CQR.rst
@@ -0,0 +1 @@
+document BaseException in favor of bare except
\ No newline at end of file