Indicate that asyncio.timeout[at] should be preferred over asyncio.Timeout #142044
Description
asyncio.Timeout is exported by asyncio.__all__ and thus available when doing from asyncio import *. It is documented as the return type of asyncio.timeout[at]. In #141401, it was suggested to rename that class to avoid possible typos when writing asyncio.timeout However, I pointed several issues with that approach:
- We cannot change a public API without a deprecation period.
- Making it deprecated is painful. We need to support
Timeoutbeing used in type annotations, so the warning should be emitted at construction time. However we do not want that warning to be emitted when usingasyncio.timeout[at]. Alternatively we could have two different classes or make other hacks, but AFAICT, this would rather seem like an ugly hack that I would like to avoid.
IMOM, the best course of action is:
- Improve the docs to indicate that the class exists, the interface exists, but that it should not be instantiated directly. It can however be used in type annotations or users could decide to subclass the class to provide an improved interface for their own needs.
- Add a rule to linters so that any usage of
async with asyncio.Timeout(...)is flagged and that the user likely wantedasync with asyncio.timeoutinstead. It's not our call to make but changing the docs first would give more weight to that decision on their side.
Activity
xitop commentedon Nov 29, 2025
I'd like to suggest a new name for the
Timeoutwhile keeping the old name as an soft deprecated alias.This suggestion addresses the feedback from #141401 (now closed)
The context manager class will be
TimeoutManager.Timeoutwill be an alias (Timeout = TimeoutManager). The documentation will contain the new name. A short note about the old name being soft deprecated (with a link to the glossary) will be added to the docs.picnixz commentedon Nov 29, 2025
Soft-deprecation would not help. The public API cannot be changed here. It will still be available as asyncio.Timeout.
xitop commentedon Nov 29, 2025
It is only mitigation measure. It will prevent that someone just wanting to refresh his memory (T... or t... ?) and briefly scans the docs will find the incorrect class.
picnixz commentedon Nov 29, 2025
I am against this change and we usually leave this work to linters. Please do try to understand that not everyone will make a mistake.
xitop commentedon Nov 29, 2025
It's not just about me. This topic had a quite positive reaction on Discourse. The renaming was suggested by a Steering Council member. I filed the issue also on behalf of these people.
picnixz commentedon Nov 29, 2025
I suppose the renaming has been suggested without necessarily having dvelve into the runtime implications but let's ask @gpshead
gpshead commentedon Nov 29, 2025
Running the actual deprecation of the name on this one will take 5+ years. I'm not sure it is worthwhile, but if you want to start the ball rolling on that - rename Timeout to something more appropriate and put a
Timeout = TheArtistFormerlyKnownAsTimeoutin place today so that a preferred name is made available. That way there is a nicer name in place but the old name still works fine. You'd want to document them as equal and recommend people writing code only for use on 3.15+ prefer the new name.Even without that renaming dance to start the possibility of a future deprecation of the old name, the best thing to do regardless is improving the documentation today (and linters like ruff check, flake8, and pylint).
kumaraditya303 commentedon Dec 10, 2025
I am in favor of improving the docs, deprecating this would be painful so -1 on that.
gh-142044: Add note to prefer `asyncio.timeout[_at]` over `asyncio.Ti…
pythongh-142044: Add note to prefer `asyncio.timeout[_at]` over `asyn…
pythongh-142044: Add note to prefer `asyncio.timeout[_at]` over `asyn…
[3.14] gh-142044: Add note to prefer `asyncio.timeout[_at]` over `asy…
[3.13] gh-142044: Add note to prefer `asyncio.timeout[_at]` over `asy…
pythongh-142044: Add note to prefer `asyncio.timeout[_at]` over `asyn…
pythongh-142044: Add note to prefer `asyncio.timeout[_at]` over `asyn…