Add an Example for automatic retries to the Advanced Usage docs

[matthewarmand]

While Requests doesn't automatically retry failures, this is an extremely common advanced use case in real world applications.

Although there's a mention of this capability in the HTTPAdapter API docs, it's a bit buried and not very specific.

The ubiquity of the use case fits perfectly in the Transport Adapters section of the Advanced Usage docs, so I thought it would be useful to have a simple Example of this capability.

I took a stab at such an addition, and tried to follow the style of the rest of the docs pretty closely.

Linking over to the urllib3.util.Retry docs seems like it should reinforce the fact that Requests isn't the owner of that code and that library should be consulted with questions about that class (rather than Requests' support of it).

I'm curious if maintainers have any feedback about the content or code example. Specifically I was curious whether you have any opinions as to the appropriate standard for the Retry import. While urllib3.util.Retry is where the class lives and what the urllib3 docs reference, from urllib3 import Retry also works, and in some StackOverflow posts I've seen people use from requests.adapters import Retry. I felt that last one would telegraph an ownership by Requests that would be undesirable, but I'm wondering if anyone is particularly picky about the best practice for that import.

Also, let me know if this is non-trivial enough to add a HISTORY entry for.

[matthewarmand]

@nateprewitt and @sethmlarson, apologies for the tag-summon (I find that a bit discourteous sometimes) but I think this is a pretty low-effort, low-risk, high-value docs change that folks would find useful, and I'm guessing it probably just got lost in the rest of the activity on this project.

Do either of you (or any other maintainers) have any thoughts or feedback on the change in general, or the questions I posed above in the original post? Is this something you'd consider accepting into the docs?

[nateprewitt]

Hi @matthewarmand, thanks for checking in. This does look reasonable at first glance, it appears to have fallen off the review radar. I'll do a quick review this evening and let you know if anything needs to change. Otherwise, I'm alright with adding this.

[nateprewitt]

Looks good, thanks @matthewarmand!