Coroutine functions should return Coroutine, not Awaitable

[jpochyla]

async def coro_func() -> None:
    pass
c = coro_func()
reveal_type(c)  # prints typing.Awaitable[builtins.None]

c above has all fields of typing.Coroutine, you can send and throw on it, but the type doesn't reflect that.

[gvanrossum]

Would you like to see if you can submit a PR to fix this?

[ilevkivskyi]

This would be simple to fix, by just changing the return type in semanal.py:

                    defn.type = defn.type.copy_modified(
                        ret_type = self.named_type_or_none('typing.Awaitable',
                                                           [defn.type.ret_type]))

To something like Coroutine[ret_type, None, NoReturn]. But this will also require many tedious changes in tests (because of error messages).

[jpochyla]

Thanks @ilevkivskyi! I think I can do the PR, with the test & doc changes. One thing I am not sure about is whether the return type of defs annotated with @types.coroutine should also be Coroutine, #2907 seems to indicate otherwise. Why wouldn't the type be the same? I thought they are basically equivalent.

[ilevkivskyi]

@jpochyla
The coroutines made by @types.coroutine (they are called generator based coroutines) are special in the sense that they provide compatibility between older versions of Python and Python 3.5+. Namely, you can do both await test() and yield from test() if it is defined as

@types.coroutine
def test():
    yield 1

You can't do await on normal generators, and you can't do yield from on native coroutines (made by async def). IIRC, there is even a special internal type in typeshed and mypy to denote generator based coroutines AwaitableGenerator.

[scottbelden]

Hi, just seeing if any progress was being made on this (as I stumbled on it today).

[ilevkivskyi]

@scottbelden
Unfortunately, it seems that no-one is working on this now. If you have time and enthusiasm, then you can try to fix it yourself.

[scottbelden]

I started trying to make an attempt to resolve this, but I'm afraid that without some help I don't think I'll be able to do it and might just have to wait for someone else to get to it. I started with making the changes in semanal.py that you mentioned in one of the previous messages and the tests did blow up as you expected, but I think in an unexpected way (at least unexpected to me). The errors were complaining about typing.Coroutine not found:

    assert ret_type is not None, "Internal error: typing.Coroutine not found"
AssertionError: Internal error: typing.Coroutine not found

I'm not sure why typing.Awaitable would be found but not typing.Coroutine.

[JelleZijlstra]

You may have to add it to one of the stub test files (typing.pyi somewhere in the test-data/ directory).

[AndreLouisCaron]

I also hit this issue yesteday. Here is one case where having Coroutine  rather than Awaitable would really help:

from asyncio import (
    AbstractEventLoop,
    get_event_loop,
    sleep,
    Task,
)
from typing import Coroutine, Optional


# NOTE: `loop.create_task()` only accepts coroutine objects.  It cannot accept
#       futures, nor tasks so we should not use `typing.Awaitable`.
def spawn(coro: Coroutine,
          loop: Optional[AbstractEventLoop]=None) -> Task:
    loop = loop or get_event_loop()
    return loop.create_task(coro)


# Any regular coroutine :-)
#
# I would expect `mypy` to deduce `Coroutine[Any, Any, Any]`, but it detects
# `Awaitable[None]`.
async def background_work() -> None:
    await sleep(5.0)
    print('DONE!')


# Demonstrate the type conflict :-)
async def main() -> None:
    task = spawn(background_work())  # error: Argument 1 to "spawn" has incompatible type "Awaitable[None]"; expected "Coroutine[Any, Any, Any]"
    print('waiting...')
    await task


if __name__ == '__main__':
    get_event_loop().run_until_complete(main())

[gvanrossum]

As a reminder to myself:

• Awaitable is a Protocol that just defines __await__, and Coroutine subclasses that and adds send(), throw() and close() methods.
• AbstractEventLoop.create_task() is defined to take a union of Coroutine and Generator.