[issue24692] types.coroutines() idempotence documentation
New submission from Antoine Pietri:
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?
----------
assignee: docs@python
components: Documentation
messages: 247184
nosy: docs@python, seirl
priority: normal
severity: normal
status: open
title: types.coroutines() idempotence documentation
versions: Python 3.5
_______________________________________
Python tracker
Roundup Robot added the comment:
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
----------
nosy: +python-dev
_______________________________________
Python tracker
Changes by Yury Selivanov
Martin Panter added the comment:
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.
----------
_______________________________________
Python tracker
Martin Panter added the comment:
Let me know if this patch works for you.
----------
keywords: +patch
stage: -> patch review
versions: +Python 3.6
Added file: http://bugs.python.org/file40050/coro-idempotent.patch
_______________________________________
Python tracker
Antoine Pietri added the comment:
Lgtm!
----------
_______________________________________
Python tracker
Stefan Behnel added the comment:
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).
----------
nosy: +scoder
_______________________________________
Python tracker
Martin Panter added the comment:
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.
----------
Added file: http://bugs.python.org/file40092/coro-idempotent.v2.patch
_______________________________________
Python tracker
Yury Selivanov added the comment:
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.
----------
nosy: +yselivanov
_______________________________________
Python tracker
Antoine Pietri added the comment:
I checked, the current doc gives a good explanation. I'm closing the issue.
----------
stage: patch review -> resolved
status: open -> closed
_______________________________________
Python tracker
participants (5)
-
Antoine Pietri -
Martin Panter
-
Roundup Robot
-
Stefan Behnel
-
Yury Selivanov