Repository navigation
Indicate that asyncio.timeout[at] should be preferred over asyncio.Timeout #142044
Description
Activity
I'd like to suggest a new name for the
Timeoutwhile keeping the old name as an soft deprecated alias.A soft deprecated API should not be used in new code,
but it is safe for already existing code to use it.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.Soft-deprecation would not help. The public API cannot be changed here. It will still be available as asyncio.Timeout.
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.
class asyncio.Timeout(when)
An asynchronous context manager for cancelling overdue coroutines
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.
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.
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).
Reacted by Bénédikt TranI am in favor of improving the docs, deprecating this would be painful so -1 on that.
- added a commit that references this issue
on Feb 7, 2026
asyncio.Timeoutis exported byasyncio.__all__and thus available when doingfrom asyncio import *. It is documented as the return type ofasyncio.timeout[at]. In #141401, it was suggested to rename that class to avoid possible typos when writingasyncio.timeoutHowever, I pointed several issues with that approach: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:
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.Linked PRs
asyncio.timeout[_at]overasyncio.Timeout#144449asyncio.timeout[_at]overasyncio.Timeout(GH-144449) #144565asyncio.timeout[_at]overasyncio.Timeout(GH-144449) #144566