[3.10] gh-97654: Add auto exception chaining example to tutorial (GH-97703) (#97884)

Add auto exception chaining example to tutorial
(cherry picked from commit 395b66a0ae5237eec195ca97daaaf8563706ed34)

Co-authored-by: Shahriar Heidrich <smheidrich@weltenfunktion.de>

diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst
index 3f09db21040680cc2a3ffc88cc181e5a6f1d9a10..ecfb6128839060b7e041057be11278dd666fe1ab 100644 (file)
--- a/Doc/tutorial/errors.rst
+++ b/Doc/tutorial/errors.rst
@@ -275,8 +275,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
@@ -302,9 +321,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')