GeezerVison

Frankly, this doesn't tell me much. The description doesn't even state that aiter(x) is equivalent to x.__aiter__(), which to me is the key point. Certainly it shouldn't start by stating the type of what it returns; it should describe how the return value relates to the input. (Compare the entry for abs(x) above, "Return the absolute value of a number." This clearly references the input and what the function does to that value.)

Also, state explicitly that aiter(aiter(x)) is the same as aiter(x) (IOW that aiter(x) itself has an __aiter__() method that returns self.)

Incorporated in the latest revision, but please let me know if it needs further refinement. Thanks for the great feedback!

Is it necessary to add these to the public C API? Just because PyObject_GetIter() is public I'm not sure that the Aiter variant needs to be. @vstinner tends to push back on adding new things to the C API. @1st1 what do you think?

I don't mind adding this function -- while somewhat trivial, it's something that projects like Cython (and potentially our own modules like _asynciomodule.c) have to reimplement.

Maybe these types and the function below should remain CPython implementation details? Just because they're returned by builtins doesn't mean all the implementation types need to be in the C-level API.

+1. I'd make them internal.

Makes sense, thanks. Done in the latest revision. Another look?

Much better! Here is how I would rearrange this:

Return an :term:`asynchronous iterator`
for an :term:`asynchronous iterable`. 
Equivalent to calling ``x.__aiter__()``.

``aiter(x)`` itself has an ``__aiter__()`` method that returns ``x``,
so ``aiter(aiter(x))`` is the same as ``aiter(x)``.

Incorporated in the latest revision, thanks!

(((
Come to think of it, iter also has the iter(iter(x)) == iter(x) property, which is not currently mentioned in the iter docs. The iter docs have a lot more work to do though, to cover the 1- and 2-arg variants (and they're already doing this very well).

And now that I'm looking at those again, I notice the only code example there is for the 2-arg variant:

from functools import partial
with open('mydata.db', 'rb') as f:
    for block in iter(partial(f.read, 64), b''):
        process_block(block)

If this pattern is now obsoleted by assignment expressions[1], is it worth updating the iter docs to (1) mention the iter(iter(x)) == iter(x) property, and (2) remove the obsoleted example code? If so, happy to submit a separate PR for that.

[1] as in the following:

with open('mydata.db', 'rb') as f:
    while block := f.read(64):
        process_block(block)

)))

I don't want to personally get into the weeds about the iter() docs, sorry. Something for the docs WG perhaps.

I don't think it's worth updating the docs to promise iter(iter(x)) == iter(x) as it isn't a specific benefit to the user beyond logically doing the right thing.

I can see that.

@gvanrossum, do you think @brettcannon's rationale applies equally to the aiter docs too? I did add a test_aiter_idempotent() for this in 6ee8824 to go along with the promise that the aiter docs are now making, but can remove that test along with that part of the docs if that's better.

I think there's a different bar for updating the iter() docs than for the initial version of the aiter() docs. And they don't have to match precisely.

FWIW the main reason the idempotency property is important is because of the implicit [a]iter() call in a for-loop, since in

for i in x: ...

the for-loop calls iter(x), so that in

for i in iter(x): ...

the for-loop ends up calling iter(iter(x)). It's the same for async for and aiter().