Merge pull request #2187 from kevinburke/more-docs

Document Timeout behaviour

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
 
 
@@ -247,29 +249,11 @@ API Changes
       requests.get("http://example.org", proxies=proxies)
 
 
-Behavioral Changes
-~~~~~~~~~~~~~~~~~~
+Behavioural Changes
+~~~~~~~~~~~~~~~~~~~~~~~
 
 * Keys in the ``headers`` dictionary are now native strings on all Python
   versions, i.e. bytestrings on Python 2 and unicode on Python 3. If the
   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)
-

docs/community/support.rst

@@ -15,7 +15,7 @@ If your question is less than 140 characters, feel free to send a tweet to
 File an Issue
 -------------
 
-If you notice some unexpected behavior in Requests, or want to see support
+If you notice some unexpected behaviour in Requests, or want to see support
 for a new feature,
 `file an issue on GitHub <https://github.com/kennethreitz/requests/issues>`_.
 

docs/user/advanced.rst

@@ -194,7 +194,7 @@ Body Content Workflow
 ---------------------
 
 By default, when you make a request, the body of the response is downloaded
-immediately. You can override this behavior and defer downloading the response
+immediately. You can override this behaviour and defer downloading the response
 body until you access the :class:`Response.content <requests.Response.content>`
 attribute with the ``stream`` parameter::
 

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.

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.

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.
     """
 
 

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