WIP: format python in docs

Author: edgarrmondragon

.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
     rev: v0.14.6
     hooks:
     -   id: ruff-check
-    # -   id: ruff-format
+    -   id: ruff-format
 -   repo: https://github.com/astral-sh/uv-pre-commit
     rev: 0.9.13
     hooks:

backoff/__init__.py

@@ -12,20 +12,21 @@
 For examples and full documentation see the README at
 https://github.com/python-backoff/backoff
 """
+
 from backoff._decorator import on_exception, on_predicate
 from backoff._jitter import full_jitter, random_jitter
 from backoff._wait_gen import constant, expo, fibo, runtime, decay
 
 __all__ = [
-    'on_predicate',
-    'on_exception',
-    'constant',
-    'expo',
-    'decay',
-    'fibo',
-    'runtime',
-    'full_jitter',
-    'random_jitter',
+    "on_predicate",
+    "on_exception",
+    "constant",
+    "expo",
+    "decay",
+    "fibo",
+    "runtime",
+    "full_jitter",
+    "random_jitter",
 ]
 
 __version__ = "2.2.1"

backoff/_async.py

@@ -11,37 +11,44 @@ def _ensure_coroutine(coro_or_func):
     if inspect.iscoroutinefunction(coro_or_func):
         return coro_or_func
     else:
+
         @functools.wraps(coro_or_func)
         async def f(*args, **kwargs):
             return coro_or_func(*args, **kwargs)
+
         return f
 
 
 def _ensure_coroutines(coros_or_funcs):
     return [_ensure_coroutine(f) for f in coros_or_funcs]
 
 
-async def _call_handlers(handlers,
-                         *,
-                         target, args, kwargs, tries, elapsed,
-                         **extra):
+async def _call_handlers(handlers, *, target, args, kwargs, tries, elapsed, **extra):
     details = {
-        'target': target,
-        'args': args,
-        'kwargs': kwargs,
-        'tries': tries,
-        'elapsed': elapsed,
+        "target": target,
+        "args": args,
+        "kwargs": kwargs,
+        "tries": tries,
+        "elapsed": elapsed,
     }
     details.update(extra)
     for handler in handlers:
         await handler(details)
 
 
-def retry_predicate(target, wait_gen, predicate,
-                    *,
-                    max_tries, max_time, jitter,
-                    on_success, on_backoff, on_giveup,
-                    wait_gen_kwargs):
+def retry_predicate(
+    target,
+    wait_gen,
+    predicate,
+    *,
+    max_tries,
+    max_time,
+    jitter,
+    on_success,
+    on_backoff,
+    on_giveup,
+    wait_gen_kwargs,
+):
     on_success = _ensure_coroutines(on_success)
     on_backoff = _ensure_coroutines(on_backoff)
     on_giveup = _ensure_coroutines(on_giveup)
@@ -54,7 +61,6 @@ def retry_predicate(target, wait_gen, predicate,
 
     @functools.wraps(target)
     async def retry(*args, **kwargs):
-
         # update variables from outer function args
         max_tries_value = _maybe_call(max_tries)
         max_time_value = _maybe_call(max_time)
@@ -75,23 +81,22 @@ async def retry(*args, **kwargs):
 
             ret = await target(*args, **kwargs)
             if predicate(ret):
-                max_tries_exceeded = (tries == max_tries_value)
-                max_time_exceeded = (max_time_value is not None and
-                                     elapsed >= max_time_value)
+                max_tries_exceeded = tries == max_tries_value
+                max_time_exceeded = (
+                    max_time_value is not None and elapsed >= max_time_value
+                )
 
                 if max_tries_exceeded or max_time_exceeded:
                     await _call_handlers(on_giveup, **details, value=ret)
                     break
 
                 try:
-                    seconds = _next_wait(wait, ret, jitter, elapsed,
-                                         max_time_value)
+                    seconds = _next_wait(wait, ret, jitter, elapsed, max_time_value)
                 except StopIteration:
                     await _call_handlers(on_giveup, **details, value=ret)
                     break
 
-                await _call_handlers(on_backoff, **details, value=ret,
-                                     wait=seconds)
+                await _call_handlers(on_backoff, **details, value=ret, wait=seconds)
 
                 # Note: there is no convenient way to pass explicit event
                 # loop to decorator, so here we assume that either default
@@ -113,11 +118,21 @@ async def retry(*args, **kwargs):
     return retry
 
 
-def retry_exception(target, wait_gen, exception,
-                    *,
-                    max_tries, max_time, jitter, giveup,
-                    on_success, on_backoff, on_giveup, raise_on_giveup,
-                    wait_gen_kwargs):
+def retry_exception(
+    target,
+    wait_gen,
+    exception,
+    *,
+    max_tries,
+    max_time,
+    jitter,
+    giveup,
+    on_success,
+    on_backoff,
+    on_giveup,
+    raise_on_giveup,
+    wait_gen_kwargs,
+):
     on_success = _ensure_coroutines(on_success)
     on_backoff = _ensure_coroutines(on_backoff)
     on_giveup = _ensure_coroutines(on_giveup)
@@ -129,7 +144,6 @@ def retry_exception(target, wait_gen, exception,
 
     @functools.wraps(target)
     async def retry(*args, **kwargs):
-
         max_tries_value = _maybe_call(max_tries)
         max_time_value = _maybe_call(max_time)
 
@@ -151,9 +165,10 @@ async def retry(*args, **kwargs):
                 ret = await target(*args, **kwargs)
             except exception as e:
                 giveup_result = await giveup(e)
-                max_tries_exceeded = (tries == max_tries_value)
-                max_time_exceeded = (max_time_value is not None and
-                                     elapsed >= max_time_value)
+                max_tries_exceeded = tries == max_tries_value
+                max_time_exceeded = (
+                    max_time_value is not None and elapsed >= max_time_value
+                )
 
                 if giveup_result or max_tries_exceeded or max_time_exceeded:
                     await _call_handlers(on_giveup, **details, exception=e)
@@ -162,14 +177,12 @@ async def retry(*args, **kwargs):
                     return None
 
                 try:
-                    seconds = _next_wait(wait, e, jitter, elapsed,
-                                         max_time_value)
+                    seconds = _next_wait(wait, e, jitter, elapsed, max_time_value)
                 except StopIteration:
                     await _call_handlers(on_giveup, **details, exception=e)
                     raise e
 
-                await _call_handlers(on_backoff, **details, wait=seconds,
-                                     exception=e)
+                await _call_handlers(on_backoff, **details, wait=seconds, exception=e)
 
                 # Note: there is no convenient way to pass explicit event
                 # loop to decorator, so here we assume that either default
@@ -185,4 +198,5 @@ async def retry(*args, **kwargs):
                 await _call_handlers(on_success, **details)
 
                 return ret
+
     return retry

backoff/_common.py

@@ -8,7 +8,7 @@
 
 
 # Use module-specific logger with a default null handler.
-_logger = logging.getLogger('backoff')
+_logger = logging.getLogger("backoff")
 _logger.addHandler(logging.NullHandler())  # pragma: no cover
 _logger.setLevel(logging.INFO)
 
@@ -65,14 +65,20 @@ def _prepare_logger(logger):
 # Configure handler list with user specified handler and optionally
 # with a default handler bound to the specified logger.
 def _config_handlers(
-    user_handlers, *, default_handler=None, logger=None, log_level=None,
+    user_handlers,
+    *,
+    default_handler=None,
+    logger=None,
+    log_level=None,
 ):
     handlers = []
     if logger is not None:
         assert log_level is not None, "Log level is not specified"
         # bind the specified logger to the default log handler
         log_handler = functools.partial(
-            default_handler, logger=logger, log_level=log_level,
+            default_handler,
+            logger=logger,
+            log_level=log_level,
         )
         handlers.append(log_handler)
 
@@ -81,7 +87,7 @@ def _config_handlers(
 
     # user specified handlers can either be an iterable of handlers
     # or a single handler. either way append them to the list.
-    if hasattr(user_handlers, '__iter__'):
+    if hasattr(user_handlers, "__iter__"):
         # add all handlers in the iterable
         handlers += list(user_handlers)
     else:
@@ -94,27 +100,27 @@ def _config_handlers(
 # Default backoff handler
 def _log_backoff(details, logger, log_level):
     msg = "Backing off %s(...) for %.1fs (%s)"
-    log_args = [details['target'].__name__, details['wait']]
+    log_args = [details["target"].__name__, details["wait"]]
 
     exc_typ, exc, _ = sys.exc_info()
     if exc is not None:
         exc_fmt = traceback.format_exception_only(exc_typ, exc)[-1]
         log_args.append(exc_fmt.rstrip("\n"))
     else:
-        log_args.append(details['value'])
+        log_args.append(details["value"])
     logger.log(log_level, msg, *log_args)
 
 
 # Default giveup handler
 def _log_giveup(details, logger, log_level):
     msg = "Giving up %s(...) after %d tries (%s)"
-    log_args = [details['target'].__name__, details['tries']]
+    log_args = [details["target"].__name__, details["tries"]]
 
     exc_typ, exc, _ = sys.exc_info()
     if exc is not None:
         exc_fmt = traceback.format_exception_only(exc_typ, exc)[-1]
         log_args.append(exc_fmt.rstrip("\n"))
     else:
-        log_args.append(details['value'])
+        log_args.append(details["value"])
 
     logger.log(log_level, msg, *log_args)

backoff/_decorator.py

@@ -24,19 +24,21 @@
 )
 
 
-def on_predicate(wait_gen: _WaitGenerator,
-                 predicate: _Predicate[Any] = operator.not_,
-                 *,
-                 max_tries: Optional[_MaybeCallable[int]] = None,
-                 max_time: Optional[_MaybeCallable[float]] = None,
-                 jitter: Union[_Jitterer, None] = full_jitter,
-                 on_success: Union[_Handler, Iterable[_Handler], None] = None,
-                 on_backoff: Union[_Handler, Iterable[_Handler], None] = None,
-                 on_giveup: Union[_Handler, Iterable[_Handler], None] = None,
-                 logger: _MaybeLogger = 'backoff',
-                 backoff_log_level: int = logging.INFO,
-                 giveup_log_level: int = logging.ERROR,
-                 **wait_gen_kwargs: Any) -> Callable[[_CallableT], _CallableT]:
+def on_predicate(
+    wait_gen: _WaitGenerator,
+    predicate: _Predicate[Any] = operator.not_,
+    *,
+    max_tries: Optional[_MaybeCallable[int]] = None,
+    max_time: Optional[_MaybeCallable[float]] = None,
+    jitter: Union[_Jitterer, None] = full_jitter,
+    on_success: Union[_Handler, Iterable[_Handler], None] = None,
+    on_backoff: Union[_Handler, Iterable[_Handler], None] = None,
+    on_giveup: Union[_Handler, Iterable[_Handler], None] = None,
+    logger: _MaybeLogger = "backoff",
+    backoff_log_level: int = logging.INFO,
+    giveup_log_level: int = logging.ERROR,
+    **wait_gen_kwargs: Any,
+) -> Callable[[_CallableT], _CallableT]:
     """Returns decorator for backoff and retry triggered by predicate.
 
     Args:
@@ -80,6 +82,7 @@ def on_predicate(wait_gen: _WaitGenerator,
             args will first be evaluated and their return values passed.
             This is useful for runtime configuration.
     """
+
     def decorate(target):
         nonlocal logger, on_success, on_backoff, on_giveup
 
@@ -120,21 +123,23 @@ def decorate(target):
     return decorate
 
 
-def on_exception(wait_gen: _WaitGenerator,
-                 exception: _MaybeSequence[Type[Exception]],
-                 *,
-                 max_tries: Optional[_MaybeCallable[int]] = None,
-                 max_time: Optional[_MaybeCallable[float]] = None,
-                 jitter: Union[_Jitterer, None] = full_jitter,
-                 giveup: _Predicate[Exception] = lambda e: False,
-                 on_success: Union[_Handler, Iterable[_Handler], None] = None,
-                 on_backoff: Union[_Handler, Iterable[_Handler], None] = None,
-                 on_giveup: Union[_Handler, Iterable[_Handler], None] = None,
-                 raise_on_giveup: bool = True,
-                 logger: _MaybeLogger = 'backoff',
-                 backoff_log_level: int = logging.INFO,
-                 giveup_log_level: int = logging.ERROR,
-                 **wait_gen_kwargs: Any) -> Callable[[_CallableT], _CallableT]:
+def on_exception(
+    wait_gen: _WaitGenerator,
+    exception: _MaybeSequence[Type[Exception]],
+    *,
+    max_tries: Optional[_MaybeCallable[int]] = None,
+    max_time: Optional[_MaybeCallable[float]] = None,
+    jitter: Union[_Jitterer, None] = full_jitter,
+    giveup: _Predicate[Exception] = lambda e: False,
+    on_success: Union[_Handler, Iterable[_Handler], None] = None,
+    on_backoff: Union[_Handler, Iterable[_Handler], None] = None,
+    on_giveup: Union[_Handler, Iterable[_Handler], None] = None,
+    raise_on_giveup: bool = True,
+    logger: _MaybeLogger = "backoff",
+    backoff_log_level: int = logging.INFO,
+    giveup_log_level: int = logging.ERROR,
+    **wait_gen_kwargs: Any,
+) -> Callable[[_CallableT], _CallableT]:
     """Returns decorator for backoff and retry triggered by exception.
 
     Args:
@@ -180,6 +185,7 @@ def on_exception(wait_gen: _WaitGenerator,
             args will first be evaluated and their return values passed.
             This is useful for runtime configuration.
     """
+
     def decorate(target):
         nonlocal logger, on_success, on_backoff, on_giveup