From: Kevin Burke Date: Fri, 29 Aug 2014 18:33:46 +0000 (-0700) Subject: Document Timeout behaviour X-Git-Tag: v2.4.1~7^2~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=dfa41afd43a15222eb7a2db35feadd36dba4b445;p=services%2Fpython-requests.git Document Timeout behaviour --- diff --git a/docs/api.rst b/docs/api.rst index 69f138a..f1242cc 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -60,6 +60,8 @@ Exceptions .. autoexception:: requests.exceptions.HTTPError .. autoexception:: requests.exceptions.URLRequired .. autoexception:: requests.exceptions.TooManyRedirects +.. autoexception:: requests.exceptions.ConnectTimeout +.. autoexception:: requests.exceptions.ReadTimeout .. autoexception:: requests.exceptions.Timeout @@ -255,21 +257,3 @@ Behavioral Changes keys are not native strings (unicode on Python2 or bytestrings on Python 3) they will be converted to the native string type assuming UTF-8 encoding. -* Timeouts behave slightly differently. On streaming requests, the timeout - only applies to the connection attempt. On regular requests, the timeout - is applied to the connection process and on to all attempts to read data from - the underlying socket. It does *not* apply to the total download time for the - request. - - :: - - tarball_url = 'https://github.com/kennethreitz/requests/tarball/master' - - # One second timeout for the connection attempt - # Unlimited time to download the tarball - r = requests.get(tarball_url, stream=True, timeout=1) - - # One second timeout for the connection attempt - # Another full second timeout to download the tarball - r = requests.get(tarball_url, timeout=1) - diff --git a/requests/adapters.py b/requests/adapters.py index 3c1e979..ed7a907 100644 --- a/requests/adapters.py +++ b/requests/adapters.py @@ -316,8 +316,10 @@ class HTTPAdapter(BaseAdapter): :param request: The :class:`PreparedRequest ` being sent. :param stream: (optional) Whether to stream the request content. - :param timeout: (optional) The timeout on the request. - :type timeout: float or tuple (connect timeout, read timeout), eg (3.1, 20) + :param timeout: (optional) How long to wait for the server to send + data before giving up, as a float, or a (`connect timeout, read + timeout `_) tuple. + :type timeout: float or tuple :param verify: (optional) Whether to verify SSL certificates. :param cert: (optional) Any user-provided SSL certificate to be trusted. :param proxies: (optional) The proxies dictionary to apply to the request. diff --git a/requests/api.py b/requests/api.py index 01d853d..57a91d5 100644 --- a/requests/api.py +++ b/requests/api.py @@ -24,10 +24,14 @@ def request(method, url, **kwargs): :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`. :param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`. :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`. - :param files: (optional) Dictionary of 'name': file-like-objects (or {'name': ('filename', fileobj)}) for multipart encoding upload. + :param files: (optional) Dictionary of ``'name': file-like-objects`` (or ``{'name': ('filename', fileobj)}``) for multipart encoding upload. :param auth: (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth. - :param timeout: (optional) Float describing the timeout of the request in seconds. + :param timeout: (optional) How long to wait for the server to send data + before giving up, as a float, or a (`connect timeout, read timeout + `_) tuple. + :type timeout: float or tuple :param allow_redirects: (optional) Boolean. Set to True if POST/PUT/DELETE redirect following is allowed. + :type allow_redirects: bool :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy. :param verify: (optional) if ``True``, the SSL cert will be verified. A CA_BUNDLE path can also be provided. :param stream: (optional) if ``False``, the response content will be immediately downloaded. diff --git a/requests/exceptions.py b/requests/exceptions.py index 6dbd98a..d8f05f0 100644 --- a/requests/exceptions.py +++ b/requests/exceptions.py @@ -46,15 +46,16 @@ class SSLError(ConnectionError): class Timeout(RequestException): """The request timed out. - Catching this error will catch both :exc:`ConnectTimeout` and - :exc:`ReadTimeout` errors. + Catching this error will catch both + :exc:`~requests.exceptions.ConnectTimeout` and + :exc:`~requests.exceptions.ReadTimeout` errors. """ class ConnectTimeout(ConnectionError, Timeout): - """The request timed out while trying to connect to the server. + """The request timed out while trying to connect to the remote server. - Requests that produce this error are safe to retry + Requests that produced this error are safe to retry. """ diff --git a/requests/sessions.py b/requests/sessions.py index 508b0ef..334db58 100644 --- a/requests/sessions.py +++ b/requests/sessions.py @@ -400,13 +400,16 @@ class Session(SessionRedirectMixin): :class:`Request`. :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`. - :param files: (optional) Dictionary of 'filename': file-like-objects + :param files: (optional) Dictionary of ``'filename': file-like-objects`` for multipart encoding upload. :param auth: (optional) Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth. - :param timeout: (optional) Float describing the timeout of the - request in seconds. - :param allow_redirects: (optional) Boolean. Set to True by default. + :param timeout: (optional) How long to wait for the server to send + data before giving up, as a float, or a (`connect timeout, read + timeout `_) tuple. + :type timeout: float or tuple + :param allow_redirects: (optional) Set to True by default. + :type allow_redirects: bool :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy. :param stream: (optional) whether to immediately download the response