In the new types.coroutines() documentation, it is not clearly stated whether this function is idempotent or not: what happens when it is called on a function that is already a native coroutine?

New changeset 636ce05ea8f6 by Yury Selivanov in branch '3.5':
Issue #24692: Add more tests for types.coroutine
https://hg.python.org/cpython/rev/636ce05ea8f6

New changeset 3f3e398bcd3e by Yury Selivanov in branch 'default':
Merge 3.5 (Issue #24692)
https://hg.python.org/cpython/rev/3f3e398bcd3e

Going by Yury’s tests and implementation, I think it is intended that:

* An “async def” coroutine factory function is accepted and passed through unmodified
* An generator–coroutine factory function that has already been transformed is also accepted
* If a wrapped function (not a normal coroutine nor generator factory) returns a coroutine instance (e.g. if the function was already decorated), the return value is never wrapped a second time

I will have a go at writing this up.

Let me know if this patch works for you.

Lgtm!

Note that the expected usage is not as a function but as a decorator. That should be stated in the docs as well. IMHO, users should only do two things with whatever the result is: either use it as a Generator (as before), or pass it as an argument to "await". Everything else is best considered implementation details. Well, except for the case of passing a coroutine, which will obviously just be passed through (and that answers the original question).

I think you are right that it would be typically used as a decorator. Patch v2 changes it to be defined as a decorator.

Not sure what the second part of your comment is referring to. The existing text about lack of __await__() maybe? You still have to have something (such as “asyncio”) drive the top-level coroutine. So that is a third thing users have to do with them. Passing a coroutine to “await” does not magically make it go, it just becomes a subordinate of the outer coroutine.

Is this still something that we need to address? I think that the current types.coroutine docs are pretty accurate and don't see where the proposed patch really improves them.

I checked, the current doc gives a good explanation. I'm closing the issue.