Frankly, this doesn't tell me much. The description doesn't even state thataiter(x) is equivalent tox.__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 thataiter(aiter(x)) is the same asaiter(x) (IOW thataiter(x) itself has an__aiter__() method that returnsself.)

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 becausePyObject_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 theiter(iter(x)) == iter(x) property, which is not currently mentioned intheiter docs. Theiter 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:

fromfunctoolsimportpartialwithopen('mydata.db','rb')asf:forblockiniter(partial(f.read,64),b''):process_block(block)

If this pattern is now obsoleted by assignment expressions[1], is it worth updating theiter docs to (1) mention theiter(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:

withopen('mydata.db','rb')asf:whileblock:=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 promiseiter(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 theaiter docs too? I did add atest_aiter_idempotent() for this in 6ee8824 to go along with the promise that theaiter 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 theiter() docs than for the initial version of theaiter() 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 callsiter(x), so that in

for i in iter(x): ...

the for-loop ends up callingiter(iter(x)). It's the same forasync for andaiter().