Document Timeout behaviour

diff --git a/docs/api.rst b/docs/api.rst
index 69f138a2829f18dc5cd6651612b1f6ae80e0d0b9..f1242ccbb8add397e122cdad957874142c43e6bf 100644 (file)
--- 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 3c1e979f14788ee3acb7fc65c504bc13e1c86963..ed7a907262b7bf1c508e4a05b53a78dcf3f68163 100644 (file)
--- a/requests/adapters.py
+++ b/requests/adapters.py
@@ -316,8 +316,10 @@ class HTTPAdapter(BaseAdapter):
 
         :param request: The :class:`PreparedRequest <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 <user/advanced.html#timeouts>`_) 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 01d853d5cae6fd270027f19407eae3d266fd38d7..57a91d5591dfa357758016697fa2c947f6b336c1 100644 (file)
--- 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
+        <user/advanced.html#timeouts>`_) 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 6dbd98a931c18cb77884f91bc2303701c16891e2..d8f05f0817b6048bcd5e8e3a73e80eedf6e27d5b 100644 (file)
--- 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 508b0ef29af4514db4383e6dc36a9bf56cf27c3e..334db58eb14db9a19a4c435676aa9a1687781578 100644 (file)
--- 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 <user/advanced.html#timeouts>`_) 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