Merge branch 'master' into bugfix/bpo-42179

python · willingc · Dec 16, 2020 · Nov 5, 2020 · Nov 5, 2020 · Nov 5, 2020
commit bb29890a5c8814cbb2e94cb3b10e26d863ff4a8a
diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst
@@ -281,33 +281,27 @@ chaining exceptions. For example::
 This can be useful when you are transforming exceptions. For example::
 
     >>> def func():
-    ...     raise IOError
+    ...     raise ConnectionError
     ...
     >>> try:
     ...     func()
-    ... except IOError as exc:
+    ... except ConnectionError as exc:
     ...     raise RuntimeError('Failed to open database') from exc
     ...
     Traceback (most recent call last):
       File "<stdin>", line 2, in <module>
       File "<stdin>", line 2, in func
-    OSError
+    ConnectionError
     <BLANKLINE>
     The above exception was the direct cause of the following exception:
     <BLANKLINE>
     Traceback (most recent call last):
       File "<stdin>", line 4, in <module>
     RuntimeError: Failed to open database
 
-The expression following the :keyword:`from` must be either an exception or
-``None``. Exception chaining happens automatically when an exception is raised
-inside an exception handler or :keyword:`finally` section, however in this case
-``__context__`` attribute of the exception is used. Chaining with
-``__context__`` works similarly to chaining with ``__cause__``,
-but when formatting exception traceback ``__cause__`` takes priority.
-For more information about chaining mechanics see :ref:`bltin-exceptions`.
-
-Exception chaining can be disabled by using ``from None`` idiom:
+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:
 
     >>> try:
     ...     open('database.sqlite')
@@ -318,6 +312,13 @@ Exception chaining can be disabled by using ``from None`` idiom:
       File "<stdin>", line 4, in <module>
     RuntimeError
 
+There are two special attributes that enable chaining mechanics in
+exceptions: ``__context__`` and ``__cause__``. When you raise an exception
+inside :keyword:`except` or :keyword:`finally`, Pyhton automatically fills
+``__context__`` attribute of the new exception with the caught one. When you
+use ``from exc`` syntax, Pyhon fills ``__cause__`` attribute with
+the ``exc``. You can use both attributes for introspection purposes, however
+when formatting exception traceback message, ``__cause__`` takes priority.
 For more information about chaining mechanics, see :ref:`bltin-exceptions`.