classification
Title: types.coroutines() idempotence documentation
Type: Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: antoine.pietri, docs@python, martin.panter, python-dev, scoder, yselivanov
Priority: normal Keywords: patch

Created on 2015-07-23 11:21 by antoine.pietri, last changed 2017-06-01 07:21 by antoine.pietri. This issue is now closed.

Files
File name Uploaded Description Edit
coro-idempotent.patch martin.panter, 2015-07-29 02:34 review
coro-idempotent.v2.patch martin.panter, 2015-08-01 08:18 Also define as decorator review
Messages (9)
msg247184 - (view) Author: Antoine Pietri (antoine.pietri) * Date: 2015-07-23 11:21
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?
msg247191 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-07-23 12:59
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
msg247553 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-07-29 01:54
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.
msg247554 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-07-29 02:34
Let me know if this patch works for you.
msg247583 - (view) Author: Antoine Pietri (antoine.pietri) * Date: 2015-07-29 16:50
Lgtm!
msg247585 - (view) Author: Stefan Behnel (scoder) * (Python committer) Date: 2015-07-29 17:30
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).
msg247801 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-08-01 08:18
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.
msg248786 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2015-08-18 18:50
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.
msg294909 - (view) Author: Antoine Pietri (antoine.pietri) * Date: 2017-06-01 07:21
I checked, the current doc gives a good explanation. I'm closing the issue.
History
Date User Action Args
2017-06-01 07:21:14antoine.pietrisetstatus: open -> closed

messages: + msg294909
stage: patch review -> resolved
2015-08-18 18:50:17yselivanovsetnosy: + yselivanov
messages: + msg248786
2015-08-01 08:18:52martin.pantersetfiles: + coro-idempotent.v2.patch

messages: + msg247801
2015-07-29 17:30:14scodersetnosy: + scoder
messages: + msg247585
2015-07-29 16:50:44antoine.pietrisetmessages: + msg247583
2015-07-29 02:34:47martin.pantersetfiles: + coro-idempotent.patch
versions: + Python 3.6
messages: + msg247554

keywords: + patch
stage: patch review
2015-07-29 01:54:47martin.pantersetmessages: + msg247553
2015-07-23 13:01:16yselivanovsetnosy: + martin.panter
2015-07-23 12:59:32python-devsetnosy: + python-dev
messages: + msg247191
2015-07-23 11:21:42antoine.pietricreate