diff options
| -rw-r--r-- | Doc/tutorial/errors.rst | 47 |
1 files changed, 47 insertions, 0 deletions
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 |