From dcfe111eb5602333135b8776996332a8dcf59392 Mon Sep 17 00:00:00 2001
From: Abhilash Raj <maxking@users.noreply.github.com>
Date: Wed, 14 Aug 2019 14:11:32 -0700
Subject: bpo-37826: Document exception chaining in Python tutorial for errors.
 (GH-15243)

https://bugs.python.org/issue37826
---
 Doc/tutorial/errors.rst | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst
index 4e287bb..e9a63e4 100644
--- a/Doc/tutorial/errors.rst
+++ b/Doc/tutorial/errors.rst
@@ -267,6 +267,53 @@ re-raise the exception::
    NameError: HiThere
 
 
+.. _tut-exception-chaining:
+
+Exception Chaining
+==================
+
+The :keyword:`raise` statement allows an optional :keyword:`from` which enables
+chaining exceptions by setting the ``__cause__`` attribute of the raised
+exception. For example::
+
+    raise RuntimeError from OSError
+
+This can be useful when you are transforming exceptions. For example::
+
+    >>> def func():
+    ...    raise IOError
+    ...
+    >>> try:
+    ...     func()
+    ... except IOError 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
+    <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
+
+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. Exception chaining
+can be disabled by using ``from None`` idiom:
+
+    >>> try:
+    ...     open('database.sqlite')
+    ... except IOError:
+    ...     raise RuntimeError from None
+    ...
+    Traceback (most recent call last):
+      File "<stdin>", line 4, in <module>
+    RuntimeError
+
+
 .. _tut-userexceptions:
 
 User-defined Exceptions
-- 
cgit v0.12