Rename asyncio.Timeout to be unlike asyncio.timeout

[xitop]

Feature or enhancement

Proposal:

This renaming was proposed on Discourse as a solution for the annoyance that two very similar names exist and both can be used in the same statement without any error, because both are async context managers (CM):

async with asyncio.timeout(99): await ...  # timeout is using relative time as expected
async with asyncio.Timeout(99): await ...  # Timeout is using loop clock absolute time;
                                           # small values are already in the past,
                                           # so it cancels immediately

It is very easy to make an error and write the upper-case Timeout by mistake. For instance we already have the upper-case TaskGroup async CM.

Using timeout creates a Timeout object. Because Timeout is not intended to be used directly, giving it a new name and deprecating the old one was suggested in the linked Discourse thread.

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

https://discuss.python.org/t/error-prone-naming-asyncio-timeout-vs-asyncio-timeout/104727

[hugovk]

What do you propose as the new name?

The old name would need deprecating.

[xitop]

I'm leaving the choice of a new name to Python developers and native speakers.

But if we need something to start with, maybe a TimeoutManager.

[nineteendo]

Maybe TimeoutAt?

[mikeshardmind]

TimeoutAt isn't really correct for what this is. The absolute loop time in the initialization is only for the initial timeout, the main reason both exist, as well as another function that is a context manager with an absolute loop time, is that this form is reschedulable.

TimeoutManager seems fine.

[sharktide]

I agree with TimeoutManger

[picnixz]

Using timeout creates a Timeout object. Because Timeout is not intended to be used directly, giving it a new name and deprecating the old one was suggested in the linked Discourse thread.

It is documented: https://docs.python.org/3/library/asyncio-task.html#asyncio.Timeout. So yes it can be used directly and shouldn't be deprecated (if we want it to be deprecated, I would rather make it private and only indicate the methods that are present on the returned CM instead of exposing the name)

For instance we already have the upper-case TaskGroup async CM.

but do we have asyncio.taskGroup? or asyncio.Taskgroup? I don't think we should change this honestly. Sure, it's a bit annoying to make an error but this is not something to change IMO.

[mikeshardmind]

This does also strike me as something a linter could catch., which might be a more productive way to ensure fewer users make this mistake. If you use asyncio.Timeout with a literal timeout, rather than a computed value, it's pretty likely you meant asyncio.timeout.

[xitop]

If you use asyncio.Timeout with a literal timeout, rather than a computed value, it's pretty likely you meant asyncio.timeout.

According to the documentation, the counterpart of asyncio.timeout that uses absolute time is asyncio.timeout_at, i.e. not the asyncio.Timeout. The asyncio.Timeout is introduced in the docs by the last paragraph of asyncio.timeout: The context manager produced by asyncio.timeout() can be rescheduled ....

[xitop]

but do we have asyncio.taskGroup?

The TaskGroup example only shows that there is no consistency for asyncio context manager names. Some are CamelCase and some are lowercase. That increases odds of making a mistake.