[issue14911] generator.throw() documentation inaccurate
New submission from Kristján Valur Jónsson <kristjan@ccpgames.com>: 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) ---------- assignee: docs@python components: Documentation messages: 161565 nosy: docs@python, kristjan.jonsson priority: normal severity: normal status: open title: generator.throw() documentation inaccurate versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- stage: -> needs patch versions: -Python 3.1, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Yury Selivanov added the comment: Kristjan, can you write a patch for this? ---------- nosy: +yselivanov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Kristján Valur Jónsson added the comment: 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 ---------- keywords: +patch Added file: http://bugs.python.org/file33886/throw27.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Kristján Valur Jónsson added the comment: And 3.x ---------- Added file: http://bugs.python.org/file33888/3x.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Yury Selivanov added the comment: I like the patches, except the example in 3x.diff. Please see the review. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Kristján Valur Jónsson added the comment: Note that the docstring does not match the doc: PyDoc_STRVAR(throw_doc, "throw(typ[,val[,tb]]) -> raise exception in generator,\n\ return next yielded value or raise StopIteration."); Should I change the docstring too? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Martin Panter added the comment: 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? ---------- nosy: +vadmium versions: +Python 3.4, Python 3.5, Python 3.6 -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Martin Panter added the comment: 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 <https://docs.python.org/dev/reference/datamodel.html#coroutine.throw> * Change the doc string(s) to match the argument names, but don’t bother copying the full definition text ---------- stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Martin Panter added the comment: 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 ---------- Added file: http://bugs.python.org/file41245/throw-3x.v2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Yury Selivanov added the comment: Martin, could you please rebase your patch on top of recent cpython default branch, so that a 'review' link appears? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Martin Panter added the comment: This one is based on the public 3.5 branch, so should work. I corrected a small typo made in the previous patch. ---------- versions: -Python 3.4 Added file: http://bugs.python.org/file41360/throw-3x.v3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment: 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! ---------- nosy: +cheryl.sabella _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue14911> _______________________________________
participants (5)
-
Cheryl Sabella -
Kristján Valur Jónsson
-
Martin Panter
-
Yury Selivanov
-
Éric Araujo