gh-64862: Add the stop_exception parameter in iter() and aiter()

[serhiy-storchaka]

iter() and aiter() now accept the keyword-only stop_exception parameter -- an exception class or a tuple of exception classes which ends the iteration:

for item in iter(queue.get_nowait, stop_exception=Empty):
    ...

async for item in aiter(queue.get, stop_exception=QueueShutDown):
    ...

Many callables report exhaustion by raising an exception instead of returning a special value, so the sentinel form cannot be used with them at all.

aiter() also gained the callable form, which it did not have before: the callable is called and its result is awaited for every __anext__() (the callable is only called when the result of __anext__() is awaited).

The second parameter of iter() is now named stop_value and can be passed by keyword. It can be omitted if stop_exception is given.

stop_exception=StopIteration (StopAsyncIteration for aiter()) and an empty tuple never change the behavior, so they are normalized to "no stop exception"; such an iterator is pickled exactly as before. For other cases callable_iterator now has __setstate__(), because the stop exception and the absence of the sentinel cannot be expressed as arguments of iter().

• Issue: Introduce exception argument to iter #64862

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34202807 | 📁 Comparing 5877437 against main (c1fc445)

  🔍 Preview build  

4 files changed

± library/functions.html
± library/tempfile.html
± whatsnew/3.16.html
± whatsnew/changelog.html