From 9745ec9ceb33e9abb54993bbd54f3344aeb8c07e Mon Sep 17 00:00:00 2001 From: Alex Vandiver Date: Mon, 3 Aug 2020 13:04:29 -0700 Subject: [PATCH] doc: Document the backoff class better. --- zulip/zulip/__init__.py | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/zulip/zulip/__init__.py b/zulip/zulip/__init__.py index 94e4be0..f61935b 100644 --- a/zulip/zulip/__init__.py +++ b/zulip/zulip/__init__.py @@ -33,7 +33,27 @@ requests_json_is_function = callable(requests.Response.json) API_VERSTRING = "v1/" class CountingBackoff: - def __init__(self, maximum_retries: int = 10, timeout_success_equivalent: Optional[float] = None, delay_cap: float = 90.0) -> None: + def __init__( + self, + maximum_retries: int = 10, + timeout_success_equivalent: Optional[float] = None, + delay_cap: float = 90.0, + ) -> None: + """Sets up a retry-backoff object. Example usage: + backoff = zulip.CountingBackoff() + while backoff.keep_going(): + try: + something() + backoff.succeed() + except Exception: + backoff.fail() + + timeout_success_equivalent is used in cases where 'success' is + never possible to determine automatically; it sets the + threshold in seconds before the next keep_going/fail, above + which the last run is treated like it was a success. + + """ self.number_of_retries = 0 self.maximum_retries = maximum_retries self.timeout_success_equivalent = timeout_success_equivalent