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

Add auto exception chaining example to tutorial

1 files changed, 23 insertions, 5 deletions

diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst
index 57919e3bad..67bb195566 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')