From cdbc2e271529f467b278b2760f12ee0b5d6930d3 Mon Sep 17 00:00:00 2001 From: Matthew Armand Date: Mon, 3 Jul 2023 16:38:22 -0400 Subject: [PATCH] Add an Example for automatic retries to the Advanced Usage docs (#6258) - While Requests doesn't automatically retry failures, this ability is a very common advanced use case in real world applications. - Although there's a mention of this ability on the HTTPAdapter class docs, it's a bit buried and not very specific. - It makes sense then to have an Example in the HTTPAdapter section of the Advanced Usage docs with a basic template for how this can be accomplished with Requests. --- docs/user/advanced.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index c664a83d30..055c88a956 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -1026,8 +1026,30 @@ library to use SSLv3:: num_pools=connections, maxsize=maxsize, block=block, ssl_version=ssl.PROTOCOL_SSLv3) +Example: Automatic Retries +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, Requests does not retry failed connections. However, it is possible +to implement automatic retries with a powerful array of features, including +backoff, within a Requests :class:`Session ` using the +`urllib3.util.Retry`_ class:: + + from urllib3.util import Retry + from requests import Session + from requests.adapters import HTTPAdapter + + s = Session() + retries = Retry( + total=3, + backoff_factor=0.1, + status_forcelist=[502, 503, 504], + allowed_methods={'POST'}, + ) + s.mount('https://', HTTPAdapter(max_retries=retries)) + .. _`described here`: https://kenreitz.org/essays/2012/06/14/the-future-of-python-http .. _`urllib3`: https://github.com/urllib3/urllib3 +.. _`urllib3.util.Retry`: https://urllib3.readthedocs.io/en/stable/reference/urllib3.util.html#urllib3.util.Retry .. _blocking-or-nonblocking: