Stronger async neutral iter?

[maxfischer2781]

The builtins.iter and most things using it (or its underlying helper) currently accept both Iterable and AsyncIterable to be "async neutral". However, there is an additional case of Awaitable[Iterable] that is not handled.

• Is it worth supporting this case?
• Should the standard builtins.iter support this case?

---

This case can easily occur when working with functions that may be either a generator or return an iterable. In the sync case, both of these are very similar – we can fetch the values from either via any iterable-consumer, such as list:

def gen(n):
    for i in range(n):
        yield i

def lst(n):
    return [*range(n)]

# this is fine
print(list(gen(5)), list(lst(5)))

In the async case, the two are in fact very different. One is an Awaitable[Iterator] that requires for ... in await x and the other is an AsyncIterator that requires async for ... in x.

async def agen(n):
    for i in range(n):
        yield i

async def alst(n):
    return [*range(n)]

# [THIS-IS-FINE.GIF]
print([item async for item in gen(5)], list(await lst(5)))

[maxfischer2781]

Where to put the new functionality?

There is an important point against extending asyncstdlib.builtins.iter itself: The real standard library iter and aiter as well as asyncstdlib.builtins.iter currently all are failsafe if the argument is not iterable. All of these explicitly or implicitly check whether the argument is iterable before doing anything with it.

That is only possible for the flat AsyncIterable[T] and Iterable[T], but not the nested Awaitable[Iterable[T]] – for the latter, we have to run code via await before being able to check whether we actually have any iterable. So, if someone accidentally or for EAFP passes in an Awaitable[T], we would run arbitrary code and throw away the result before signaling an error.

Using a separate tool such as asyncstdlib.asynctools.anyiter probably better covers all angles, since it would be opt-in.

[maxfischer2781]

Possible names in asynctools:

• very short: iter, asiter
• "anything": any_iter, anyiter
• punny: ny_iter (as a.ny_iter), anyter, s_iter (as a.s_iter)

[maxfischer2781]

What cases to cover?

Obviously we should cover at least the cases of the default iter: Iterable and AsyncIterable.

The motivating case is Awaitable[Iterable], so this should be in as well.

We actually also have an additional case, already handled by asynctools.await_each: Iterable[Awaitable].
Including this in one helper seems simple enough and would make it suitable for normalizing iteration.

I don't think cases like Iterable[AsyncIterable], i.e. flattening, should be covered, since that is always a bit murky ("should a str/dict/... be flattened?").

I see some value in having "async flattening", e.g. Awaitable[Iterable[Awaitable[T]]] or similar to just AsyncIterable[T]. Not sure how deep this should go – e.g. Iterable[Awaitable[Awaitable[T]]]?
A mere flatten=False switch could do. Having a helper for "async flattening" might be useful as well, rare as the case is.