``asyncio.{timeout_at,timeout}`` are incorrectly documented as ``coroutine``

[graingert]

Documentation

asyncio.timeout_at and asyncio.timeout are documented as coroutine but they are synchronous functions that return async context managers.

Linked PRs

• gh-107980: fix doc role for asyncio.timeouts #108126
• [3.12] gh-107980: fix doc role for asyncio.timeouts (GH-108126) #108152
• [3.11] gh-107980: fix doc role for asyncio.timeouts (GH-108126) #108153

[gvanrossum]

@Tinche I think you wrote those docs originally -- maybe you can help fix them too?

[Tinche]

Sure, I can take this.

I must've stuck on the coroutinefunction role on there as closest that sounded right. But you're right, these aren't coroutine functions, they're really async context managers, or technically async context manager factories I guess.

I can just convert these to functions, or would adding a new role for async context managers be a better play? I see these roles are defined in https://github.com/python/cpython/blob/main/Doc/tools/extensions/pyspecific.py, might not be too hard adding a new one. As far as I can tell, there are only a few async context managers in the stdlib currently: TaskGroup and Timeout, AsyncExitStack and aclosing. Maybe they'd benefit from a documentation prefix similar to the current coroutine.

[AA-Turner]

a new role for async context managers be a better play

There isn't currently a role for context managers, note that the contextlib context managers are generally marked up as functions. Perhaps the analogous position would be mark timeout as an async function?

A

[graingert]

Perhaps the analogous position would be mark timeout as an async function?

timeout is not an async function, it's a synchronous function that returns an instance of asyncio.Timeout