Repository navigation
Let StopIteration be caught in try/except - #920
Open
HoneyBearTech wants to merge 1 commit into
Open
HoneyBearTech wants to merge 1 commit into
HoneyBearTech wants to merge 1 commit into
Conversation
Python turns a StopIteration that leaves a coroutine into
RuntimeError("coroutine raised StopIteration"), so next() on an empty
iterator, a native __next__ or a raise StopIteration in a script could
never be caught with except StopIteration.
Where that happens to one of the interpreter's own coroutines, the
StopIteration is now put in a private carrier exception right away:
aeval() and the operator nodes catch Python's RuntimeError as it
arrives from the coroutine they await, and the helpers that run native
code catch the StopIteration itself. try/except matches and binds the original
StopIteration, and with blocks pass it to __exit__. The handler
expressions and bodies, the finally clause and __exit__ run with it as
the exception being handled, so a bare raise, exception context and
sys.exception() behave as in Python. An element of a generator
expression that raises it gives RuntimeError("generator raised
StopIteration"), as in Python. An uncaught one is reported as
StopIteration with the script line, also in Jupyter. A RuntimeError
from a native generator or coroutine, or one a script raises, is
unchanged.
The two small differences that remain are listed in the language
limitations in the docs.
Tests compare the results with CPython.
Signed-off-by: Sean Stoube <31805425+HoneyBearTech@users.noreply.github.com>
honeybeartech-homelab-automation
Bot
force-pushed
the
fix-stopiteration
branch
from
November 22, 2026 03:04
b8c3717 to
c89c40b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was broken
A
StopIterationcould never be caught in pyscript, even in the simplest script:An uncaught one was reported as
RuntimeError: coroutine raised StopIteration, which doesn't say what really happened.Why
AstEval(aeval()and theast_*methods).StopIterationthat leaves a coroutine intoRuntimeError("coroutine raised StopIteration").StopIterationfromnext(), an iterator's__next__, any native function, or a script's ownraise StopIterationleft the coroutine it was raised in as aRuntimeError.except StopIterationnever matched,withblocks passed theRuntimeErrorto__exit__, and the original exception and itsvaluewere only reachable through__cause__.What I changed
EvalStopIteration(aRuntimeErrorsubclass), carries the originalStopIterationout of pyscript's coroutines. Onlyeval.pycreates it, at the point where Python's conversion would happen:aeval(), and the operator nodes (binary and unary operators and comparisons) around their per-operator methods, catch Python'sRuntimeErroras it arrives from the coroutine they awaited. They recognise Python's own conversion by its exact type, itsStopIterationcause and a traceback that ends at the awaiting frame, never by message or arguments. So a script's ownraise RuntimeError("coroutine raised StopIteration")stays aRuntimeError, and the exception's arguments are never compared or touched.StopIterationitself and raise the carrier instead:call_func), including creating an instance (a native__new__or__init__, a metaclass__call__) and a zero-argumentsuper();__setitem__, unpacking) and*unpacking;obj.x = v,obj.x += 1,del obj.x): a native property setter or deleter, a native__setattr__/__delattr__or a metaclass's, and the property lookup before it. The catch is insideEvalAttrSet.setattr_asyncanddelattr_async, the helpers Support @property and @classmethod on pyscript class methods #918 added, because by the time the exception reaches the assignment code Python has already turned it into aRuntimeError;__prepare__;exceptclause (a metaclass's__instancecheck__);nonlocalresolution;eval(),exec()andlocals().async for,async defandasync withnow go straight to the same methods asfor,defandwith, soaeval()checks them directly.try/exceptmatches and binds the originalStopIteration. Tuple handlers,except Exception as exc,.valueand.argswork as in Python.excepttype expressions, the handler bodies and thefinallyclause run with the originalStopIterationas the exception being handled. So a bareraise,raise ... from,__context__andsys.exception()behave as in Python.ast_tryre-raises explicitly, and no longer returns from inside afinallyblock.withandasync withpass the original exception, its type and its traceback to__exit__/__aexit__, which can suppress it.contextlib.suppress(StopIteration),@contextlib.contextmanagerandnullcontext()work.raisere-raisessys.exception()explicitly, and raisesRuntimeError("No active exception to reraise")when there is none, as in Python.forloops, comprehensions and generator expressions still end normally when their iterator runs out. An element of a generator expression that raisesStopIterationlets it out of the generator, so Python itself givesRuntimeError("generator raised StopIteration")with theStopIterationas its cause, as in Python.RuntimeError:StopIterationescape;RuntimeErrorPython would give it.StopIterationis reported asStopIteration, with the script line that raised it.EvalExceptionFormatterbuilds that traceback, and the Jupyter kernel's error reply now uses the same exception for its name and value.StopIterationis involved, sotrystatements are as fast as before. A loop of 10,000trystatements runs within a few percent of master, both without an exception and with a caughtValueError.Testing
test_stop_iteration_matches_pythonintests/test_unit_eval.py. It runs 57 scripts in CPython and in pyscript and compares every result. They cover:next()with and without a default,raise StopIteration,raise StopIteration(5)and several arguments;except StopIteration, tuple handlers,except Exception as exc,.valueand.args, handler expressions, and anexceptexpression that fails;raisein a handler,raise ... from,__context__,sys.exception(), and a handler that clears the traceback before re-raising;finally, including one that clears the traceback of the exception passing through it;withandasync withwhose__exit__/__aexit__sees and suppresses it,contextlib.suppress,@contextlib.contextmanagerandnullcontext();sortedkey,functools.partial, a property,map), native async functions and tasks (where a genuineRuntimeErrorstays one);forloops, list, set and dict comprehensions, and generator expressions, including an element that raises it;+,==,not, unary-,in,__setitem__, a property setter,__iter__and__hash__;obj.x,obj.x = v,obj.x += 1anddel obj.x, a native__setattr__/__delattr__, a metaclass's__setattr__/__delattr__and property, a classmethod called on the class and on an instance, and a getter'sAttributeErrorfalling back to a pyscript or compiled__getattr__that raises it, each checking the exception's type and value, including aStopIterationsubclass;StopIterationescape, where the genuineRuntimeErrorstays one;__prepare__,eval()andexec(), and decorators that raise it;__init__and caught by the caller ofCls(), in a base__init__reached throughsuper().__init__()(pyscript or compiled) orBase.__init__(), and in__new__(pyscript or compiled);RuntimeError("coroutine raised StopIteration"), and aRuntimeErrorwhose argument has an__eq__that must never be called.test_stop_iteration_uncaught_reportchecks the error report:StopIterationwith the script line, and withoutRuntimeError;StopIterationas its context;StopIterationas the direct cause ofRuntimeError: generator raised StopIteration.test_jupyter_kernel_msgschecks thatraise StopIteration(5)gives the error nameStopIterationand value5.sphinx-build -Wpass on Python 3.14.Docs
A new item in Language Limitations says that
StopIterationcan be caught as in Python, and lists the two small differences that remain:async defthat raises it and is awaited through a native task givesStopIteration, where Python givesRuntimeError("coroutine raised StopIteration");withstatement whose__exit__/__aexit__returns an object whose__bool__or__len__raisesStopIterationraisesRuntimeErrorinstead.Note
Remaining differences from Python that this PR doesn't fix:
except*(exception groups) isn't supported in pyscript, as before.except BaseExceptiononly catchesExceptionsubclasses in pyscript, as before.async defthat raisesStopIteration, awaited through a native task (for example a@pyscript_compilecoroutine doingawait asyncio.create_task(f())), givesStopIterationwhere Python givesRuntimeError("coroutine raised StopIteration").withblock whose__exit__/__aexit__returns an object whose__bool__or__len__raisesStopIterationgivesRuntimeErrorinstead ofStopIteration.__getattribute__raisesStopIterationfor every name, including__class__, can still giveRuntimeError: pyscript's ownisinstance()check on a value, before the attribute is looked up, runs that method outside the catch. This was already the case before this rebase.My lambda PR (#919) and this PR both change
eval.py. Whichever merges second needs a rebase of about 6 hunks, inast_lambda,try_handlers,loopvar_scope_saveand the list, dict and set comprehension loops, plus the sameStopIterationcatch in the two comprehension-scope helpers the lambda PR adds (loopvar_scope_enterandloopvar_scope_exit). I'm happy to do it. Both PRs also add tests at the end oftests/test_unit_eval.py, which is a small "keep both" conflict. This PR is rebased onto master after #918. Mysuper().propPR (#923) merges cleanly with this PR'seval.pychanges. Both add tests at the end of the test file, so whichever merges later needs a small test-file update.