python-wrap 0.2.1__py3-none-any.whl

python_wrap/config.py

@@ -0,0 +1,217 @@
+"""Project-wide defaults for python-wrap decorators.
+
+Call `configure` once at application start-up, **before** the decorators you want to
+affect are applied. Values are read when a decorator is *applied* (at import time for
+module-level functions), so a decorator applied earlier keeps the settings it saw.
+Arguments passed explicitly to a decorator always win over configured defaults.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import difflib
+import logging
+import threading
+from collections.abc import Iterable, Iterator, Mapping
+from typing import Any
+
+from python_wrap import _core
+
+__all__ = ["configure", "configured", "get_config", "reset_config"]
+
+UNSET: Any = object()
+"""Sentinel meaning "argument not passed"; resolved against the configured defaults."""
+
+_KEYS = ("logger", "retry", "redact", "redact_extra")
+_RETRY_KEYS = (
+    "max_attempts",
+    "delay",
+    "backoff",
+    "max_delay",
+    "jitter",
+    "max_time",
+    "log_level",
+    "budget",
+)
+
+_lock = threading.RLock()
+_state: dict[str, Any] = {}
+
+
+def _hint(name: str, valid: tuple[str, ...], what: str) -> TypeError:
+    close = difflib.get_close_matches(name, valid, n=1)
+    tip = f" Did you mean {close[0]!r}?" if close else ""
+    return TypeError(f"Unknown {what} {name!r}.{tip} Valid: {', '.join(valid)}.")
+
+
+def _names(value: Any, key: str) -> tuple[str, ...]:
+    if isinstance(value, str) or not isinstance(value, Iterable):
+        raise TypeError(f"{key} must be an iterable of strings, got {value!r}")
+    names = tuple(value)
+    if not all(isinstance(n, str) for n in names):
+        raise TypeError(f"{key} must contain only strings, got {value!r}")
+    return names
+
+
+def _validate(key: str, value: Any) -> Any:
+    if key == "logger":
+        if value is not None and not isinstance(value, (str, logging.Logger)):
+            raise TypeError(f"logger must be a logging.Logger, a name or None, got {value!r}")
+        return value
+    if key == "retry":
+        if not isinstance(value, Mapping):
+            raise TypeError(f"retry must be a mapping of retry defaults, got {value!r}")
+        for name in value:
+            if name not in _RETRY_KEYS:
+                raise _hint(str(name), _RETRY_KEYS, "retry default")
+        # Imported here to avoid an import cycle.
+        from python_wrap.retry import _check_budget
+        from python_wrap.retry import _validate as validate_retry
+
+        _check_budget(value.get("budget"))
+        validate_retry(
+            value.get("max_attempts", 3),
+            value.get("delay", 1.0),
+            value.get("backoff", 1.0),
+            value.get("max_delay"),
+            value.get("jitter", 0.0),
+            value.get("max_time"),
+        )
+        return dict(value)
+    if key == "redact":
+        return None if value is None else _names(value, "redact")
+    return _names(value, "redact_extra")
+
+
+def configure(**defaults: Any) -> None:
+    """Set project-wide defaults for python-wrap decorators.
+
+    Call it once at start-up, before decorating: values are read when a decorator is
+    applied, so decorators applied earlier keep their settings. Keys not mentioned keep
+    their current value; each key you pass replaces that key entirely (`retry={...}`
+    replaces the previous retry defaults). Explicit decorator arguments always win.
+
+    Args:
+        **defaults: Any of:
+
+            - `logger`: logger (or name) used by every decorator that logs when it
+              is not given `logger=`. `None` restores the package logger.
+            - `retry`: dict of defaults for `retry`/`retrying`; keys `max_attempts`,
+              `delay`, `backoff`, `max_delay`, `jitter`, `max_time`, `log_level`,
+              `budget` (a `RetryBudget` shared by every retry applied afterwards).
+            - `redact`: default redaction fragments for `log_args` and `audit`
+              (replaces `DEFAULT_REDACT`); `None` restores it.
+            - `redact_extra`: fragments added to the redaction list (the built-ins
+              stay), for `log_args` and `audit`.
+
+    Raises:
+        TypeError: For an unknown key (with a "did you mean" hint) or a wrongly typed value
+            (including a `budget` that is not a `RetryBudget`).
+        ValueError: If a retry default is out of range.
+
+    Example:
+        ```python
+        import logging
+        from python_wrap.config import configure, reset_config
+
+        configure(logger=logging.getLogger("app"), retry={"max_attempts": 5, "delay": 0.5})
+        reset_config()
+        ```
+    """
+    for key in defaults:
+        if key not in _KEYS:
+            raise _hint(key, _KEYS, "configuration key")
+    clean = {k: _validate(k, v) for k, v in defaults.items()}
+    with _lock:
+        _state.update(clean)
+        if "logger" in clean:
+            _core._default_logger = clean["logger"]
+
+
+def get_config() -> dict[str, Any]:
+    """Return a copy of the current configuration.
+
+    Returns:
+        A dict with keys `logger`, `retry`, `redact` and `redact_extra`, holding the
+        defaults in force (`None`, `{}`, `None` and `()` when nothing is configured).
+
+    Example:
+        ```python
+        from python_wrap.config import get_config
+
+        assert get_config()["retry"] == {}
+        ```
+    """
+    with _lock:
+        return {
+            "logger": _state.get("logger"),
+            "retry": dict(_state.get("retry", {})),
+            "redact": _state.get("redact"),
+            "redact_extra": _state.get("redact_extra", ()),
+        }
+
+
+def reset_config() -> None:
+    """Forget every configured default, restoring the built-in behaviour.
+
+    Example:
+        ```python
+        from python_wrap.config import configure, get_config, reset_config
+
+        configure(retry={"max_attempts": 9})
+        reset_config()
+        assert get_config()["retry"] == {}
+        ```
+    """
+    with _lock:
+        _state.clear()
+        _core._default_logger = None
+
+
+@contextlib.contextmanager
+def configured(**defaults: Any) -> Iterator[None]:
+    """Apply `configure(**defaults)` for a `with` block, then restore the previous state.
+
+    Meant for tests. Remember that decorators read the defaults when applied, so apply
+    them inside the block.
+
+    Args:
+        **defaults: Same keys as `configure`.
+
+    Example:
+        ```python
+        from python_wrap.config import configured, get_config
+
+        with configured(retry={"max_attempts": 2}):
+            assert get_config()["retry"] == {"max_attempts": 2}
+        assert get_config()["retry"] == {}
+        ```
+    """
+    with _lock:
+        saved = dict(_state)
+        configure(**defaults)
+    try:
+        yield
+    finally:
+        with _lock:
+            _state.clear()
+            _state.update(saved)
+            _core._default_logger = saved.get("logger")
+
+
+def retry_default(name: str, value: Any, fallback: Any) -> Any:
+    """Resolve a retry argument: explicit value, else configured default, else `fallback`."""
+    if value is not UNSET:
+        return value
+    with _lock:
+        retry_defaults: dict[str, Any] = _state.get("retry", {})
+        return retry_defaults.get(name, fallback)
+
+
+def redaction(explicit: Iterable[str] | None, builtin: tuple[str, ...]) -> tuple[str, ...]:
+    """Final redaction fragments: explicit list or configured/built-in, plus `redact_extra`."""
+    with _lock:
+        base: tuple[str, ...] | None = _state.get("redact")
+        extra: tuple[str, ...] = _state.get("redact_extra", ())
+    chosen = tuple(explicit) if explicit is not None else (builtin if base is None else base)
+    return chosen + extra

python_wrap/deadline.py

@@ -0,0 +1,168 @@
+"""Deadlines: one time budget shared by every call inside a block.
+
+`deadline(seconds)` records an absolute point in time in a `contextvars.ContextVar`,
+so it follows the code it wraps across function calls, `await`s and tasks created
+inside the block (each task copies the context it was created in). Inner code asks
+`remaining()` how much time is left, or calls `check()` to fail fast once it is gone.
+
+A deadline is cooperative: it never interrupts anything by itself. The toolkit's
+`timeout` (decorator or context manager) clamps its own limit to the remaining deadline,
+so a `timeout(30)` inside `deadline(5)` gives up after at most 5 seconds. Your own code
+can do the same, e.g. pass `remaining()` as an HTTP client timeout.
+
+Nested deadlines never extend an outer one: the earliest wins.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from types import TracebackType
+
+from python_wrap import _core
+from python_wrap.errors import TimeoutExpired
+
+__all__ = ["Deadline", "check", "deadline", "remaining"]
+
+# (absolute expiry on the ``_core.monotonic()`` clock, seconds the setting block asked for)
+_current: contextvars.ContextVar[tuple[float, float] | None] = contextvars.ContextVar(
+    "python_wrap_deadline", default=None
+)
+
+
+class Deadline:
+    """A time budget for a block of code; create it with `deadline`.
+
+    Use as `with deadline(5):` or `async with deadline(5):`. Entering computes the
+    absolute expiry; if an enclosing deadline expires sooner, that one stays in force.
+    One instance may be entered several times, but each `with` must exit in the reverse
+    order of entering (as `with` blocks naturally do in one thread or task).
+
+    Attributes:
+        seconds: The budget this deadline was created with.
+    """
+
+    def __init__(self, seconds: float) -> None:
+        if seconds < 0:
+            raise ValueError(f"deadline seconds must be >= 0, got {seconds!r}")
+        self.seconds = seconds
+        self._tokens: list[contextvars.Token[tuple[float, float] | None]] = []
+
+    @property
+    def expires_at(self) -> float | None:
+        """The effective expiry (on the `_core.monotonic()` clock) in the current context.
+
+        `None` when no deadline is active here.
+        """
+        current = _current.get()
+        return None if current is None else current[0]
+
+    def __enter__(self) -> Deadline:
+        expiry = _core.monotonic() + self.seconds
+        outer = _current.get()
+        # An enclosing deadline that comes first stays in force.
+        keep_outer = outer is not None and outer[0] <= expiry
+        value = outer if keep_outer and outer is not None else (expiry, self.seconds)
+        self._tokens.append(_current.set(value))
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        _current.reset(self._tokens.pop())
+
+    async def __aenter__(self) -> Deadline:
+        return self.__enter__()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.__exit__(exc_type, exc, tb)
+
+    def __repr__(self) -> str:
+        return f"Deadline(seconds={self.seconds!r}, remaining={remaining()!r})"
+
+
+def deadline(seconds: float) -> Deadline:
+    """Give the enclosed block (and everything it calls) at most ``seconds`` seconds.
+
+    The deadline is stored in a context variable, so it is visible to every function
+    called inside the block, sync or async, and to tasks started from it. Nesting never
+    extends time: an inner `deadline(10)` inside `deadline(2)` still ends after 2 seconds.
+
+    Nothing is interrupted automatically. `timeout` clamps to the remaining time, and
+    your code can call `remaining()` or `check()`.
+
+    Args:
+        seconds: The budget in seconds (>= 0).
+
+    Returns:
+        A `Deadline` to use with `with` or `async with`.
+
+    Raises:
+        ValueError: If ``seconds`` is negative.
+
+    Example:
+        ```python
+        from python_wrap.deadline import deadline, remaining
+
+        assert remaining() is None
+        with deadline(5):
+            with deadline(60):  # cannot extend the outer budget
+                left = remaining()
+                assert left is not None and left <= 5
+        assert remaining() is None
+        ```
+    """
+    return Deadline(seconds)
+
+
+def remaining() -> float | None:
+    """Seconds left before the current deadline, or `None` if there is none.
+
+    Never negative: an expired deadline reports `0.0`.
+
+    Returns:
+        The remaining time in seconds, or `None` outside any `deadline` block.
+
+    Example:
+        ```python
+        from python_wrap.deadline import deadline, remaining
+
+        with deadline(2):
+            budget = remaining()  # e.g. pass as an HTTP client timeout
+            assert budget is not None and 0 < budget <= 2
+        ```
+    """
+    current = _current.get()
+    if current is None:
+        return None
+    return max(current[0] - _core.monotonic(), 0.0)
+
+
+def check() -> None:
+    """Raise `TimeoutExpired` if the current deadline has passed; otherwise do nothing.
+
+    Call it between steps of a long job to stop as soon as the budget is gone.
+
+    Raises:
+        TimeoutExpired: The deadline has passed. Its ``seconds`` is the budget of the
+            `deadline` block that set it.
+
+    Example:
+        ```python
+        from python_wrap.deadline import check, deadline
+
+        with deadline(5):
+            for step in range(3):
+                check()  # raises TimeoutExpired once the 5 seconds are used up
+        ```
+    """
+    current = _current.get()
+    if current is not None and _core.monotonic() >= current[0]:
+        raise TimeoutExpired(f"deadline of {current[1]:g}s has passed", seconds=current[1])

python_wrap/decorators.py

@@ -0,0 +1,7 @@
+"""Compatibility module: v0.1 imported everything from ``python_wrap.decorators``.
+
+New code should import from ``python_wrap`` directly.
+"""
+
+from . import *  # noqa: F403
+from . import __all__ as __all__