Inspect exception or return value in wait_gen (or wait_gen override)

[steinitzu]

I wanted to see if there is interest in an API addition to allow users to determine wait time based on exception or return value from the decorated function.

One use case being: You're sending requests to a rate limited API. API blocks your request but is nice enough to include Retry-After header in the response.
Retry-After contains the exact number of seconds you should wait before making another request.

If I could access the exception or response somehow before wait time is decided, I could check for this header and if present use its value, otherwise fall back on a wait_gen
Using any kind of calculated time function is very hit and miss in this scenario and mostly wasteful.

I'm thinking about adding an optional wait_override argument to the decorators. This would be a function that gets passed the exception (for backoff.on_exception) or the retry-able's return value (for backoff.on_predicate).
So that users can do something like this:

def my_override(exception):
    headers = getattr(e, 'headers', {})
    seconds = headers.get('Retry-After')
    # If None is returned, wait_gen takes over
    return int(seconds) if seconds else None
    
@backoff.on_exception(backoff.expo, HTTPError, wait_override=my_override)    
def request_thing(url):
    response = do_request(...)    
    response.raise_for_status()
    return response

[bgreen-litl]

This seems like a valid use case. Your suggested API is actually very similar to that of the giveup keyword arg. So in that sense it doesn't seem out of place. giveup is only supported on on_exceptiondecorator though - do you think on_predicate would have such a compelling case? In general, I do try to keep them as similar as possible, but we would end up with the slightly odd API of in one case the function taking an Exception arg and in the other an arbitrary value. Maybe that's not too weird though?

I have one other thought for an implementation which might be slicker, or maybe it wouldn't work... Although I haven't used the feature much, it's possible to send values to generators as well as yield from them. What if the backoff.expo (or perhaps a replacement) generator supported receiving the exception or value itself? Any change would need to be backward compatible, and it's possible this just won't work since I haven't tried. If it did work though, this might be nicer than expanding API surface with another keyword arg. Thoughts?

[steinitzu]

I like the idea of sending the value to the generator, but also somewhat unfamiliar territory for me.
I'll play around with it a bit, I think it might be doable without breaking all current gen functions. Seems that send() just does the same thing as next() on a regular started generator unless the generator explicitly handles it.
Then possibly a custom wait_gen could be used to do some stuff with exception.

I don't really have a good use case for on_predicate in general right now, I'm more likely to just check the return value inline if needed and throw an exception, so no idea if and how people would use a feature like this with it.

[bgreen-litl]

Thanks.

Now that I'm thinking about, I think it's possible that the giveup keyword arg could be better implemented this way too. If the wait_gen generator received the exception or value it could do that "should I give up" introspection itself and return None if so. The API actually wouldn't need to change to implement this, as the giveup keyword would be passed along to wait_gen on its instantiation (see how max_value works).

If I'm losing you or confusing the point, don't worry about it. I'm thinking out loud here a bit. The point is that if your feature can be implemented with a send() to the generator then perhaps giveup can be implemented this way too.

[edgarrmondragon]

is this closed by ed932f7?

[bgreen-litl]

@edgarrmondragon Yes. Thanks. And released in latest backoff (2.0.1)