Access to Decorator Parameters in on_backoff Handlers

[zhaohanyan]

Issue: Access to Decorator Parameters in on_backoff Handlers

Description
Currently, when using backoff decorators like @backoff.on_predicate or @backoff.on_exception, the on_backoff handlers only receive a details dictionary with limited information. However, important decorator parameters, such as max_time and max_tries, are not accessible in the details, which can limit flexibility in implementing complex backoff handling logic. Additionally, there is no direct way to pass additional parameters to on_backoff handlers.

Problem
For use cases where on_backoff handling may need to consider or log values like max_time and max_tries (especially if they are dynamic), users currently need to implement workarounds such as using global variables, environment variables, or functools.partial. These methods, while functional, can make the code less readable and maintainable.

Allowing direct access to decorator parameters like max_time and max_tries within on_backoff handlers would simplify configuration and enhance functionality. Additionally, supporting the option to pass custom parameters into the on_backoff handler would add flexibility for more complex backoff strategies.

Proposed Solution

1. Include Decorator Parameters in details: Add max_time, max_tries, and other relevant parameters from the decorator into the details dictionary.
2. Allow Additional Parameters in on_backoff Handlers: Permit on_backoff handlers to accept additional arguments beyond details, enabling more flexible configuration.

Example Usage

@backoff.on_predicate(
    backoff.runtime,
    predicate=lambda r: r.status_code == 429,
    on_backoff=lambda details, max_time: custom_handler(details, max_time=max_time),
    max_time=180,
    max_tries=5
)
def my_function():
    pass

def custom_handler(details, max_time):
    # Access max_time directly in the handler
    print(f"Max time is set to {max_time}")

Benefit
This enhancement would improve flexibility and code readability when working with backoff configurations and would allow more sophisticated use cases to be handled more naturally.

[zhaohanyan]

In our custom function use case, we would like to check if the Retry-After header specifies a wait time that exceeds max_time. If it does, we prefer to skip waiting and immediately return, saving time by not waiting longer than necessary.