kennethreitz/requests — pull request #2216 by sigmavirus24 (2014-09-10 19:17:41+00:00)
Title: Retries logic

Currently our documentation tells user that by creating a custom `HTTPAdapter` they can pass `max_retries=n` and that will apply to connection and read retries. This is a lie at the moment (and has been probably since 2.4.0 was released with the new version of urllib3 that added the `Retry` class).

In order to preserve backwards compatibility (and have passing tests) I remember upgrading the logic [here](https://github.com/kennethreitz/requests/blob/master/requests/adapters.py#L361) to pass `read=False` because some where we expected a plain `ReadTimeout` exception we were now getting a `MaxRetryError`. This, however, means that we have broken what we promised in the documentation (and what was likely present in even 2.3.0).

At the moment we do not support passing a `Retry` instance from `urllib3`. I'd like to propose the following changes:

- In `requests.adapters`, `DEFAULT_RETRIES` becomes a sentinel object, e.g., `DEFAULT_RETRIES = object()`.
- In `HTTPAdatper.__init__`, we check for the sentinel object and if so set `self.max_retries` to `Retry(0, read=False)`. Otherwise, we do `self.max_retries = Retry.from_int(max_retries)`

This should fix preserve the default existing behaviour that specifying `read=False` preserved but also allow users to do one of two things:

1. Import `Retry` from urllib3, construct their own `Retry` instance and then pass it as `max_retries`
1. Specify a number for both connection and read retries.

Does this sound like a fair proposal?

**Edit** I forgot to mention that @txtsd brought this to our attention in IRC. They get the credit for reporting this. Thank you @txtsd