This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Exceptions tutorial page does not mention raise from
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.10
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Bonifacio2, Niels Albers, docs@python, rhettinger, shireenrao
Priority: normal Keywords: easy

Created on 2019-08-20 07:21 by Niels Albers, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Messages (8)
msg349994 - (view) Author: Niels Albers (Niels Albers) Date: 2019-08-20 07:21
raise <Exception> from <exception instance> has been in the language since python 3, yet the tutorial page teaching about exceptions does not mention it. (see https://docs.python.org/3.7/tutorial/errors.html#raising-exceptions)
It would be especially helpful to language newcomers to touch on the possibility of passing error context when raising a new exception in an exception handler.
msg350010 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-20 15:08
Thanks for spotting this omission.  Would you like to submit a PR with a short paragraph on exception chaining and "raise from"?
msg350036 - (view) Author: Srinivas Nyayapati (shireenrao) * Date: 2019-08-20 18:52
In case Niels Albers is not interested, can I submit a PR?
I noticed the linked raise reference documentation from the tutorial having details on exception chaining (https://docs.python.org/3.7/reference/simple_stmts.html#raise). Does it make sense to mention exception chaining in the tutorial and say "read details in the reference docs"? Or as you mentioned.. just write a short paragraph on exception chaining and give an example in the tutorial?
msg350037 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-20 19:21
Please give Niel a chance to submit wording, even a post here on the tracker will be fine.  We usually defer to the person who actually encountered the issue.  

If after a week or so, there is no response, you can pick this up.  Try to be minimal with it and avoid the temptation to go gonzo.  The "from" part of exception semantics is one of its most minor and easily ignored features.  Accordingly, it should get minimal space in the tutorial and probably doesn't even warrant an example if a simple, clear sentence will suffice.
msg351126 - (view) Author: Srinivas Nyayapati (shireenrao) * Date: 2019-09-04 13:14
Here is my first pass at this. I propose the following sentence be added at the end section 8.4:

If you need to track related exceptions (exceptions during exception handling), you should use exception chaining. You can chain exceptions by using the ``from`` clause. Just raise a new exception class or instance from an existing exception. The existing exception will be set as 
the cause for the new exception.
msg351179 - (view) Author: Niels Albers (Niels Albers) Date: 2019-09-05 06:15
Thanks Srinivas for the suggestion. IMO exception chaining has more utility than only dealing with new exceptions that are caused by exception handling. It's all about preserving exception context. As both a writer of libraries and a user of such, I do like to have a full context chain when I have to handle an exception (or more importantly as a devops engineeer: log it)

Is this edit acceptable?

"If you need to track exception context, you can use exception chaining. You can chain exceptions by using the ``from`` clause. Just raise a new exception class or instance from an existing exception. The existing exception will be set as 
the cause for the new exception."
msg393659 - (view) Author: Bonifacio (Bonifacio2) * Date: 2021-05-14 12:59
Version 3.9 of the docs already cover the syntax Neils talks about in his original message. https://docs.python.org/3.9/tutorial/errors.html#exception-chaining
Is there anything left to be done here? If so, I'm glad to help with them, but I would need directions.
msg393677 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-05-14 17:02
Thanks for looking. This issue does appear to be out of date.
History
Date User Action Args
2022-04-11 14:59:19adminsetgithub: 82072
2021-05-14 17:02:23rhettingersetstatus: open -> closed
resolution: out of date
messages: + msg393677

stage: resolved
2021-05-14 12:59:36Bonifacio2setnosy: + Bonifacio2
messages: + msg393659
2021-03-21 19:53:55iritkatrielsetkeywords: + easy
versions: + Python 3.10, - Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9
2019-09-05 06:15:34Niels Alberssetmessages: + msg351179
2019-09-04 13:14:06shireenraosetmessages: + msg351126
2019-08-20 19:21:32rhettingersetmessages: + msg350037
2019-08-20 18:52:16shireenraosetnosy: + shireenrao
messages: + msg350036
2019-08-20 15:08:41rhettingersetnosy: + rhettinger
messages: + msg350010
2019-08-20 07:22:12Niels Alberssettype: enhancement
2019-08-20 07:21:07Niels Alberscreate