Why do we need the asyncio.coroutine decorator?

Question

Why do we need the asyncio.coroutine decorator? What functionality does it provide?

For example:

# import asyncio
# @asyncio.coroutine
def gen():
    value = yield("Started")
    print(value)

a = gen()
a.send(None)
a.send("Done")

Now if I uncomment the first two lines and use the asyncio.coroutine decorator, I still get the same output.

I mean this is already a coroutine - a function that can be paused and passed in with an argument. Why do I need to decorate it with another coroutine i.e asyncio.coroutine?

Answer 1

It's important to understand that generators and asyncio coroutines - are different things. Coroutines are implemented using generators, but (theoretically) could been implemented without them. Genarators - are part of implementation regarding to coroutines.

Since asyncio coroutines are implemented using generators, you can sometimes use generators as coroutines without errors:

import asyncio


def main():
    yield from asyncio.sleep(1)
    print('done')


loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Result:

done

---

But it doesn't work with every kind of coroutine:

import asyncio


def main():
    # yield from asyncio.sleep(1)
    print('done')


loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Result:

TypeError: An asyncio.Future, a coroutine or an awaitable is required

---

That's why (besides few other things) asyncio.coroutine decorator uses:

import asyncio


@asyncio.coroutine
def main():
    # yield from asyncio.sleep(1)
    print('done')


loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Result:

done

---

But as already noted by all it doesn't actually matter today: since Python 3.5 decorator and yield from have been replaced with keywords async def and await that's not only nicer, but helps to split coroutines from their implementation details in a better way.

import asyncio


async def main():
    # await asyncio.sleep(1)
    print('done')


loop = asyncio.get_event_loop()
loop.run_until_complete(main())