[issue15355] generator.__next__() docs should mention exception if already executing
New submission from Chris Jerdonek <chris.jerdonek@gmail.com>: I think the generator.__next__() documentation should say that it raises an exception if the generator is already executing: http://docs.python.org/dev/reference/expressions.html#generator.__next__ I don't think this is currently mentioned anywhere in the section on yield expressions. I think this is worth mentioning because this is different from the general situation for iterators, for example. One consequence of this is that, unlike for iterators, using a bare generator in a multithreaded situation will always result in a critical section (since an iterator can be made to take care of its own locking, etc). ---------- assignee: docs@python components: Documentation keywords: easy messages: 165476 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: generator.__next__() docs should mention exception if already executing versions: Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Chris Jerdonek <chris.jerdonek@gmail.com> added the comment: This is a very simple patch. ---------- keywords: +patch Added file: http://bugs.python.org/file26525/issue-15355-1.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Changes by Chris Jerdonek <chris.jerdonek@gmail.com>: ---------- stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- nosy: +ncoghlan _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Chris Jerdonek added the comment: Terry, if when reviewing my patch for issue 15457, you also have time to review this much simpler patch (also in the documentation on generators), I would appreciate it. If not, that's okay. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Meador Inge added the comment: Hmmm, in your original description you say that the 'generator.__next__' documentation should be changed, but in the patch the note applies to all generator methods. From looking at the code it seems that the patch is correct and that '__next__', 'send', 'throw', and 'close' can all raise the "already executing" exception via 'gen_send_ex'. Documenting this behavior seems reasonable, but you should probably mention what exception gets raises. BTW, you don't need to make the Misc/NEWS changes a part of your patches. A core dev will write that for you and since Misc/NEWS is changed so much it might conflict and make patches harder to apply across similar branches (say 3.2 and 3.3). ---------- nosy: +meador.inge _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Chris Jerdonek added the comment:
Hmmm, in your original description you say that the 'generator.__next__' documentation should be changed, but in the patch the note applies to all generator methods.
Thanks, Meador. Yes, I realized that later. Retitling now. I will also add the exception type. I wasn't sure if that was implementation-specific.
BTW, you don't need to make the Misc/NEWS changes
Certainly -- will do from now on. Thanks for telling me. I had thought I was helping. New patch attached. ---------- title: generator.__next__() docs should mention exception if already executing -> generator docs should mention already-executing exception Added file: http://bugs.python.org/file26560/issue-15355-2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Chris Jerdonek added the comment: Meador, does this language look okay to you now that it states the exception type? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Meador Inge added the comment: Hi Chris, it seems reasonable to me, but I would feel more comfortable if someone (like Nick) that is more familiar with the generator implementation can comment on this as well. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Chris Jerdonek added the comment: Nick, would you be able to take a look at this minor documentation patch re: generators? Would you prefer this blanket statement, or an explicit (possibly repeated) statement inside the documentation of each method? ---------- versions: +Python 2.7, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
R. David Murray added the comment: Chris, if Nick is too busy to reply right now and you want to move this along, you could write some tests (not necessarily for inclusion in the test suite) to confirm that the doc you are adding is correct. I don't know enough about generators to comment myself, I'd have to write tests :) ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Chris Jerdonek added the comment: Good suggestion, David. Here is such sample test code. It is adapted from the sample code for "ValueError: generator already executing" included in PEP 255: def test_gen(call_gen_method): def gen(): call_gen_method(me) yield 1 me = gen() try: me.__next__() except Exception as e: print(repr(e)) test_gen(lambda g: g.__next__()) test_gen(lambda g: g.send(1)) test_gen(lambda g: g.throw(OSError)) test_gen(lambda g: g.close()) This outputs: ValueError('generator already executing',) ValueError('generator already executing',) ValueError('generator already executing',) ValueError('generator already executing',) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
Roundup Robot added the comment: New changeset dc4b00f51c48 by R David Murray in branch '3.2': #15355: Mention already-executing Exception in generator docs. http://hg.python.org/cpython/rev/dc4b00f51c48 New changeset 73f1ba3319dd by R David Murray in branch 'default': Merge #15355: Mention already-executing Exception in generator docs. http://hg.python.org/cpython/rev/73f1ba3319dd New changeset a62309ae88a2 by R David Murray in branch '2.7': #15355: Mention already-executing Exception in generator docs. http://hg.python.org/cpython/rev/a62309ae88a2 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
R. David Murray added the comment: Confirmed that 2.7 raises the same errors (as I expected) using your test. Thanks, Chris. ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________
participants (5)
-
Chris Jerdonek -
Meador Inge
-
Nick Coghlan
-
R. David Murray
-
Roundup Robot