Debian Codegraph @

Lib/asyncio/timeouts.py

raw
1 import enum
2
3 from types import TracebackType
4
5 from . import events
6 from . import exceptions
7 from . import tasks
8
9
10 __all__ = (
11 "Timeout",
12 "timeout",
13 "timeout_at",
14 )
15
16
17 class _State(enum.Enum):
18 CREATED = "created"
19 ENTERED = "active"
20 EXPIRING = "expiring"
21 EXPIRED = "expired"
22 EXITED = "finished"
23
24
25 class Timeout:
26 """Asynchronous context manager for cancelling overdue coroutines.
27
28 Use `timeout()` or `timeout_at()` rather than instantiating this class
29 directly.
30 """
31
32 def __init__(self, when: float | None) -> None:
33 """Schedule a timeout that will trigger at a given loop time.
34
35 - If `when` is `None`, the timeout will never trigger.
36 - If `when < loop.time()`, the timeout will trigger on the next
37 iteration of the event loop.
38 """
39 self._state = _State.CREATED
40
41 self._timeout_handler: events.TimerHandle | None = None
42 self._task: tasks.Task | None = None
43 self._when = when
44
45 def when(self) -> float | None:
46 """Return the current deadline."""
47 return self._when
48
49 def reschedule(self, when: float | None) -> None:
50 """Reschedule the timeout."""
51 if self._state is not _State.ENTERED:
52 if self._state is _State.CREATED:
53 raise RuntimeError("Timeout has not been entered")
54 raise RuntimeError(
55 f"Cannot change state of {self._state.value} Timeout",
56 )
57
58 self._when = when
59
60 if self._timeout_handler is not None:
61 self._timeout_handler.cancel()
62
63 if when is None:
64 self._timeout_handler = None
65 else:
66 loop = events.get_running_loop()
67 if when <= loop.time():
68 self._timeout_handler = loop.call_soon(self._on_timeout)
69 else:
70 self._timeout_handler = loop.call_at(when, self._on_timeout)
71
72 def expired(self) -> bool:
73 """Is timeout expired during execution?"""
74 return self._state in (_State.EXPIRING, _State.EXPIRED)
75
76 def __repr__(self) -> str:
77 info = ['']
78 if self._state is _State.ENTERED:
79 when = round(self._when, 3) if self._when is not None else None
80 info.append(f"when={when}")
81 info_str = ' '.join(info)
82 return f"<Timeout [{self._state.value}]{info_str}>"
83
84 async def __aenter__(self) -> "Timeout":
85 if self._state is not _State.CREATED:
86 raise RuntimeError("Timeout has already been entered")
87 task = tasks.current_task()
88 if task is None:
89 raise RuntimeError("Timeout should be used inside a task")
90 self._state = _State.ENTERED
91 self._task = task
92 self._cancelling = self._task.cancelling()
93 self.reschedule(self._when)
94 return self
95
96 async def __aexit__(
97 self,
98 exc_type: type[BaseException] | None,
99 exc_val: BaseException | None,
100 exc_tb: TracebackType | None,
101 ) -> bool | None:
102 assert self._state in (_State.ENTERED, _State.EXPIRING)
103
104 if self._timeout_handler is not None:
105 self._timeout_handler.cancel()
106 self._timeout_handler = None
107
108 if self._state is _State.EXPIRING:
109 self._state = _State.EXPIRED
110
111 if self._task.uncancel() <= self._cancelling and exc_type is not None:
112 # Since there are no new cancel requests, we're
113 # handling this.
114 if issubclass(exc_type, exceptions.CancelledError):
115 raise TimeoutError from exc_val
116 elif exc_val is not None:
117 self._insert_timeout_error(exc_val)
118 if isinstance(exc_val, ExceptionGroup):
119 for exc in exc_val.exceptions:
120 self._insert_timeout_error(exc)
121 elif self._state is _State.ENTERED:
122 self._state = _State.EXITED
123
124 return None
125
126 def _on_timeout(self) -> None:
127 assert self._state is _State.ENTERED
128 self._task.cancel()
129 self._state = _State.EXPIRING
130 # drop the reference early
131 self._timeout_handler = None
132
133 @staticmethod
134 def _insert_timeout_error(exc_val: BaseException) -> None:
135 while exc_val.__context__ is not None:
136 if isinstance(exc_val.__context__, exceptions.CancelledError):
137 te = TimeoutError()
138 te.__context__ = te.__cause__ = exc_val.__context__
139 exc_val.__context__ = te
140 break
141 exc_val = exc_val.__context__
142
143
144 def timeout(delay: float | None) -> Timeout:
145 """Timeout async context manager.
146
147 Useful in cases when you want to apply timeout logic around block
148 of code or in cases when asyncio.wait_for is not suitable. For example:
149
150 >>> async with asyncio.timeout(10): # 10 seconds timeout
151 ... await long_running_task()
152
153
154 delay - value in seconds or None to disable timeout logic
155
156 long_running_task() is interrupted by raising asyncio.CancelledError,
157 the top-most affected timeout() context manager converts CancelledError
158 into TimeoutError.
159 """
160 loop = events.get_running_loop()
161 return Timeout(loop.time() + delay if delay is not None else None)
162
163
164 def timeout_at(when: float | None) -> Timeout:
165 """Schedule the timeout at absolute time.
166
167 Like timeout() but argument gives absolute time in the same clock system
168 as loop.time().
169
170 Please note: it is not POSIX time but a time with
171 undefined starting base, e.g. the time of the system power on.
172
173 >>> async with asyncio.timeout_at(loop.time() + 10):
174 ... await long_running_task()
175
176
177 when - a deadline when timeout occurs or None to disable timeout logic
178
179 long_running_task() is interrupted by raising asyncio.CancelledError,
180 the top-most affected timeout() context manager converts CancelledError
181 into TimeoutError.
182 """
183 return Timeout(when)