stubgen generates stubs for `@asynccontextmanager` functions that mypy itself rejects

[selsky]

Bug Report

stubgen copies @asynccontextmanager and the async def keyword verbatim into the generated .pyi. Because a stub body has no yield, mypy then classifies the stubbed function as a coroutine function returning AsyncIterator[T] rather than as an async generator function, and rejects the decorator application.

The result is that stubgen emits a stub which mypy — the same version, with default settings — reports an error on. Source that type-checks cleanly produces a stub that does not.

To Reproduce

# cm.py
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager


@asynccontextmanager
async def ctx() -> AsyncIterator[int]:
    yield 1

$ mypy cm.py
Success: no issues found in 1 source file

$ stubgen -o out cm.py
Processed 1 modules
Generated out/cm.pyi

$ cat out/cm.pyi
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

@asynccontextmanager
async def ctx() -> AsyncIterator[int]: ...

$ mypy out/cm.pyi
out/cm.pyi:4: error: Argument 1 to "asynccontextmanager" has incompatible type "Callable[[], Coroutine[Any, Any, AsyncIterator[int]]]"; expected "Callable[[], AsyncIterator[Never]]"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

The same happens for methods, and with AsyncGenerator[T, None] in place of AsyncIterator[T].

Expected Behavior

stubgen output should type-check under the mypy version that produced it. For an @asynccontextmanager-decorated async generator, that means emitting one of the two spellings the typing docs sanction for stubs — either dropping async:

@asynccontextmanager
def ctx() -> AsyncIterator[int]: ...

or dropping the decorator and declaring the decorated result, as typeshed does:

from contextlib import AbstractAsyncContextManager

def ctx() -> AbstractAsyncContextManager[int]: ...

Both of these are accepted by mypy 2.3.0.

Actual Behavior

out/cm.pyi:4: error: Argument 1 to "asynccontextmanager" has incompatible type "Callable[[], Coroutine[Any, Any, AsyncIterator[int]]]"; expected "Callable[[], AsyncIterator[Never]]"  [arg-type]

Your Environment

• Mypy version used: 2.3.0 (compiled: yes)
• Mypy command-line flags: none (mypy out/cm.pyi); stub produced with stubgen -o out cm.py
• Mypy configuration options from mypy.ini (and other config files): none
• Python version used: 3.11.15

---

Additional notes

This is a change in behaviour from 1.15.0. That version's stubgen omitted the decorator entirely:

# stubgen 1.15.0
async def ctx() -> AsyncIterator[int]: ...

which is also lossy, but happens to type-check, so the problem only becomes visible on 2.3.0 once the decorator is preserved.

The synchronous case is unaffected — @contextmanager over def f() -> Iterator[T] round-trips through stubgen and type-checks on 2.3.0, because there is no async keyword to change how the return type is interpreted.

[selsky]

Bisected: this was introduced by 3ced11a, first released in 1.16.0. 1.15.0 is the last unaffected release.

Verified by running stubgen from a source checkout at each tag, on the cm.py from the report:

# stubgen v1.15.0
from collections.abc import AsyncIterator

async def ctx() -> AsyncIterator[int]: ...

# stubgen v1.16.0
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

@asynccontextmanager
async def ctx() -> AsyncIterator[int]: ...

and at the commit boundary:

revision	@asynccontextmanager emitted
ebafbcefa (3ced11a^)	no
3ced11a43	yes

1.15.0 dropped the decorator entirely, which is also lossy but happens to produce a stub that type-checks, so the problem only becomes visible from 1.16.0 onward.

#18489 added a catch-all branch to StubGenerator.process_decorator:

elif fullname in DATACLASS_TRANSFORM_NAMES:
    p = AliasPrinter(self)
    self._decorators.append(f"@{decorator.accept(p)}")
elif isinstance(decorator, (NameExpr, MemberExpr)):   # added by #18489
    p = AliasPrinter(self)
    self._decorators.append(f"@{decorator.accept(p)}")

Decorators are now copied through generically, after the specific handling for abstractmethod, overload, .setter/.deleter and dataclass_transform. There is no check for whether the resulting decorator/signature combination is valid in a stub, and @asynccontextmanager over async def is exactly the combination that isn't — format_func_def still passes is_async=is_coroutine regardless of which decorators were just emitted.

So the fix could be localised to the point where the two interact: suppress async when asynccontextmanager is among the decorators, which yields the spelling the typing docs sanction for stubs.

[A5rocks]

cc @cdce8p based on bisection above

[nightcityblade]

Hi, I'd like to work on this. I'll submit a focused PR with regression coverage shortly.