[Python-checkins] bpo-41576: document BaseException in favor of bare except (GH-21917)

[miss-islington]

https://github.com/python/cpython/commit/699ee016af5736ffc80f68359617611a22b72943
commit: 699ee016af5736ffc80f68359617611a22b72943
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2021-08-06T14:14:40-07:00
summary:

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

(cherry picked from commit e9a6f1b78bf57d9f3f99547bd007d7cfc9724cfb)

Co-authored-by: Thomas Grainger <tagrain at gmail.com>

files:
A Misc/NEWS.d/next/Documentation/2020-08-21-22-59-37.bpo-41576.7a6CQR.rst
M Doc/tutorial/errors.rst

diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst
index 27e39dfe257716..e7a45a302c65a7 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 00000000000000..f74ef62ca47ab2
--- /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