Repository navigation
Rename asyncio.Timeout to be unlike asyncio.timeout #141401
Description
Activity
What do you propose as the new name?
The old name would need deprecating.
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.Maybe
TimeoutAt?TimeoutAtisn'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.TimeoutManagerseems fine.I agree with TimeoutManger
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? orasyncio.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.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.
Reacted by Bénédikt TranIf 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.timeoutthat uses absolute time isasyncio.timeout_at, i.e. not theasyncio.Timeout. Theasyncio.Timeoutis introduced in the docs by the last paragraph ofasyncio.timeout: The context manager produced by asyncio.timeout() can be rescheduled ....but do we have
asyncio.taskGroup?The
TaskGroupexample 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.3 remaining items
I personally would leave it as is. Deprecation is really a long and annoying process. What I suggested is not making the name private by the way. What I meant is to not expose it in the docs and only say that the CM return an object which has the "following methods".
People would still be able to use it at runtime but the docs wouldn't mention it. It's unfortunate but this also means that anyone doing
from asyncio import *should not be broken by the fact that we deprecateTimeout(it's exposed intimeout.py::__all__and then later re-exported toasyncio).Now, what I do not want to see:
from asyncio import *raising DeprecationWarning because of a deprecated name. If we provide an__all__, then it was meant for it to be*-importable IMO.from asyncio import Timeoutorfrom asyncio.timeout import Timeoutshould still be entirely correct. I didn't think about it before but users that want to type their code may want to keep that class, whether it's its interface or its name. So even my proposal would need to be amended in favor of a simple docs emphasis about "prefer using the CM directly" rather than "do not use it".
The best course of action would be to leave it to the linters, so that
asyncio.Timeoutis not used explicitly. So I'm willing to adding a recommendation in the docs, but leave the runtime as is.@picnixz, I'm confused by your replies:
"would rather make it private"
"What I suggested is not making the name private by the way."
Just editing the docs cannot solve the problem when somebody types a 'T' instead of the 't'.
I understand that the question is if doing the renaming process is worth the effort. I don't know the answer.
About my reply: that's before I actually saw that it's part of the public API. I should have been clearer.
Just editing the docs cannot solve the problem when somebody types a 'T' instead of the 't'.
Yes but we cannot also help them more without penalizing others. I'm sorry, but the best we can do is simply change the docs so that the linters could take this as a sign that a new rule could be added.
I understand that the question is if doing the renaming process is worth the effort. I don't know the answer.
For me, it's a clear no. Deprecation requires at least 5 years. And as I said, it's not that trivial. It breaks code that would rely just on the class name for typing purposes and it would break code that does
from asyncio import *. It's also breaking the contract about a public API. We don't want to make it deprecated and have everyone else getting warnings because of the change, so we likely need to make it so that the warning is raised at construction time. But we don't want that warning to be raised if the caller isasyncio.timeout[at].I will recategorize this issue as a doc issue. We can simply indicate in the docs that the interface is documented and can be used but users should instead use
timeoutandtimeout_at. From a usage ratio, I think there are as many people making that typo than users using it, but there are likely more users doingfrom asyncio import *in their everyday's script (what is costly is the wrapper implementation just to avoid a warning when doingfrom asyncio import *or other solutions).Or maybe better, let's close this issue as the discussion could be reopened and let's create a separate issue.
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):
It is very easy to make an error and write the upper-case
Timeoutby mistake. For instance we already have the upper-caseTaskGroupasync CM.Using
timeoutcreates aTimeoutobject. BecauseTimeoutis 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