[Feature]: Lifecycle management for asyncstdlib-created iterators

[hongyiweiwu01]

Describe the feature

This might be more of a request for usage guidance than one for new features. If I have an AsyncGenerator agen() and I pass it into one of the asyncstdlib iterators, say enumerate, my understanding is enumerate now ties the cleanup of agen to its own cleanup. But that doesn't mean enumerate(agen()) is deterministically cleaned-up -- for instance, in the following scenario:

async for i, item in asyncstdlib.enumerate(agen()):
    if i > 2:
        break

So would the correct solution in this case be to wrap the entire code block in async with asyncstdlib.scoped_iter(asyncstdlib.enumerate(agen())) as safe_enum_it and iterate on safe_enum_it instead?

A potentially related situation is with how asyncstdlib.list owns the internal iterable. If I just do a = await asyncstdlib.list(agen()), and for some reason (maybe an external exception) the execution is interrupted and agen() doesn't finish iterating, would it be correct to assume that the cleanup isn't guaranteed to happen, and we should ideally do something like

async with asyncstdlib.scoped_iter(agen()) as safe_agen_it:
   a = await asyncstdlib.list(safe_agen_it)

instead?

I really love this library, so would really appreciate your explanation on this. Thank you!

Request Assignment [Optional]

• I already have a plan and want to submit an implementation.

[maxfischer2781]

Thanks for the questions! I've moved this to Discussions since that seems more appropriate in this case - feel free to open another issue if you have a specific request.

Cleanup in general

Indeed asyncstdlib pushes the closing responsibility just up the stack but does not remove it entirely. If your iteration code breaks or returns or an exception is likely then scoped_iter is the safe bet.
For some use-cases there are more appropriate building blocks, though. For example, enumerate+break often should be just islice (in fact these two are why asyncstdlib was born ages ago). From my personal projects, I can really recommend writing your own helpers if you find yourself writing the same stop+cleanup logic again and again.

That said, missing out on closing an async iterator/generator is not the end of the world. Async generator cleanup is weird if you try and hit every edge case (see e.g. python-trio/trio#265 if you have too much time) so just do your best.

Cleanup for asyncstdlib.list

Honestly, I think this is a blunder on my part. asyncstdlib.list and related functions should give the same guarantees as others and clean up the iterator on error.