| from __future__ import absolute_import |
| # The default socket timeout, used by httplib to indicate that no timeout was |
| # specified by the user |
| from socket import _GLOBAL_DEFAULT_TIMEOUT |
| import time |
| |
| from ..exceptions import TimeoutStateError |
| |
| # A sentinel value to indicate that no timeout was specified by the user in |
| # urllib3 |
| _Default = object() |
| |
| |
| def current_time(): |
| """ |
| Retrieve the current time. This function is mocked out in unit testing. |
| """ |
| return time.time() |
| |
| |
| class Timeout(object): |
| """ Timeout configuration. |
| |
| Timeouts can be defined as a default for a pool:: |
| |
| timeout = Timeout(connect=2.0, read=7.0) |
| http = PoolManager(timeout=timeout) |
| response = http.request('GET', 'http://example.com/') |
| |
| Or per-request (which overrides the default for the pool):: |
| |
| response = http.request('GET', 'http://example.com/', timeout=Timeout(10)) |
| |
| Timeouts can be disabled by setting all the parameters to ``None``:: |
| |
| no_timeout = Timeout(connect=None, read=None) |
| response = http.request('GET', 'http://example.com/, timeout=no_timeout) |
| |
| |
| :param total: |
| This combines the connect and read timeouts into one; the read timeout |
| will be set to the time leftover from the connect attempt. In the |
| event that both a connect timeout and a total are specified, or a read |
| timeout and a total are specified, the shorter timeout will be applied. |
| |
| Defaults to None. |
| |
| :type total: integer, float, or None |
| |
| :param connect: |
| The maximum amount of time to wait for a connection attempt to a server |
| to succeed. Omitting the parameter will default the connect timeout to |
| the system default, probably `the global default timeout in socket.py |
| <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_. |
| None will set an infinite timeout for connection attempts. |
| |
| :type connect: integer, float, or None |
| |
| :param read: |
| The maximum amount of time to wait between consecutive |
| read operations for a response from the server. Omitting |
| the parameter will default the read timeout to the system |
| default, probably `the global default timeout in socket.py |
| <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_. |
| None will set an infinite timeout. |
| |
| :type read: integer, float, or None |
| |
| .. note:: |
| |
| Many factors can affect the total amount of time for urllib3 to return |
| an HTTP response. |
| |
| For example, Python's DNS resolver does not obey the timeout specified |
| on the socket. Other factors that can affect total request time include |
| high CPU load, high swap, the program running at a low priority level, |
| or other behaviors. |
| |
| In addition, the read and total timeouts only measure the time between |
| read operations on the socket connecting the client and the server, |
| not the total amount of time for the request to return a complete |
| response. For most requests, the timeout is raised because the server |
| has not sent the first byte in the specified time. This is not always |
| the case; if a server streams one byte every fifteen seconds, a timeout |
| of 20 seconds will not trigger, even though the request will take |
| several minutes to complete. |
| |
| If your goal is to cut off any request after a set amount of wall clock |
| time, consider having a second "watcher" thread to cut off a slow |
| request. |
| """ |
| |
| #: A sentinel object representing the default timeout value |
| DEFAULT_TIMEOUT = _GLOBAL_DEFAULT_TIMEOUT |
| |
| def __init__(self, total=None, connect=_Default, read=_Default): |
| self._connect = self._validate_timeout(connect, 'connect') |
| self._read = self._validate_timeout(read, 'read') |
| self.total = self._validate_timeout(total, 'total') |
| self._start_connect = None |
| |
| def __str__(self): |
| return '%s(connect=%r, read=%r, total=%r)' % ( |
| type(self).__name__, self._connect, self._read, self.total) |
| |
| @classmethod |
| def _validate_timeout(cls, value, name): |
| """ Check that a timeout attribute is valid. |
| |
| :param value: The timeout value to validate |
| :param name: The name of the timeout attribute to validate. This is |
| used to specify in error messages. |
| :return: The validated and casted version of the given value. |
| :raises ValueError: If the type is not an integer or a float, or if it |
| is a numeric value less than zero. |
| """ |
| if value is _Default: |
| return cls.DEFAULT_TIMEOUT |
| |
| if value is None or value is cls.DEFAULT_TIMEOUT: |
| return value |
| |
| try: |
| float(value) |
| except (TypeError, ValueError): |
| raise ValueError("Timeout value %s was %s, but it must be an " |
| "int or float." % (name, value)) |
| |
| try: |
| if value < 0: |
| raise ValueError("Attempted to set %s timeout to %s, but the " |
| "timeout cannot be set to a value less " |
| "than 0." % (name, value)) |
| except TypeError: # Python 3 |
| raise ValueError("Timeout value %s was %s, but it must be an " |
| "int or float." % (name, value)) |
| |
| return value |
| |
| @classmethod |
| def from_float(cls, timeout): |
| """ Create a new Timeout from a legacy timeout value. |
| |
| The timeout value used by httplib.py sets the same timeout on the |
| connect(), and recv() socket requests. This creates a :class:`Timeout` |
| object that sets the individual timeouts to the ``timeout`` value |
| passed to this function. |
| |
| :param timeout: The legacy timeout value. |
| :type timeout: integer, float, sentinel default object, or None |
| :return: Timeout object |
| :rtype: :class:`Timeout` |
| """ |
| return Timeout(read=timeout, connect=timeout) |
| |
| def clone(self): |
| """ Create a copy of the timeout object |
| |
| Timeout properties are stored per-pool but each request needs a fresh |
| Timeout object to ensure each one has its own start/stop configured. |
| |
| :return: a copy of the timeout object |
| :rtype: :class:`Timeout` |
| """ |
| # We can't use copy.deepcopy because that will also create a new object |
| # for _GLOBAL_DEFAULT_TIMEOUT, which socket.py uses as a sentinel to |
| # detect the user default. |
| return Timeout(connect=self._connect, read=self._read, |
| total=self.total) |
| |
| def start_connect(self): |
| """ Start the timeout clock, used during a connect() attempt |
| |
| :raises urllib3.exceptions.TimeoutStateError: if you attempt |
| to start a timer that has been started already. |
| """ |
| if self._start_connect is not None: |
| raise TimeoutStateError("Timeout timer has already been started.") |
| self._start_connect = current_time() |
| return self._start_connect |
| |
| def get_connect_duration(self): |
| """ Gets the time elapsed since the call to :meth:`start_connect`. |
| |
| :return: Elapsed time. |
| :rtype: float |
| :raises urllib3.exceptions.TimeoutStateError: if you attempt |
| to get duration for a timer that hasn't been started. |
| """ |
| if self._start_connect is None: |
| raise TimeoutStateError("Can't get connect duration for timer " |
| "that has not started.") |
| return current_time() - self._start_connect |
| |
| @property |
| def connect_timeout(self): |
| """ Get the value to use when setting a connection timeout. |
| |
| This will be a positive float or integer, the value None |
| (never timeout), or the default system timeout. |
| |
| :return: Connect timeout. |
| :rtype: int, float, :attr:`Timeout.DEFAULT_TIMEOUT` or None |
| """ |
| if self.total is None: |
| return self._connect |
| |
| if self._connect is None or self._connect is self.DEFAULT_TIMEOUT: |
| return self.total |
| |
| return min(self._connect, self.total) |
| |
| @property |
| def read_timeout(self): |
| """ Get the value for the read timeout. |
| |
| This assumes some time has elapsed in the connection timeout and |
| computes the read timeout appropriately. |
| |
| If self.total is set, the read timeout is dependent on the amount of |
| time taken by the connect timeout. If the connection time has not been |
| established, a :exc:`~urllib3.exceptions.TimeoutStateError` will be |
| raised. |
| |
| :return: Value to use for the read timeout. |
| :rtype: int, float, :attr:`Timeout.DEFAULT_TIMEOUT` or None |
| :raises urllib3.exceptions.TimeoutStateError: If :meth:`start_connect` |
| has not yet been called on this object. |
| """ |
| if (self.total is not None and |
| self.total is not self.DEFAULT_TIMEOUT and |
| self._read is not None and |
| self._read is not self.DEFAULT_TIMEOUT): |
| # In case the connect timeout has not yet been established. |
| if self._start_connect is None: |
| return self._read |
| return max(0, min(self.total - self.get_connect_duration(), |
| self._read)) |
| elif self.total is not None and self.total is not self.DEFAULT_TIMEOUT: |
| return max(0, self.total - self.get_connect_duration()) |
| else: |
| return self._read |
