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.

Title: generator.throw() documentation inaccurate
Type: Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: asvetlov, cheryl.sabella, docs@python, dpg, gvanrossum, kristjan.jonsson, martin.panter, miss-islington, yselivanov
Priority: normal Keywords: easy, patch

Created on 2012-05-25 11:02 by kristjan.jonsson, last changed 2022-04-11 14:57 by admin. This issue is now closed.

File name Uploaded Description Edit
throw27.diff kristjan.jonsson, 2014-02-03 15:19
3x.diff kristjan.jonsson, 2014-02-03 15:57 review
throw-3x.v2.patch martin.panter, 2015-12-05 01:23 For Python 3
throw-3x.v3.patch martin.panter, 2015-12-19 01:21 review
Pull Requests
URL Status Linked Edit
PR 32207 merged dpg, 2022-03-31 00:58
PR 32213 merged miss-islington, 2022-03-31 13:57
PR 32214 merged miss-islington, 2022-03-31 13:57
Messages (16)
msg161565 - (view) Author: Kristján Valur Jónsson (kristjan.jonsson) * (Python committer) Date: 2012-05-25 11:02
the documentation for generator.throw() does not mention the fact that it has the same semantics for the three arguments as a "raise" expression has.
The first two arguments can be:
throw(exc_type, None)
throw(exc_type, value)
throw(exc_type, exc_instance)
throw(exc_instance, None)
msg209836 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-01-31 22:11
Kristjan, can you write a patch for this?
msg210139 - (view) Author: Kristján Valur Jónsson (kristjan.jonsson) * (Python committer) Date: 2014-02-03 15:19
Here's one for 2.7.  I'm still looking at 3.  The funny thing is that the signature of generator.throw reflects 2.x conventions.  I'm figuring out if it can be used with the .with_traceback() idiom
msg210146 - (view) Author: Kristján Valur Jónsson (kristjan.jonsson) * (Python committer) Date: 2014-02-03 15:57
And 3.x
msg210150 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-02-03 17:35
I like the patches, except the example in 3x.diff. Please see the review.
msg210188 - (view) Author: Kristján Valur Jónsson (kristjan.jonsson) * (Python committer) Date: 2014-02-04 09:45
Note that the docstring does not match the doc:
"throw(typ[,val[,tb]]) -> raise exception in generator,\n\
return next yielded value or raise StopIteration.");

Should I change the docstring too?
msg245559 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-06-20 12:00
See Issue 13213 for some analysis of the behaviour of different combinations of arguments.

The docstring should be changed if necessary, but in this case I don’t see what needs changing. The argument names perhaps, just for consistency’s sake?
msg254824 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-11-18 00:00
I can’t really comment on the 2.7 version, because I’m not too familiar with Python 2 exceptions.

For Python 3, is there any reason to bless the None, tuple or non-exception cases as the exception “value” argument? IMO these just make things too complicated without any benefit. Changes I would make to the patch:

* Only mention that “value” can be omitted, or it can be an instance of the class specified by “type”. Drop mentioning the None option, and the single or tuple constructor argument options. It looks like the tuple option actually gets expanded to multiple constructor arguments?!
* Mention that if “value” is passed, its traceback could be lost
* Drop the example, unless someone can come up with a concise and realistic example
* Unify with definition for coroutines <>
* Change the doc string(s) to match the argument names, but don’t bother copying the full definition text
msg255913 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-12-05 01:23
Changes in throw-3x.v2.patch:

* Split into two signatures
* Added parallel coroutine.throw(value) signature
* *Value* should be an exception instance; drop mentioning other options
* Default value is instantiated from *type*
* __traceback__ can be cleared
* Dropped the example
* Update generator and coroutine doc strings with double signatures
msg256627 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2015-12-17 23:32
Martin, could you please rebase your patch on top of recent cpython default branch, so that a 'review' link appears?
msg256716 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-12-19 01:21
This one is based on the public 3.5 branch, so should work. I corrected a small typo made in the previous patch.
msg327913 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-10-17 22:00
It seems that this patch was close to being merged.  Would it be helpful for me to create a PR for it over 3.8?  Thanks!
msg414774 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2022-03-08 21:03
This still hasn't been fixed. I suspect that a new patch should be produced and uploaded as a PR. It looks pretty simple.
msg416436 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2022-03-31 13:57
New changeset 8be7c2bc5ad5e295f0f855bb31db412eef2c7c92 by Dave Goncalves in branch 'main':
bpo-14911: Corrected generator.throw() documentation (GH-32207)
msg416437 - (view) Author: miss-islington (miss-islington) Date: 2022-03-31 14:23
New changeset 625f6704c0d783360574bbab2f78b0b9bbed5891 by Miss Islington (bot) in branch '3.10':
bpo-14911: Corrected generator.throw() documentation (GH-32207)
msg416438 - (view) Author: miss-islington (miss-islington) Date: 2022-03-31 14:24
New changeset 98d57737de73342d33d1b90dc0285f586465d22b by Miss Islington (bot) in branch '3.9':
bpo-14911: Corrected generator.throw() documentation (GH-32207)
Date User Action Args
2022-04-11 14:57:30adminsetgithub: 59116
2022-03-31 14:29:37asvetlovsetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: - Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8
2022-03-31 14:24:43miss-islingtonsetmessages: + msg416438
2022-03-31 14:23:12miss-islingtonsetmessages: + msg416437
2022-03-31 13:57:29miss-islingtonsetpull_requests: + pull_request30290
2022-03-31 13:57:24miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request30289
2022-03-31 13:57:02asvetlovsetnosy: + asvetlov
messages: + msg416436
2022-03-31 00:58:19dpgsetnosy: + dpg
pull_requests: + pull_request30282
2022-03-08 21:03:55gvanrossumsetversions: + Python 3.7, Python 3.8, Python 3.9, Python 3.10, Python 3.11
nosy: + gvanrossum

messages: + msg414774

keywords: + easy
2018-10-17 22:00:32cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg327913
2015-12-19 01:21:05martin.pantersetfiles: + throw-3x.v3.patch

messages: + msg256716
versions: - Python 3.4
2015-12-17 23:32:21yselivanovsetmessages: + msg256627
2015-12-05 01:23:11martin.pantersetfiles: + throw-3x.v2.patch

messages: + msg255913
2015-11-18 00:00:32martin.pantersetmessages: + msg254824
stage: needs patch -> patch review
2015-06-20 12:02:41martin.panterlinkissue13213 superseder
2015-06-20 12:00:48martin.pantersetnosy: + martin.panter

messages: + msg245559
versions: + Python 3.4, Python 3.5, Python 3.6, - Python 3.2, Python 3.3
2014-02-04 09:45:12kristjan.jonssonsetmessages: + msg210188
2014-02-03 17:35:14yselivanovsetmessages: + msg210150
2014-02-03 15:57:37kristjan.jonssonsetfiles: + 3x.diff

messages: + msg210146
2014-02-03 15:19:58kristjan.jonssonsetfiles: + throw27.diff
keywords: + patch
messages: + msg210139
2014-01-31 22:11:27yselivanovsetnosy: + yselivanov
messages: + msg209836
2012-05-25 18:42:09eric.araujosetstage: needs patch
versions: - Python 3.1, Python 3.4
2012-05-25 11:02:16kristjan.jonssoncreate