[Python-checkins] gh-97654: Add auto exception chaining example to tutorial (#97703)

[JelleZijlstra]

https://github.com/python/cpython/commit/395b66a0ae5237eec195ca97daaaf8563706ed34
commit: 395b66a0ae5237eec195ca97daaaf8563706ed34
branch: main
author: Shahriar Heidrich <smheidrich at weltenfunktion.de>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2022-10-04T17:36:04-07:00
summary:

gh-97654: Add auto exception chaining example to tutorial (#97703)

Add auto exception chaining example to tutorial

files:
M Doc/tutorial/errors.rst

diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst
index 57919e3bad13..67bb19556681 100644
--- a/Doc/tutorial/errors.rst
+++ b/Doc/tutorial/errors.rst
@@ -284,8 +284,27 @@ re-raise the exception::
 Exception Chaining
 ==================
 
-The :keyword:`raise` statement allows an optional :keyword:`from<raise>` which enables
-chaining exceptions. For example::
+If an unhandled exception occurs inside an :keyword:`except` section, it will
+have the exception being handled attached to it and included in the error
+message::
+
+    >>> try:
+    ...     open("database.sqlite")
+    ... except OSError:
+    ...     raise RuntimeError("unable to handle error")
+    ...
+    Traceback (most recent call last):
+      File "<stdin>", line 2, in <module>
+    FileNotFoundError: [Errno 2] No such file or directory: 'database.sqlite'
+    <BLANKLINE>
+    During handling of the above exception, another exception occurred:
+    <BLANKLINE>
+    Traceback (most recent call last):
+      File "<stdin>", line 4, in <module>
+    RuntimeError: unable to handle error
+
+To indicate that an exception is a direct consequence of another, the
+:keyword:`raise` statement allows an optional :keyword:`from<raise>` clause::
 
     # exc must be exception instance or None.
     raise RuntimeError from exc
@@ -311,9 +330,8 @@ This can be useful when you are transforming exceptions. For example::
       File "<stdin>", line 4, in <module>
     RuntimeError: Failed to open database
 
-Exception chaining happens automatically when an exception is raised inside an
-:keyword:`except` or :keyword:`finally` section. This can be
-disabled by using ``from None`` idiom:
+It also allows disabling automatic exception chaining using the ``from None``
+idiom::
 
     >>> try:
     ...     open('database.sqlite')