Indicate that `asyncio.timeout[at]` should be preferred over `asyncio.Timeout`

[picnixz]

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 Timeout being used in type annotations, so the warning should be emitted at construction time. However we do not want that warning to be emitted when using asyncio.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 wanted async with asyncio.timeout instead. It's not our call to make but changing the docs first would give more weight to that decision on their side.

[xitop]

I'd like to suggest a new name for the Timeout while 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. Timeout will 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]

Soft-deprecation would not help. The public API cannot be changed here. It will still be available as asyncio.Timeout.

[xitop]

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

[picnixz]

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]

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]

I suppose the renaming has been suggested without necessarily having dvelve into the runtime implications but let's ask @gpshead

[gpshead]

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 = TheArtistFormerlyKnownAsTimeout in 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]

I am in favor of improving the docs, deprecating this would be painful so -1 on that.