What is the difference between @types.coroutine and @asyncio.coroutine decorators?

Question

Documentations say:

@asyncio.coroutine

Decorator to mark generator-based coroutines. This enables the generator use yield from to call async def coroutines, and also enables the generator to be called by async def coroutines, for instance using an await expression.

_

@types.coroutine(gen_func)

This function transforms a generator function into a coroutine function which returns a generator-based coroutine. The generator-based coroutine is still a generator iterator, but is also considered to be a coroutine object and is awaitable. However, it may not necessarily implement the __await__() method.

So is seems like purposes is the same - to flag a generator as a coroutine (what async defin Python3.5 and higher does with some features).

When need to use asyncio.coroutine when need to use types.coroutine, what is the diffrence?

Answer 1

The difference is if you have a yield statement or not. Here's the code:

from types import coroutine as t_coroutine
from asyncio import coroutine as a_coroutine, ensure_future, sleep, get_event_loop


@a_coroutine
def a_sleep():
    print("doing something in async")
    yield 1


@t_coroutine
def t_sleep():
    print("doing something in types")
    yield 1


async def start():
    sleep_a = a_sleep()
    sleep_t = t_sleep()
    print("Going down!")


loop = get_event_loop()
loop.run_until_complete(start())

In this example everything seem same - here's the debugging info from pycharm (we're standing on the "Going down!" line). Nothing is printed in console yet, so the functions didn't start yet.

But if we remove the yield, the types version will start function instantly!

from types import coroutine as t_coroutine
from asyncio import coroutine as a_coroutine, ensure_future, sleep, get_event_loop


@a_coroutine
def a_sleep():
    print("doing something in async")


@t_coroutine
def t_sleep():
    print("doing something in types")


async def start():
    sleep_a = a_sleep()
    sleep_t = t_sleep()
    print("Going down!")


loop = get_event_loop()
loop.run_until_complete(start())

Now we have doing something in types in console printed. And here's the debug info:

As you can see it starts right after call, if there is no result and returns None.

---

As for usage, you should use asyncio version always. If you need to run it like fire and forget (running instantly and getting results later) - use ensure_future function.

Answer 2

One other subtle difference: generator-based coroutines decorated with @asyncio.coroutine will test True for asyncio.iscoroutinefunction(), while those decorated with @types.coroutine will test False.

# testcoro.py
import asyncio
import inspect
import types

@asyncio.coroutine
def old_coro_with_asyncio():
    yield from asyncio.sleep(1)

@types.coroutine
def old_coro_with_types():
    yield from asyncio.sleep(1)

if __name__ == "__main__":
    for coro in (old_coro_with_asyncio, old_coro_with_types):
        print(coro.__name__, 'iscoroutine:', asyncio.iscoroutine(coro))
        print(coro.__name__, 'iscoroutinefunc:', asyncio.iscoroutinefunction(coro))

Output:

(py37) $ python3 testcoro.py 
old_coro_with_asyncio iscoroutine: False
old_coro_with_asyncio iscoroutinefunc: True
old_coro_with_types iscoroutine: False
old_coro_with_types iscoroutinefunc: False

Nonetheless, both of these are awaitable.

---

_{*Note also that this difference does not apply to their _results: replace iscoroutinefunction() with iscoroutine() (which tests for a coroutine object), and old_coro_with_asyncio() + old_coro_with_types() will evaluate False for both.}