Funktionierender Prototyp des Serious Games zur Vermittlung von Wissen zu Software-Engineering-Arbeitsmodellen.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

timeout.py 10KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279
  1. from __future__ import annotations
  2. import time
  3. import typing
  4. from enum import Enum
  5. from socket import getdefaulttimeout
  6. from ..exceptions import TimeoutStateError
  7. if typing.TYPE_CHECKING:
  8. from typing_extensions import Final
  9. class _TYPE_DEFAULT(Enum):
  10. # This value should never be passed to socket.settimeout() so for safety we use a -1.
  11. # socket.settimout() raises a ValueError for negative values.
  12. token = -1
  13. _DEFAULT_TIMEOUT: Final[_TYPE_DEFAULT] = _TYPE_DEFAULT.token
  14. _TYPE_TIMEOUT = typing.Optional[typing.Union[float, _TYPE_DEFAULT]]
  15. class Timeout:
  16. """Timeout configuration.
  17. Timeouts can be defined as a default for a pool:
  18. .. code-block:: python
  19. import urllib3
  20. timeout = urllib3.util.Timeout(connect=2.0, read=7.0)
  21. http = urllib3.PoolManager(timeout=timeout)
  22. resp = http.request("GET", "https://example.com/")
  23. print(resp.status)
  24. Or per-request (which overrides the default for the pool):
  25. .. code-block:: python
  26. response = http.request("GET", "https://example.com/", timeout=Timeout(10))
  27. Timeouts can be disabled by setting all the parameters to ``None``:
  28. .. code-block:: python
  29. no_timeout = Timeout(connect=None, read=None)
  30. response = http.request("GET", "https://example.com/", timeout=no_timeout)
  31. :param total:
  32. This combines the connect and read timeouts into one; the read timeout
  33. will be set to the time leftover from the connect attempt. In the
  34. event that both a connect timeout and a total are specified, or a read
  35. timeout and a total are specified, the shorter timeout will be applied.
  36. Defaults to None.
  37. :type total: int, float, or None
  38. :param connect:
  39. The maximum amount of time (in seconds) to wait for a connection
  40. attempt to a server to succeed. Omitting the parameter will default the
  41. connect timeout to the system default, probably `the global default
  42. timeout in socket.py
  43. <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.
  44. None will set an infinite timeout for connection attempts.
  45. :type connect: int, float, or None
  46. :param read:
  47. The maximum amount of time (in seconds) to wait between consecutive
  48. read operations for a response from the server. Omitting the parameter
  49. will default the read timeout to the system default, probably `the
  50. global default timeout in socket.py
  51. <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.
  52. None will set an infinite timeout.
  53. :type read: int, float, or None
  54. .. note::
  55. Many factors can affect the total amount of time for urllib3 to return
  56. an HTTP response.
  57. For example, Python's DNS resolver does not obey the timeout specified
  58. on the socket. Other factors that can affect total request time include
  59. high CPU load, high swap, the program running at a low priority level,
  60. or other behaviors.
  61. In addition, the read and total timeouts only measure the time between
  62. read operations on the socket connecting the client and the server,
  63. not the total amount of time for the request to return a complete
  64. response. For most requests, the timeout is raised because the server
  65. has not sent the first byte in the specified time. This is not always
  66. the case; if a server streams one byte every fifteen seconds, a timeout
  67. of 20 seconds will not trigger, even though the request will take
  68. several minutes to complete.
  69. If your goal is to cut off any request after a set amount of wall clock
  70. time, consider having a second "watcher" thread to cut off a slow
  71. request.
  72. """
  73. #: A sentinel object representing the default timeout value
  74. DEFAULT_TIMEOUT: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT
  75. def __init__(
  76. self,
  77. total: _TYPE_TIMEOUT = None,
  78. connect: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,
  79. read: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,
  80. ) -> None:
  81. self._connect = self._validate_timeout(connect, "connect")
  82. self._read = self._validate_timeout(read, "read")
  83. self.total = self._validate_timeout(total, "total")
  84. self._start_connect: float | None = None
  85. def __repr__(self) -> str:
  86. return f"{type(self).__name__}(connect={self._connect!r}, read={self._read!r}, total={self.total!r})"
  87. # __str__ provided for backwards compatibility
  88. __str__ = __repr__
  89. @staticmethod
  90. def resolve_default_timeout(timeout: _TYPE_TIMEOUT) -> float | None:
  91. return getdefaulttimeout() if timeout is _DEFAULT_TIMEOUT else timeout
  92. @classmethod
  93. def _validate_timeout(cls, value: _TYPE_TIMEOUT, name: str) -> _TYPE_TIMEOUT:
  94. """Check that a timeout attribute is valid.
  95. :param value: The timeout value to validate
  96. :param name: The name of the timeout attribute to validate. This is
  97. used to specify in error messages.
  98. :return: The validated and casted version of the given value.
  99. :raises ValueError: If it is a numeric value less than or equal to
  100. zero, or the type is not an integer, float, or None.
  101. """
  102. if value is None or value is _DEFAULT_TIMEOUT:
  103. return value
  104. if isinstance(value, bool):
  105. raise ValueError(
  106. "Timeout cannot be a boolean value. It must "
  107. "be an int, float or None."
  108. )
  109. try:
  110. float(value)
  111. except (TypeError, ValueError):
  112. raise ValueError(
  113. "Timeout value %s was %s, but it must be an "
  114. "int, float or None." % (name, value)
  115. ) from None
  116. try:
  117. if value <= 0:
  118. raise ValueError(
  119. "Attempted to set %s timeout to %s, but the "
  120. "timeout cannot be set to a value less "
  121. "than or equal to 0." % (name, value)
  122. )
  123. except TypeError:
  124. raise ValueError(
  125. "Timeout value %s was %s, but it must be an "
  126. "int, float or None." % (name, value)
  127. ) from None
  128. return value
  129. @classmethod
  130. def from_float(cls, timeout: _TYPE_TIMEOUT) -> Timeout:
  131. """Create a new Timeout from a legacy timeout value.
  132. The timeout value used by httplib.py sets the same timeout on the
  133. connect(), and recv() socket requests. This creates a :class:`Timeout`
  134. object that sets the individual timeouts to the ``timeout`` value
  135. passed to this function.
  136. :param timeout: The legacy timeout value.
  137. :type timeout: integer, float, :attr:`urllib3.util.Timeout.DEFAULT_TIMEOUT`, or None
  138. :return: Timeout object
  139. :rtype: :class:`Timeout`
  140. """
  141. return Timeout(read=timeout, connect=timeout)
  142. def clone(self) -> Timeout:
  143. """Create a copy of the timeout object
  144. Timeout properties are stored per-pool but each request needs a fresh
  145. Timeout object to ensure each one has its own start/stop configured.
  146. :return: a copy of the timeout object
  147. :rtype: :class:`Timeout`
  148. """
  149. # We can't use copy.deepcopy because that will also create a new object
  150. # for _GLOBAL_DEFAULT_TIMEOUT, which socket.py uses as a sentinel to
  151. # detect the user default.
  152. return Timeout(connect=self._connect, read=self._read, total=self.total)
  153. def start_connect(self) -> float:
  154. """Start the timeout clock, used during a connect() attempt
  155. :raises urllib3.exceptions.TimeoutStateError: if you attempt
  156. to start a timer that has been started already.
  157. """
  158. if self._start_connect is not None:
  159. raise TimeoutStateError("Timeout timer has already been started.")
  160. self._start_connect = time.monotonic()
  161. return self._start_connect
  162. def get_connect_duration(self) -> float:
  163. """Gets the time elapsed since the call to :meth:`start_connect`.
  164. :return: Elapsed time in seconds.
  165. :rtype: float
  166. :raises urllib3.exceptions.TimeoutStateError: if you attempt
  167. to get duration for a timer that hasn't been started.
  168. """
  169. if self._start_connect is None:
  170. raise TimeoutStateError(
  171. "Can't get connect duration for timer that has not started."
  172. )
  173. return time.monotonic() - self._start_connect
  174. @property
  175. def connect_timeout(self) -> _TYPE_TIMEOUT:
  176. """Get the value to use when setting a connection timeout.
  177. This will be a positive float or integer, the value None
  178. (never timeout), or the default system timeout.
  179. :return: Connect timeout.
  180. :rtype: int, float, :attr:`Timeout.DEFAULT_TIMEOUT` or None
  181. """
  182. if self.total is None:
  183. return self._connect
  184. if self._connect is None or self._connect is _DEFAULT_TIMEOUT:
  185. return self.total
  186. return min(self._connect, self.total) # type: ignore[type-var]
  187. @property
  188. def read_timeout(self) -> float | None:
  189. """Get the value for the read timeout.
  190. This assumes some time has elapsed in the connection timeout and
  191. computes the read timeout appropriately.
  192. If self.total is set, the read timeout is dependent on the amount of
  193. time taken by the connect timeout. If the connection time has not been
  194. established, a :exc:`~urllib3.exceptions.TimeoutStateError` will be
  195. raised.
  196. :return: Value to use for the read timeout.
  197. :rtype: int, float or None
  198. :raises urllib3.exceptions.TimeoutStateError: If :meth:`start_connect`
  199. has not yet been called on this object.
  200. """
  201. if (
  202. self.total is not None
  203. and self.total is not _DEFAULT_TIMEOUT
  204. and self._read is not None
  205. and self._read is not _DEFAULT_TIMEOUT
  206. ):
  207. # In case the connect timeout has not yet been established.
  208. if self._start_connect is None:
  209. return self._read
  210. return max(0, min(self.total - self.get_connect_duration(), self._read))
  211. elif self.total is not None and self.total is not _DEFAULT_TIMEOUT:
  212. return max(0, self.total - self.get_connect_duration())
  213. else:
  214. return self.resolve_default_timeout(self._read)