Document 'from None' in raise statement doc.

[terryjreedy]

BPO	17188
Nosy	@terryjreedy, @ncoghlan, @rbtcollins, @benjaminp, @ezio-melotti, @berkerpeksag, @serhiy-storchaka, @Mariatta, @csabella
PRs	bpo-17188: DOC: Document 'from None' in raise statement #1671 bpo-17188: DOC: Document 'from None' in raise statement #1671 [3.6] bpo-17188: DOC: Document 'from None' in raise statement (GH-1671) #1867 bpo-17188: add missing periods at the end of sentences #1875 [3.6] bpo-17188: add missing periods at the end of sentences (GH-1875) #1876
Files	patch17188.patch issue17188.patch issue17188_1.patch issue17188_3.4.patch issue17188_3.4.patch issue17188_by_thomir.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/terryjreedy'
closed_at = <Date 2017-05-30.20:31:02.679>
created_at = <Date 2013-02-12.01:19:59.419>
labels = ['easy', 'type-feature', '3.7', 'docs']
title = "Document 'from None' in raise statement doc."
updated_at = <Date 2017-05-30.22:38:56.033>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2017-05-30.22:38:56.033>
actor = 'Mariatta'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2017-05-30.20:31:02.679>
closer = 'Mariatta'
components = ['Documentation']
creation = <Date 2013-02-12.01:19:59.419>
creator = 'terry.reedy'
dependencies = []
files = ['29199', '34434', '34527', '44607', '44618', '44967']
hgrepos = []
issue_num = 17188
keywords = ['patch', 'easy']
message_count = 20.0
messages = ['181939', '182213', '182799', '182815', '213640', '214126', '214178', '276132', '276133', '276170', '278110', '293454', '294011', '294013', '294780', '294781', '294786', '294792', '294795', '294796']
nosy_count = 14.0
nosy_names = ['terry.reedy', 'ncoghlan', 'rbcollins', 'benjamin.peterson', 'ezio.melotti', 'Arfrever', 'docs@python', 'berker.peksag', 'serhiy.storchaka', 'me@dennis.is', 'thomir', 'nitika', 'Mariatta', 'cheryl.sabella']
pr_nums = ['1671', '1671', '1867', '1875', '1876']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue17188'
versions = ['Python 3.6', 'Python 3.7']

[terryjreedy]

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.

[ncoghlan]

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

[medennisis]

We have added the from None to the documentation with a explanation and some example code.

[akheron]

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.

[nitika]

Hi,
As suggested by Petri,I have made some changes.
Please review the attached patch.Any comments and feedback are welcome.

[nitika]

Patch with some corrections.
Please review the patch attached.

[akheron]

The patch doesn't apply cleanly on 3.4 or default.

[thomir]

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.

[thomir]

OK, it seems that patch applies cleanly to 3.5 and 3.6.

[thomir]

Re-uploaded the patch without the typo.

[Mariatta]

reuploaded thomir's patch issue17188_3.4.patch as is.
I take no credit for this.