backon 3.0.0__tar.gz

backon-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Llucs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

backon-3.0.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.1
+Name: backon
+Version: 3.0.0
+Summary: Function decoration for backoff and retry
+Keywords: retry,backoff,decorators
+Author-Email: Llucs <c307lucas@gmail.com>
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Project-URL: homepage, https://github.com/Llucs/backon
+Project-URL: repository, https://github.com/Llucs/backon
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# backon
+
+> Function decoration for backoff and retry — modern, fast, and zero dependencies.
+
+[![CI](https://github.com/Llucs/backon/actions/workflows/ci.yml/badge.svg)](https://github.com/Llucs/backon/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/backon.svg)](https://pypi.org/project/backon/)
+[![Python](https://img.shields.io/pypi/pyversions/backon.svg)](https://pypi.org/project/backon/)
+[![License](https://img.shields.io/pypi/l/backon.svg)](https://github.com/Llucs/backon/blob/main/LICENSE)
+
+## Why backon?
+
+**backon** is the evolution of [backoff](https://github.com/litl/backoff) — a zero-dependency Python library for retry with exponential backoff. If you know backoff, you already know backon.
+
+| Feature | backoff | tenacity | backon |
+|---|---|---|---|
+| Python 3.10+ native | ❌ | ❌ | ✅ |
+| Type hints | ❌ partial | ✅ | ✅ full |
+| `disable()` / `enable()` toggle | ❌ | ❌ | ✅ |
+| Context manager API | ❌ | ✅ | ✅ |
+| Functional `retry()` API | ❌ | ✅ | ✅ |
+| `on_attempt` callback | ❌ | ✅ | ✅ |
+| Custom sleep injection | ❌ | ❌ | ✅ |
+| `time.monotonic()` | ❌ | ✅ | ✅ |
+| PDM / PEP 621 build | ❌ | ❌ | ✅ |
+| Zero dependencies | ✅ | ✅ | ✅ |
+
+## Quick Start
+
+```bash
+pip install backon
+```
+
+### Retry on exception
+
+```python
+import backon
+
+@backon.on_exception(backon.expo, ValueError, max_tries=3)
+def fetch_data():
+    return api.call()
+```
+
+### Retry on predicate
+
+```python
+@backon.on_predicate(backon.constant, max_tries=5, interval=0.5)
+def poll_status():
+    return check_ready()
+```
+
+### Functional API
+
+```python
+result = backon.retry(fetch_data, backon.expo, exception=ValueError, max_tries=3)
+```
+
+### Context manager
+
+```python
+with backon.Retrying(backon.expo, exception=ValueError, max_tries=3) as r:
+    result = r.call(fetch_data)
+```
+
+## Wait Generators
+
+| Generator | Description |
+|---|---|
+| `expo(base=2, factor=1, max_value=None)` | Exponential backoff |
+| `constant(interval=1)` | Constant interval |
+| `fibo(max_value=None)` | Fibonacci backoff |
+| `runtime(value=callable)` | Dynamic wait from return value |
+| `decay(initial_value=1, decay_factor=1, min_value=None)` | Exponential decay |
+
+## Jitter
+
+```python
+@backon.on_exception(backon.expo, ValueError, jitter=backon.full_jitter)
+```
+
+- `full_jitter` — random between 0 and the wait value
+- `random_jitter` — random ±25% around the wait value
+- `None` — no jitter
+
+## Handlers
+
+```python
+def log_attempt(details):
+    print(f"Attempt {details['tries']} for {details['target'].__name__}")
+
+@backon.on_exception(
+    backon.expo, ValueError, max_tries=3,
+    on_attempt=log_attempt,
+    on_backoff=log_attempt,
+    on_success=log_attempt,
+    on_giveup=log_attempt,
+)
+def f():
+    ...
+```
+
+Available `details` keys: `target`, `args`, `kwargs`, `tries`, `elapsed`, `value` (on_success/on_backoff/on_giveup), `exception` (on_backoff/on_giveup), `wait` (on_backoff).
+
+## Global Toggle
+
+```python
+backon.disable()   # skip retry, call function directly
+backon.enable()    # re-enable retry
+```
+
+## Async Support
+
+Everything works with `async def` functions — no extra flags needed.
+
+```python
+@backon.on_exception(backon.expo, ValueError, max_tries=3)
+async def fetch_data():
+    return await api.call()
+```
+
+## Custom Sleep
+
+```python
+@backon.on_exception(backon.expo, ValueError, max_tries=3,
+                     sleep=lambda s: print(f"waiting {s}s"))
+def f():
+    ...
+```
+
+## Installation
+
+```bash
+pip install backon
+```
+
+Requires Python 3.10+.
+
+## Migrating from backoff
+
+backon is a drop-in replacement for most backoff users. Just change:
+
+```python
+# before
+import backoff
+@backoff.on_exception(backoff.expo, ValueError, max_tries=3)
+
+# after
+import backon
+@backon.on_exception(backon.expo, ValueError, max_tries=3)
+```
+
+## License
+
+MIT

backon-3.0.0/README.md

@@ -0,0 +1,153 @@
+# backon
+
+> Function decoration for backoff and retry — modern, fast, and zero dependencies.
+
+[![CI](https://github.com/Llucs/backon/actions/workflows/ci.yml/badge.svg)](https://github.com/Llucs/backon/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/backon.svg)](https://pypi.org/project/backon/)
+[![Python](https://img.shields.io/pypi/pyversions/backon.svg)](https://pypi.org/project/backon/)
+[![License](https://img.shields.io/pypi/l/backon.svg)](https://github.com/Llucs/backon/blob/main/LICENSE)
+
+## Why backon?
+
+**backon** is the evolution of [backoff](https://github.com/litl/backoff) — a zero-dependency Python library for retry with exponential backoff. If you know backoff, you already know backon.
+
+| Feature | backoff | tenacity | backon |
+|---|---|---|---|
+| Python 3.10+ native | ❌ | ❌ | ✅ |
+| Type hints | ❌ partial | ✅ | ✅ full |
+| `disable()` / `enable()` toggle | ❌ | ❌ | ✅ |
+| Context manager API | ❌ | ✅ | ✅ |
+| Functional `retry()` API | ❌ | ✅ | ✅ |
+| `on_attempt` callback | ❌ | ✅ | ✅ |
+| Custom sleep injection | ❌ | ❌ | ✅ |
+| `time.monotonic()` | ❌ | ✅ | ✅ |
+| PDM / PEP 621 build | ❌ | ❌ | ✅ |
+| Zero dependencies | ✅ | ✅ | ✅ |
+
+## Quick Start
+
+```bash
+pip install backon
+```
+
+### Retry on exception
+
+```python
+import backon
+
+@backon.on_exception(backon.expo, ValueError, max_tries=3)
+def fetch_data():
+    return api.call()
+```
+
+### Retry on predicate
+
+```python
+@backon.on_predicate(backon.constant, max_tries=5, interval=0.5)
+def poll_status():
+    return check_ready()
+```
+
+### Functional API
+
+```python
+result = backon.retry(fetch_data, backon.expo, exception=ValueError, max_tries=3)
+```
+
+### Context manager
+
+```python
+with backon.Retrying(backon.expo, exception=ValueError, max_tries=3) as r:
+    result = r.call(fetch_data)
+```
+
+## Wait Generators
+
+| Generator | Description |
+|---|---|
+| `expo(base=2, factor=1, max_value=None)` | Exponential backoff |
+| `constant(interval=1)` | Constant interval |
+| `fibo(max_value=None)` | Fibonacci backoff |
+| `runtime(value=callable)` | Dynamic wait from return value |
+| `decay(initial_value=1, decay_factor=1, min_value=None)` | Exponential decay |
+
+## Jitter
+
+```python
+@backon.on_exception(backon.expo, ValueError, jitter=backon.full_jitter)
+```
+
+- `full_jitter` — random between 0 and the wait value
+- `random_jitter` — random ±25% around the wait value
+- `None` — no jitter
+
+## Handlers
+
+```python
+def log_attempt(details):
+    print(f"Attempt {details['tries']} for {details['target'].__name__}")
+
+@backon.on_exception(
+    backon.expo, ValueError, max_tries=3,
+    on_attempt=log_attempt,
+    on_backoff=log_attempt,
+    on_success=log_attempt,
+    on_giveup=log_attempt,
+)
+def f():
+    ...
+```
+
+Available `details` keys: `target`, `args`, `kwargs`, `tries`, `elapsed`, `value` (on_success/on_backoff/on_giveup), `exception` (on_backoff/on_giveup), `wait` (on_backoff).
+
+## Global Toggle
+
+```python
+backon.disable()   # skip retry, call function directly
+backon.enable()    # re-enable retry
+```
+
+## Async Support
+
+Everything works with `async def` functions — no extra flags needed.
+
+```python
+@backon.on_exception(backon.expo, ValueError, max_tries=3)
+async def fetch_data():
+    return await api.call()
+```
+
+## Custom Sleep
+
+```python
+@backon.on_exception(backon.expo, ValueError, max_tries=3,
+                     sleep=lambda s: print(f"waiting {s}s"))
+def f():
+    ...
+```
+
+## Installation
+
+```bash
+pip install backon
+```
+
+Requires Python 3.10+.
+
+## Migrating from backoff
+
+backon is a drop-in replacement for most backoff users. Just change:
+
+```python
+# before
+import backoff
+@backoff.on_exception(backoff.expo, ValueError, max_tries=3)
+
+# after
+import backon
+@backon.on_exception(backon.expo, ValueError, max_tries=3)
+```
+
+## License
+
+MIT

backon-3.0.0/backon/__init__.py

@@ -0,0 +1,23 @@
+from backon._common import disable, enable
+from backon._decorator import on_exception, on_predicate
+from backon._jitter import full_jitter, random_jitter
+from backon._retry import Retrying, retry
+from backon._wait_gen import constant, decay, expo, fibo, runtime
+
+__all__ = [
+    "on_predicate",
+    "on_exception",
+    "retry",
+    "Retrying",
+    "constant",
+    "expo",
+    "decay",
+    "fibo",
+    "runtime",
+    "full_jitter",
+    "random_jitter",
+    "disable",
+    "enable",
+]
+
+__version__ = "3.0.0"

backon-3.0.0/backon/_async.py

@@ -0,0 +1,208 @@
+import asyncio
+import functools
+
+from backon._common import (
+    _elapsed,
+    _init_wait_gen,
+    _maybe_call,
+    _next_wait,
+    _now,
+    is_enabled,
+)
+
+
+def _unwrap(target):
+    if isinstance(target, staticmethod):
+        return target.__func__
+    return target
+
+
+def _ensure_coroutine(coro_or_func):
+    if asyncio.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):
+    details = {
+        "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,
+    on_attempt,
+    sleep,
+    wait_gen_kwargs,
+):
+    target = _unwrap(target)
+    on_success = _ensure_coroutines(on_success)
+    on_backoff = _ensure_coroutines(on_backoff)
+    on_giveup = _ensure_coroutines(on_giveup)
+    on_attempt = _ensure_coroutines(on_attempt)
+
+    assert not asyncio.iscoroutinefunction(max_tries)
+    assert not asyncio.iscoroutinefunction(jitter)
+
+    assert asyncio.iscoroutinefunction(target)
+
+    @functools.wraps(target)
+    async def retry(*args, **kwargs):
+        if not is_enabled():
+            return await target(*args, **kwargs)
+
+        max_tries_value = _maybe_call(max_tries)
+        max_time_value = _maybe_call(max_time)
+
+        tries = 0
+        start = _now()
+        wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
+        while True:
+            tries += 1
+            elapsed = _elapsed(start)
+            details = {
+                "target": target,
+                "args": args,
+                "kwargs": kwargs,
+                "tries": tries,
+                "elapsed": elapsed,
+            }
+
+            await _call_handlers(on_attempt, **details)
+
+            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
+                )
+
+                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)
+                except StopIteration:
+                    await _call_handlers(on_giveup, **details, value=ret)
+                    break
+
+                await _call_handlers(on_backoff, **details, value=ret, wait=seconds)
+
+                await sleep(seconds)
+                continue
+            else:
+                await _call_handlers(on_success, **details, value=ret)
+                break
+
+        return ret
+
+    return retry
+
+
+def retry_exception(
+    target,
+    wait_gen,
+    exception,
+    *,
+    max_tries,
+    max_time,
+    jitter,
+    giveup,
+    on_success,
+    on_backoff,
+    on_giveup,
+    on_attempt,
+    raise_on_giveup,
+    sleep,
+    wait_gen_kwargs,
+):
+    target = _unwrap(target)
+    on_success = _ensure_coroutines(on_success)
+    on_backoff = _ensure_coroutines(on_backoff)
+    on_giveup = _ensure_coroutines(on_giveup)
+    on_attempt = _ensure_coroutines(on_attempt)
+    giveup = _ensure_coroutine(giveup)
+
+    assert not asyncio.iscoroutinefunction(max_tries)
+    assert not asyncio.iscoroutinefunction(jitter)
+
+    @functools.wraps(target)
+    async def retry(*args, **kwargs):
+        if not is_enabled():
+            return await target(*args, **kwargs)
+
+        max_tries_value = _maybe_call(max_tries)
+        max_time_value = _maybe_call(max_time)
+
+        tries = 0
+        start = _now()
+        wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
+        while True:
+            tries += 1
+            elapsed = _elapsed(start)
+            details = {
+                "target": target,
+                "args": args,
+                "kwargs": kwargs,
+                "tries": tries,
+                "elapsed": elapsed,
+            }
+
+            await _call_handlers(on_attempt, **details)
+
+            try:
+                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
+                )
+
+                if giveup_result or max_tries_exceeded or max_time_exceeded:
+                    await _call_handlers(on_giveup, **details, exception=e)
+                    if raise_on_giveup:
+                        raise
+                    return None
+
+                try:
+                    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 sleep(seconds)
+            else:
+                await _call_handlers(on_success, **details)
+                return ret
+
+    return retry

backon-3.0.0/backon/_common.py

@@ -0,0 +1,117 @@
+import functools
+import logging
+import sys
+import time as time_module
+import traceback
+
+_logger = logging.getLogger("backon")
+_logger.addHandler(logging.NullHandler())
+
+_GLOBAL_ENABLED = True
+
+
+def disable():
+    global _GLOBAL_ENABLED
+    _GLOBAL_ENABLED = False
+
+
+def enable():
+    global _GLOBAL_ENABLED
+    _GLOBAL_ENABLED = True
+
+
+def is_enabled():
+    return _GLOBAL_ENABLED
+
+
+def _maybe_call(f, *args, **kwargs):
+    if callable(f):
+        try:
+            return f(*args, **kwargs)
+        except TypeError:
+            return f
+    else:
+        return f
+
+
+def _init_wait_gen(wait_gen, wait_gen_kwargs):
+    kwargs = {k: _maybe_call(v) for k, v in wait_gen_kwargs.items()}
+    initialized = wait_gen(**kwargs)
+    initialized.send(None)
+    return initialized
+
+
+def _next_wait(wait, send_value, jitter, elapsed, max_time):
+    value = wait.send(send_value)
+    if jitter is not None:
+        seconds = jitter(value)
+    else:
+        seconds = value
+
+    if max_time is not None:
+        seconds = min(seconds, max_time - elapsed)
+
+    return seconds
+
+
+def _prepare_logger(logger):
+    if isinstance(logger, str):
+        logger = logging.getLogger(logger)
+    return logger
+
+
+def _config_handlers(
+    user_handlers, *, default_handler=None, logger=None, log_level=None
+):
+    handlers = []
+    if logger is not None:
+        assert log_level is not None
+        log_handler = functools.partial(
+            default_handler, logger=logger, log_level=log_level
+        )
+        handlers.append(log_handler)
+
+    if user_handlers is None:
+        return handlers
+
+    if hasattr(user_handlers, "__iter__"):
+        handlers += list(user_handlers)
+    else:
+        handlers.append(user_handlers)
+
+    return handlers
+
+
+def _log_backoff(details, logger, log_level):
+    msg = "Backing off %s(...) for %.1fs (%s)"
+    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"])
+    logger.log(log_level, msg, *log_args)
+
+
+def _log_giveup(details, logger, log_level):
+    msg = "Giving up %s(...) after %d tries (%s)"
+    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"])
+
+    logger.log(log_level, msg, *log_args)
+
+
+def _now():
+    return time_module.monotonic()
+
+
+def _elapsed(start):
+    return _now() - start