Support user-defined retrying strategies

[jwodder]

Possible API:

• The Client constructor is passed an instance of a Retrier protocol instead of a RetryConfig.

• When the client gets an error (including an HTTPError from raise_for_status()), it passes the error to the retrier's handle() (or on_error()?) method along with a dataclass with attributes for retry number and the time at which the client started attemping to make the request before retries.

• The handle method either returns a float/int — causing the client to sleep that many seconds and then retry — or else returns None — indicating that no retrying should occur, in which case the client reraises the original error.

• The dataclass should also have a dict attribute for the retrier to store arbitrary data in

• Also give the dataclass method and url attributes

• Idea: Change Retrier to an ABC and give it an on_success() method that defaults to pass?

  • This can be used to emit a log message when a request succeeds after retries

• The current retrying strategy should be implemented by a default Retrier class (named GitHubRetrier?).

• Add a NullRetrier implementation that never retries

• Ideally, it should be easy for the user to take the default retrier and add in a custom retry condition to consider in addition to the default conditions, possibly with calculating of custom sleep times when this condition occurs.

  • It should be easy for a custom retry condition to indicate that the sleep time should be based on exponential backoff without the condition having to do the backoff calculation itself.

    • Give the default retrier a backoff(attempts: int) -> float method for this purpose?
    • Technically, if a custom retry check were to return a delay of 0 or a negative number, this would result in the use of exponential backoff, but that may be too obtuse.

  • If a custom retry condition returns a sleep time less than the current exponential backoff time, the latter is used as the sleep time instead, just like for the current strategy

  • idea: Define the default retrier or another retrier as taking a collection of Callable[[RequestError, RetryState], float | None] values, and then the handle method calls each one and uses the maximum result (possibly clamped to not exceed the stop time)