Add a retry decorator

[prkumar]

Here's the original use case from @liiight on Gitter:

I'm implementing retries in my code, which is done using a package called retry. basically its a super simple decorator, just catch exception, and call the decoratored func until conditions apply, nothing fancy
when using with uplink, I'm implementing it in the layer above uplink, i.e, the usage of it. i was wondering if it's possible to do it via uplink itself
i.e, catch an error and retry the called method

[prkumar]

This is similar to #71

[prkumar]

Here's my original reply. It would be nice if Uplink supported usage of existing decorators for retry, rate-limiting, etc. At the moment, this is not possible (because of how consumer methods are implemented). It might be worth it to consider if and how we should support this usage.

[bendews]

An additional use case for this sort of functionality is when auth tokens have a short expiry. On some (admittedly not great) API's I catch an expired token as an exception, refresh it and then try the original request again. Being able to simplify that interaction would be awesome.

[liiight]

@bendews You should look into https://github.com/oauthlib/oauthlib and https://requests-oauthlib.readthedocs.io/en/latest/
@prkumar It's kind of a deviation of this issue, but passing custom sessions (like how requests oauthlib implements oauth) would be very cool

[prkumar]

@liiight - the client constructor argument of a Consumer subclass should already support requests.Session subclasses (like the OAuth2Session class from requests-oauthlib library). So, although I haven't tried it out, the following should work already:

from requests_oauthlib from OAuth2Session

session = OAuth2Session(client_id)
github = GitHub(base_url=BASE_URL, client=session)

Is this what you're talking about?

[liiight]

Exactly, thanks for pointing that out.
@bednews you should check out the links I gave because requests oauthlib can be refresh token internally (when using oauth obviously)

[bendews]

@liiight I would have had far less sleepless nights if they were OAuth compliant, trust me on that! 😁

[prkumar]

The retry decorator should be available in v0.8.0. After I merge #132, I'll create a new alpha release v0.8.0a1 in case you wan't to try it out before the official release. To install this alpha release with pip, do:

$ pip install --pre uplink

Here's some documentation for the decorator. (I'll also be soon adding a section to the quickstart about this feature). Notably, this decorator can be used like the other decorators, such as @timeout or @headers:

class GitHub(uplink.Consumer):
    @uplink.retry(max_attempts=2)
    @uplink.get("/users/{user}")
    def get_user(self, user):
        pass

If you get the chance to try it out, let me know if you also have any feedback!

CC: @bendews @liiight

[prkumar]

I just released an new alpha version, v0.8.0a2, with some updates to this decorator. If you were testing the previous alpha, please update:

$ pip install --pre -U uplink

Also, I've added a section to the quickstart to help get started with using this decorator: https://uplink.readthedocs.io/en/latest/user/quickstart.html#retrying

[liiight]

I haven't had a chance to play with this but the interface look great.

One suggestion though, you could use native ptrhon status code enum for the retry conditions: https://docs.python.org/3/library/http.html#http.HTTPStatus

[prkumar]

@liiight - Thanks for the suggestion! I'll add a way to use status codes in the retry condition.