Skip to content

Commit

Permalink
Add an Example for automatic retries to the Advanced Usage docs (#6258)
Browse files Browse the repository at this point in the history
- 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.
  • Loading branch information
matthewarmand committed Jul 3, 2023
1 parent 22db55a commit cdbc2e2
Showing 1 changed file with 22 additions and 0 deletions.
22 changes: 22 additions & 0 deletions docs/user/advanced.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <requests.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:

Expand Down

0 comments on commit cdbc2e2

Please sign in to comment.