classification
Title: Exceptions tutorial page does not mention raise from
Type: enhancement Stage:
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7, Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Niels Albers, docs@python, rhettinger, shireenrao
Priority: normal Keywords:

Created on 2019-08-20 07:21 by Niels Albers, last changed 2019-09-05 06:15 by Niels Albers.

Messages (6)
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."
History
Date User Action Args
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