classification
Title: Document 'from None' in raise statement doc.
Type: enhancement Stage: backport needed
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: Arfrever, Mariatta, benjamin.peterson, berker.peksag, csabella, docs@python, ezio.melotti, me@dennis.is, ncoghlan, nitika, rbcollins, terry.reedy, thomir
Priority: normal Keywords: easy, patch

Created on 2013-02-12 01:19 by terry.reedy, last changed 2017-05-20 06:51 by terry.reedy.

Files
File name Uploaded Description Edit
patch17188.patch me@dennis.is, 2013-02-23 19:24 review
issue17188.patch nitika, 2014-03-15 18:27
issue17188_1.patch nitika, 2014-03-19 19:09
issue17188_3.4.patch thomir, 2016-09-12 23:03
issue17188_3.4.patch thomir, 2016-09-13 04:49
issue17188_by_thomir.patch Mariatta, 2016-10-05 07:11 review
Pull Requests
URL Status Linked Edit
PR 1671 merged csabella, 2017-05-20 00:16
PR 1671 merged csabella, 2017-05-20 00:16
Messages (14)
msg181939 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-02-12 01:19
Language manual, section 7.8. The raise statement has no mention of the 'from None' option. Indeed it says "if given, the second expression must be another exception class or instance", which would exclude None.

Library manual, Ch 5. Built-in Exceptions, says
'''
When raising a new exception (rather than using a bare raise to re-raise the exception currently being handled), the implicit exception context can be supplemented with an explicit cause by using from with raise:

raise new_exc from original_exc

The expression following from must be an exception or None. It will be set as __cause__ on the raised exception. Setting __cause__ also implicitly sets the __suppress_context__ attribute to True, so that using raise new_exc from None effectively replaces the old exception with the new one for display purposes (e.g. converting KeyError to AttributeError, while leaving the old exception available in __context__ for introspection when debugging.
'''
I am not sure how much should be copied over, but None should be at least mentioned and perhaps there should be a cross-reference.

I am also not sure how much applies to 3.2, but there is no version-added or -changed note with the above.
msg182213 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-02-16 05:38
As Terry notes, the various pieces of "from None" documentation should also have a nearby directive like:

.. versionchanged: 3.3

   :const:`None` permitted as ``Y`` in ``raise X from Y`` 

.. versionadded: 3.3

   The ``__suppress_context__`` attribute to suppress automatic display of the exception context
msg182799 - (view) Author: Dennis MÃ¥rtensson (me@dennis.is) * Date: 2013-02-23 19:24
We have added the from None to the documentation with a explanation and some example code.
msg182815 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2013-02-23 20:25
The patch should add something to the "The from clause is used for exception..." paragraph, to state that None is also allowed.

It also adds things in a confusing order. I think the new example should go below other examples, and the changedversion and addedversion directives should be the last thing in the section.
msg213640 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-03-15 05:31
Hi,
As suggested by Petri,I have made some changes.
Please review the attached patch.Any comments and feedback are welcome.
msg214126 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-03-19 19:09
Patch with some corrections.
Please review the patch attached.
msg214178 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2014-03-20 07:10
The patch doesn't apply cleanly on 3.4 or default.
msg276132 - (view) Author: Thomi Richards (thomir) * Date: 2016-09-12 23:03
I have attached a patch for 3.4, based on the patch submitted by Nitika Agarwal. The main difference is that I think it's better to be explicit and show a separate example of `raise X from None`.

I will submit a patch for later versions as well.
msg276133 - (view) Author: Thomi Richards (thomir) * Date: 2016-09-12 23:07
OK, it seems that patch applies cleanly to 3.5 and 3.6.
msg276170 - (view) Author: Thomi Richards (thomir) * Date: 2016-09-13 04:49
Re-uploaded the patch without the typo.
msg278110 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2016-10-05 07:11
reuploaded thomir's patch issue17188_3.4.patch as is.
I take no credit for this.
msg293454 - (view) Author: Cheryl Sabella (csabella) * Date: 2017-05-10 21:21
Would any of the original authors be able to prepare a PR for this?  Thanks.
msg294011 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-05-20 06:48
New changeset 763557eac06ba60d7c5133e4f80df8870d8f917e by terryjreedy (csabella) in branch 'master':
bpo-17188: DOC: Document 'from None' in raise statement (#1671)
https://github.com/python/cpython/commit/763557eac06ba60d7c5133e4f80df8870d8f917e
msg294013 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-05-20 06:51
The double listing seems to be a glitch.

Either someone else does backport or online doc change waits until I can do it.
History
Date User Action Args
2017-05-20 06:51:30terry.reedysetassignee: docs@python -> terry.reedy
stage: patch review -> backport needed
messages: + msg294013
versions: + Python 3.6, Python 3.7, - Python 3.4, Python 3.5
2017-05-20 06:48:30terry.reedysetmessages: + msg294011
2017-05-20 00:16:45csabellasetpull_requests: + pull_request1766
2017-05-20 00:16:41csabellasetpull_requests: + pull_request1765
2017-05-10 21:21:24csabellasetnosy: + csabella
messages: + msg293454
2016-10-05 07:11:58Mariattasetfiles: + issue17188_by_thomir.patch

messages: + msg278110
2016-10-04 19:58:20Mariattasetnosy: + Mariatta
2016-09-22 10:26:02rbcollinssetnosy: + rbcollins
2016-09-13 07:11:39petri.lehtinensetnosy: - petri.lehtinen
2016-09-13 04:49:42thomirsetfiles: + issue17188_3.4.patch

messages: + msg276170
2016-09-12 23:07:19thomirsetmessages: + msg276133
2016-09-12 23:03:35thomirsetfiles: + issue17188_3.4.patch
nosy: + thomir
messages: + msg276132

2015-01-31 00:57:01berker.peksagsetnosy: + berker.peksag
stage: needs patch -> patch review

versions: + Python 3.5, - Python 3.3
2014-03-20 18:44:32Arfreversetnosy: + Arfrever
2014-03-20 07:10:41petri.lehtinensetmessages: + msg214178
2014-03-19 19:09:33nitikasetfiles: + issue17188_1.patch

messages: + msg214126
2014-03-15 18:27:07nitikasetfiles: + issue17188.patch
2014-03-15 18:25:05nitikasetfiles: - issue17188.patch
2014-03-15 06:41:41nitikasetfiles: + issue17188.patch
2014-03-15 06:38:07nitikasetfiles: - issue17188.patch
2014-03-15 05:31:54nitikasetfiles: + issue17188.patch
nosy: + nitika
messages: + msg213640

2013-12-20 23:33:54terry.reedylinkissue20003 superseder
2013-02-23 20:25:23petri.lehtinensetnosy: + petri.lehtinen

messages: + msg182815
versions: - Python 3.2
2013-02-23 19:24:27me@dennis.issetfiles: + patch17188.patch

nosy: + me@dennis.is
messages: + msg182799

keywords: + patch
2013-02-16 05:38:43ncoghlansetmessages: + msg182213
2013-02-15 21:10:13ezio.melottisetkeywords: + easy
nosy: + benjamin.peterson, ezio.melotti
type: enhancement
2013-02-12 01:19:59terry.reedycreate