Expose conditional backoff

[kkirsche]

It would be amazing to expose a conditional backoff API that would allow users creating things like API clients to expose to their end users the option to retry or not

[bgreen-litl]

Do you mean some kind of API that a 3rd party library could could expose to its clients to transparently provide backoff's functionality?

[kkirsche]

I believe so. To rephrase myself, I'd like to use a library like this when building an API client library. In that library, I'd like to expose the option to end users of using exponential backoff without their need to implement that. I was hoping some form of conditional backoff (where the user could set backoff=true) or (backoff=false) and then either have the backoff functionality enabled or disabled based on that decision.

Does that make sense?

[bgreen-litl]

Yes. It's an interesting thought. I think like you might end up wanting to expose more configuration options than just True or False though. Maybe you'd want to mirror some subset of backoff's options as kwargs in your library? I'd have to think about this more.

[leszekhanusz]

Let's say you have a class with a do_stuff method:

class MyClass:

    def __init__(self):
        pass

    def do_stuff(self):
        print("do stuff")

If you want to implement conditional backoff to this method, you can add a parameter to the __init__ method which takes either a boolean or a full backoff decorator.

If you do that, by default the retries are enabled (or disabled) with the boolean but allows the user to define a completely specific backoff profile as well.

You rename your do_stuff method to _do_stuff_once and create the do_stuff method in the __init__ with either a default backoff decorator or the decorator provided by the user.

_CallableT = TypeVar("_CallableT", bound=Callable[..., Any])
_Decorator = Callable[[_CallableT], _CallableT]

class MyClass:

    def __init__(
        self,
        retry: Union[bool, _Decorator] = True,
    ):
        """
        :param retry: Either a Boolean to activate/deactivate the retries OR
            a backoff decorator to provide specific retries parameters.
        """

        if retry is True:
            # By default, retry repeatedly, with maximum 60 seconds between retries
            retry_decorator = backoff.on_exception(
                backoff.expo,
                Exception,
                max_value=60,
            )
        elif retry is False:
            retry_decorator = lambda e: e
        else:
            assert callable(retry)
            retry_decorator = retry

        # Creating the do_stuff method with the defined backoff decorator
        self.do_stuff = retry_decorator(self._do_stuff_once)

    def _do_stuff_once(self):
        print("do stuff")

If you do that, the user has complete control over the type of backoff profile:

# Default usage: retries with your default backoff profile
m = MyClass()

# User disabled the retries
m = MyClass(retry=False)

# User provides a custom backoff decorator
retry_decorator=backoff.on_exception(
    backoff.expo,
    Exception,
    max_value=300,
)
m = MyClass(retry=retry_decorator)

This is the approach I used in graphql-python/gql PR #324