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.

242 lines
9.5 KiB

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