diff --git a/docs/api.rst b/docs/api.rst index 69f138a2..7c5dae2e 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 @@ -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) - diff --git a/docs/community/support.rst b/docs/community/support.rst index a187a332..7f8c332d 100644 --- a/docs/community/support.rst +++ b/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 `_. diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 0de6b1b1..d50921d4 100644 --- a/docs/user/advanced.rst +++ b/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 ` attribute with the ``stream`` parameter:: diff --git a/requests/adapters.py b/requests/adapters.py index 3c1e979f..ed7a9072 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 01d853d5..57a91d55 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 6dbd98a9..d8f05f08 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 508b0ef2..334db58e 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