mypy should use CoroutineType instead of Coroutine for return types of async def functions

[A5rocks]

Feature

types.CoroutineType is defined as:

The type of coroutine objects, created by async def functions.

Evidently, async def functions return them. For context, they're a subclass of collections.abc.Coroutine with extra features.

Pitch

#18634 ran into this.

[A5rocks]

One slight complication is that the coroutines Cython returns do not pass an isinstance(value, types.CoroutineType) test. See https://github.com/python-trio/trio/actions/runs/13209523982/job/36880266237. I think this is a bug in Cython though, especially given they have tried to match the coroutine spec more closely. (this passes under CPython and PyPy)

---

And wouldn't you guess it, turns out they commented out a test checking this? https://github.com/cython/cython/blob/5084ea9a3be311b771baf3cdafe464914f86ec35/tests/run/test_coroutines_pep492.pyx#L879 (compared to the cpython test: https://github.com/python/cpython/blob/aa845af9bb39b3e2ed08bbb00a8e932a97be8fc0/Lib/test/test_coroutines.py#L537)

[da-woods]

I posted this elsewhere but it's worth emphasising here: Cython Coroutines simply cannot be of type types.CoroutineType because they use a different implementation. This is not a bug - it is simply a fact.

Unlike CPython and PyPy, Cython is not a standalone Python implementation so we do not get to control what the system regards as types.CoroutineType.

I suspect the upshot of this is that it is not appropriate to use mypy on Cython modules because MyPy demands a level of strictness about types that it is not possible for something like Cython to meet.

[JelleZijlstra]

I agree that it's not a bug for Cython to have its own coroutine type. In fact it's in line with the idea behind the types.CoroutineType / collections.abc.Coroutine split: you use CoroutineType if you mean the concrete built-in coroutine type, and collections.abc.Coroutine if you mean any coroutine type. Cython's coroutine type should then be another class that implements collections.abc.Coroutine.

A practical issue might be that people often want to access attributes like cr_frame on coroutine objects. These exist on CoroutineType but not Coroutine in our stubs, but I suspect Cython probably provides some of these attributes.