Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/urllib3/util/timeout.py: 41%
71 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-08 06:05 +0000
1from __future__ import annotations
3import time
4import typing
5from enum import Enum
6from socket import getdefaulttimeout
8from ..exceptions import TimeoutStateError
10if typing.TYPE_CHECKING:
11 from typing import Final
14class _TYPE_DEFAULT(Enum):
15 # This value should never be passed to socket.settimeout() so for safety we use a -1.
16 # socket.settimout() raises a ValueError for negative values.
17 token = -1
20_DEFAULT_TIMEOUT: Final[_TYPE_DEFAULT] = _TYPE_DEFAULT.token
22_TYPE_TIMEOUT = typing.Optional[typing.Union[float, _TYPE_DEFAULT]]
25class Timeout:
26 """Timeout configuration.
28 Timeouts can be defined as a default for a pool:
30 .. code-block:: python
32 import urllib3
34 timeout = urllib3.util.Timeout(connect=2.0, read=7.0)
36 http = urllib3.PoolManager(timeout=timeout)
38 resp = http.request("GET", "https://example.com/")
40 print(resp.status)
42 Or per-request (which overrides the default for the pool):
44 .. code-block:: python
46 response = http.request("GET", "https://example.com/", timeout=Timeout(10))
48 Timeouts can be disabled by setting all the parameters to ``None``:
50 .. code-block:: python
52 no_timeout = Timeout(connect=None, read=None)
53 response = http.request("GET", "https://example.com/", timeout=no_timeout)
56 :param total:
57 This combines the connect and read timeouts into one; the read timeout
58 will be set to the time leftover from the connect attempt. In the
59 event that both a connect timeout and a total are specified, or a read
60 timeout and a total are specified, the shorter timeout will be applied.
62 Defaults to None.
64 :type total: int, float, or None
66 :param connect:
67 The maximum amount of time (in seconds) to wait for a connection
68 attempt to a server to succeed. Omitting the parameter will default the
69 connect timeout to the system default, probably `the global default
70 timeout in socket.py
71 <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.
72 None will set an infinite timeout for connection attempts.
74 :type connect: int, float, or None
76 :param read:
77 The maximum amount of time (in seconds) to wait between consecutive
78 read operations for a response from the server. Omitting the parameter
79 will default the read timeout to the system default, probably `the
80 global default timeout in socket.py
81 <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.
82 None will set an infinite timeout.
84 :type read: int, float, or None
86 .. note::
88 Many factors can affect the total amount of time for urllib3 to return
89 an HTTP response.
91 For example, Python's DNS resolver does not obey the timeout specified
92 on the socket. Other factors that can affect total request time include
93 high CPU load, high swap, the program running at a low priority level,
94 or other behaviors.
96 In addition, the read and total timeouts only measure the time between
97 read operations on the socket connecting the client and the server,
98 not the total amount of time for the request to return a complete
99 response. For most requests, the timeout is raised because the server
100 has not sent the first byte in the specified time. This is not always
101 the case; if a server streams one byte every fifteen seconds, a timeout
102 of 20 seconds will not trigger, even though the request will take
103 several minutes to complete.
105 If your goal is to cut off any request after a set amount of wall clock
106 time, consider having a second "watcher" thread to cut off a slow
107 request.
108 """
110 #: A sentinel object representing the default timeout value
111 DEFAULT_TIMEOUT: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT
113 def __init__(
114 self,
115 total: _TYPE_TIMEOUT = None,
116 connect: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,
117 read: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,
118 ) -> None:
119 self._connect = self._validate_timeout(connect, "connect")
120 self._read = self._validate_timeout(read, "read")
121 self.total = self._validate_timeout(total, "total")
122 self._start_connect: float | None = None
124 def __repr__(self) -> str:
125 return f"{type(self).__name__}(connect={self._connect!r}, read={self._read!r}, total={self.total!r})"
127 # __str__ provided for backwards compatibility
128 __str__ = __repr__
130 @staticmethod
131 def resolve_default_timeout(timeout: _TYPE_TIMEOUT) -> float | None:
132 return getdefaulttimeout() if timeout is _DEFAULT_TIMEOUT else timeout
134 @classmethod
135 def _validate_timeout(cls, value: _TYPE_TIMEOUT, name: str) -> _TYPE_TIMEOUT:
136 """Check that a timeout attribute is valid.
138 :param value: The timeout value to validate
139 :param name: The name of the timeout attribute to validate. This is
140 used to specify in error messages.
141 :return: The validated and casted version of the given value.
142 :raises ValueError: If it is a numeric value less than or equal to
143 zero, or the type is not an integer, float, or None.
144 """
145 if value is None or value is _DEFAULT_TIMEOUT:
146 return value
148 if isinstance(value, bool):
149 raise ValueError(
150 "Timeout cannot be a boolean value. It must "
151 "be an int, float or None."
152 )
153 try:
154 float(value)
155 except (TypeError, ValueError):
156 raise ValueError(
157 "Timeout value %s was %s, but it must be an "
158 "int, float or None." % (name, value)
159 ) from None
161 try:
162 if value <= 0:
163 raise ValueError(
164 "Attempted to set %s timeout to %s, but the "
165 "timeout cannot be set to a value less "
166 "than or equal to 0." % (name, value)
167 )
168 except TypeError:
169 raise ValueError(
170 "Timeout value %s was %s, but it must be an "
171 "int, float or None." % (name, value)
172 ) from None
174 return value
176 @classmethod
177 def from_float(cls, timeout: _TYPE_TIMEOUT) -> Timeout:
178 """Create a new Timeout from a legacy timeout value.
180 The timeout value used by httplib.py sets the same timeout on the
181 connect(), and recv() socket requests. This creates a :class:`Timeout`
182 object that sets the individual timeouts to the ``timeout`` value
183 passed to this function.
185 :param timeout: The legacy timeout value.
186 :type timeout: integer, float, :attr:`urllib3.util.Timeout.DEFAULT_TIMEOUT`, or None
187 :return: Timeout object
188 :rtype: :class:`Timeout`
189 """
190 return Timeout(read=timeout, connect=timeout)
192 def clone(self) -> Timeout:
193 """Create a copy of the timeout object
195 Timeout properties are stored per-pool but each request needs a fresh
196 Timeout object to ensure each one has its own start/stop configured.
198 :return: a copy of the timeout object
199 :rtype: :class:`Timeout`
200 """
201 # We can't use copy.deepcopy because that will also create a new object
202 # for _GLOBAL_DEFAULT_TIMEOUT, which socket.py uses as a sentinel to
203 # detect the user default.
204 return Timeout(connect=self._connect, read=self._read, total=self.total)
206 def start_connect(self) -> float:
207 """Start the timeout clock, used during a connect() attempt
209 :raises urllib3.exceptions.TimeoutStateError: if you attempt
210 to start a timer that has been started already.
211 """
212 if self._start_connect is not None:
213 raise TimeoutStateError("Timeout timer has already been started.")
214 self._start_connect = time.monotonic()
215 return self._start_connect
217 def get_connect_duration(self) -> float:
218 """Gets the time elapsed since the call to :meth:`start_connect`.
220 :return: Elapsed time in seconds.
221 :rtype: float
222 :raises urllib3.exceptions.TimeoutStateError: if you attempt
223 to get duration for a timer that hasn't been started.
224 """
225 if self._start_connect is None:
226 raise TimeoutStateError(
227 "Can't get connect duration for timer that has not started."
228 )
229 return time.monotonic() - self._start_connect
231 @property
232 def connect_timeout(self) -> _TYPE_TIMEOUT:
233 """Get the value to use when setting a connection timeout.
235 This will be a positive float or integer, the value None
236 (never timeout), or the default system timeout.
238 :return: Connect timeout.
239 :rtype: int, float, :attr:`Timeout.DEFAULT_TIMEOUT` or None
240 """
241 if self.total is None:
242 return self._connect
244 if self._connect is None or self._connect is _DEFAULT_TIMEOUT:
245 return self.total
247 return min(self._connect, self.total) # type: ignore[type-var]
249 @property
250 def read_timeout(self) -> float | None:
251 """Get the value for the read timeout.
253 This assumes some time has elapsed in the connection timeout and
254 computes the read timeout appropriately.
256 If self.total is set, the read timeout is dependent on the amount of
257 time taken by the connect timeout. If the connection time has not been
258 established, a :exc:`~urllib3.exceptions.TimeoutStateError` will be
259 raised.
261 :return: Value to use for the read timeout.
262 :rtype: int, float or None
263 :raises urllib3.exceptions.TimeoutStateError: If :meth:`start_connect`
264 has not yet been called on this object.
265 """
266 if (
267 self.total is not None
268 and self.total is not _DEFAULT_TIMEOUT
269 and self._read is not None
270 and self._read is not _DEFAULT_TIMEOUT
271 ):
272 # In case the connect timeout has not yet been established.
273 if self._start_connect is None:
274 return self._read
275 return max(0, min(self.total - self.get_connect_duration(), self._read))
276 elif self.total is not None and self.total is not _DEFAULT_TIMEOUT:
277 return max(0, self.total - self.get_connect_duration())
278 else:
279 return self.resolve_default_timeout(self._read)