python-wrap 0.2.1__py3-none-any.whl

python_wrap/__init__.py

@@ -0,0 +1,272 @@
+"""python-wrap: everyday Python decorators that just work.
+
+Every decorator works on plain functions, ``async def`` functions and methods, keeps
+the wrapped signature for type checkers, and never configures logging for you.
+
+Testing helpers live in ``python_wrap.testing`` and the event catalogue in
+``python_wrap.events``; they are not re-exported here.
+"""
+
+import logging
+
+from .aio import (
+    RaceFailed,
+    amap_iter,
+    gather_limit,
+    map_async,
+    race,
+    run_sync,
+)
+from .batching import (
+    AsyncBatched,
+    Batched,
+    batch_calls,
+)
+from .bulkhead import (
+    Bulkhead,
+    Limited,
+    limit_concurrency,
+)
+from .caching import (
+    CachedProperty,
+    CacheInfo,
+    CacheStore,
+    Memoized,
+    Once,
+    cache,
+    cached_property,
+    invalidate,
+    memoize,
+    once,
+)
+from .circuit import (
+    CircuitBreaker,
+    CircuitProtected,
+    CircuitState,
+    CircuitStats,
+    circuit_breaker,
+)
+from .concurrency import (
+    AsyncDebounced,
+    Debounced,
+    RateLimiter,
+    Timeout,
+    debounce,
+    limiter_of,
+    rate_limit,
+    run_in_thread,
+    singleflight,
+    throttle,
+    timeout,
+)
+from .config import (
+    configure,
+    configured,
+    get_config,
+    reset_config,
+)
+from .deadline import (
+    Deadline,
+    deadline,
+)
+from .devtools import (
+    compose,
+    deprecate,
+    mock_data,
+    no_debug,
+    wrap_methods,
+)
+from .errors import (
+    ArgumentTypeError,
+    BatchError,
+    BulkheadFull,
+    CircuitOpenError,
+    PythonWrapError,
+    RateLimitExceeded,
+    TimeoutExpired,
+    ValidationError,
+)
+from .events import (
+    listening,
+    subscribe,
+)
+from .hedging import (
+    hedge,
+)
+from .logs import (
+    DEFAULT_REDACT,
+    AuditRecord,
+    audit,
+    current_log_context,
+    log_args,
+    log_context,
+    log_return,
+    trace,
+)
+from .metrics import (
+    CallStats,
+    Counted,
+    count_calls,
+)
+from .periodic import (
+    AsyncPeriodic,
+    Periodic,
+    periodic,
+)
+from .policy import (
+    Policy,
+    policy,
+)
+from .retry import (
+    Attempt,
+    RetryBudget,
+    RetryBudgetStats,
+    Retrying,
+    RetryState,
+    RetryStats,
+    fallback,
+    retry,
+    retry_after_header,
+    retry_on_exception,
+    retry_stats,
+    retrying,
+    suppress,
+)
+from .state import (
+    INJECTED,
+    Transaction,
+    current_transaction,
+    require_transaction,
+    revert_on_failure,
+    transactional,
+)
+from .timing import (
+    BenchmarkResult,
+    MemoryRecord,
+    TimingRecord,
+    benchmark,
+    benchmark_async,
+    measure_memory,
+    profile,
+    timing,
+)
+from .validation import (
+    check_type,
+    enforce_types,
+    validate_args,
+)
+
+__version__ = "0.2.1"
+
+# A library must never configure logging; this only silences "no handler" warnings.
+logging.getLogger("python_wrap").addHandler(logging.NullHandler())
+
+__all__ = [
+    "DEFAULT_REDACT",
+    "INJECTED",
+    "ArgumentTypeError",
+    "AsyncBatched",
+    "AsyncDebounced",
+    "AsyncPeriodic",
+    "Attempt",
+    "AuditRecord",
+    "BatchError",
+    "Batched",
+    "BenchmarkResult",
+    "Bulkhead",
+    "BulkheadFull",
+    "CacheInfo",
+    "CacheStore",
+    "CachedProperty",
+    "CallStats",
+    "CircuitBreaker",
+    "CircuitOpenError",
+    "CircuitProtected",
+    "CircuitState",
+    "CircuitStats",
+    "Counted",
+    "Deadline",
+    "Debounced",
+    "Limited",
+    "Memoized",
+    "MemoryRecord",
+    "Once",
+    "Periodic",
+    "Policy",
+    "PythonWrapError",
+    "RaceFailed",
+    "RateLimitExceeded",
+    "RateLimiter",
+    "RetryBudget",
+    "RetryBudgetStats",
+    "RetryState",
+    "RetryStats",
+    "Retrying",
+    "Timeout",
+    "TimeoutExpired",
+    "TimingRecord",
+    "Transaction",
+    "ValidationError",
+    "__version__",
+    "amap_iter",
+    "audit",
+    "batch_calls",
+    "benchmark",
+    "benchmark_async",
+    "cache",
+    "cached_property",
+    "check_type",
+    "circuit_breaker",
+    "compose",
+    "configure",
+    "configured",
+    "count_calls",
+    "current_log_context",
+    "current_transaction",
+    "deadline",
+    "debounce",
+    "deprecate",
+    "enforce_types",
+    "fallback",
+    "gather_limit",
+    "get_config",
+    "hedge",
+    "invalidate",
+    "limit_concurrency",
+    "limiter_of",
+    "listening",
+    "log_args",
+    "log_context",
+    "log_return",
+    "map_async",
+    "measure_memory",
+    "memoize",
+    "mock_data",
+    "no_debug",
+    "once",
+    "periodic",
+    "policy",
+    "profile",
+    "race",
+    "rate_limit",
+    "require_transaction",
+    "reset_config",
+    "retry",
+    "retry_after_header",
+    "retry_on_exception",
+    "retry_stats",
+    "retrying",
+    "revert_on_failure",
+    "run_in_thread",
+    "run_sync",
+    "singleflight",
+    "subscribe",
+    "suppress",
+    "throttle",
+    "timeout",
+    "timing",
+    "trace",
+    "transactional",
+    "validate_args",
+    "wrap_methods",
+]

python_wrap/_core.py

@@ -0,0 +1,212 @@
+"""Shared plumbing for every decorator in the package.
+
+Rules every module follows:
+
+* Never configure logging. Log through `get_logger`; the package logger carries a
+  ``NullHandler`` so nothing is printed unless the application configures logging.
+* Support ``async def`` functions: branch on `is_async` and return an ``async def``
+  wrapper, so ``inspect.iscoroutinefunction(wrapped)`` stays true.
+* Read time through ``_core.monotonic()`` / ``_core.perf_counter()`` and wait through
+  ``_core.sleep()`` / ``_core.async_sleep()`` — always as module attributes, never
+  imported by name — so tests can patch one place to get a fake clock.
+* ``_core.sleep`` / ``_core.async_sleep`` are only for deliberate backoff waits (retry
+  delays, a blocked rate limiter). A limit on how long to wait — a timeout, a deadline
+  for a slot, a hedge delay, a batching or debounce window — runs on real time
+  (``asyncio.timeout`` / ``asyncio.sleep`` timers, ``threading.Timer``, ``wait(timeout=)``
+  and ``time.monotonic()``), so the test overrides and the fake clock never shorten
+  it, and sync and async code behave the same.
+* Honour the process-wide test overrides (see below).
+* Decorated functions pickle by reference (``module.qualname``), so they can be sent to
+  process pools. A decorator that returns an object instead of a function gives it a
+  ``__reduce__`` returning its ``__qualname__``. Objects holding shared runtime state
+  (locks, counters, timers) refuse to pickle through `refuse_pickle`: that state is
+  per process.
+
+Test overrides contract
+-----------------------
+``_core.overrides`` is a single process-wide `Overrides` instance, mutated in
+place (never replaced), so it may be read as ``_core.overrides.<field>`` at any time.
+Reads are plain attribute reads (thread-safe under the GIL); changing it is a test-time
+operation done through `set_overrides` (which holds ``overrides_lock``) or the
+public helpers in `python_wrap.testing`. Modules must read the field **at call
+time**, not at decoration time, so a test can flip it after import:
+
+* ``no_sleep``: `sleep` / `async_sleep` return immediately (the async one
+  still yields to the event loop once). Handled here; other modules need do nothing as
+  long as they wait only through ``_core``. A fake clock installed by ``fake_clock()``
+  replaces the sleeps and so still advances time. A blocking rate limiter that would
+  have to wait lets the call through at once (still counted) instead of spinning.
+* ``max_attempts``: when not ``None``, ``retry`` uses
+  ``min(configured_max_attempts, _core.overrides.max_attempts)`` attempts.
+* ``disable_rate_limits``: when true, rate limiters (``rate_limit``, ``RateLimiter``)
+  and ``throttle`` let every call through immediately. Concurrency limits
+  (``Bulkhead``, ``limit_concurrency``) are not affected.
+* ``disable_caching``: when true, ``memoize`` / ``cache`` / ``once``-style caches
+  neither read nor write their stores and always call the wrapped function.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import logging
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, fields
+from typing import Any, NoReturn, ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+F = TypeVar("F", bound=Callable[..., Any])
+
+LOGGER_NAME = "python_wrap"
+
+LoggerLike = logging.Logger | str | None
+
+# Time sources, patched by tests. Call them as ``_core.monotonic()``.
+monotonic: Callable[[], float] = time.monotonic
+perf_counter: Callable[[], float] = time.perf_counter
+
+
+@dataclass
+class Overrides:
+    """Process-wide switches for tests. See the module docstring for the contract."""
+
+    no_sleep: bool = False
+    max_attempts: int | None = None
+    disable_rate_limits: bool = False
+    disable_caching: bool = False
+
+
+overrides = Overrides()
+overrides_lock = threading.RLock()
+
+
+def set_overrides(**values: Any) -> dict[str, Any]:
+    """Set override fields atomically and return their previous values.
+
+    Raises:
+        TypeError: If a name is not a field of `Overrides`.
+        ValueError: If ``max_attempts`` is not ``None`` or a positive integer.
+    """
+    names = {f.name for f in fields(Overrides)}
+    unknown = set(values) - names
+    if unknown:
+        raise TypeError(f"unknown override(s): {', '.join(sorted(unknown))}")
+    attempts = values.get("max_attempts")
+    if attempts is not None and (not isinstance(attempts, int) or attempts < 1):
+        raise ValueError("max_attempts override must be None or an integer >= 1")
+    with overrides_lock:
+        previous = {name: getattr(overrides, name) for name in values}
+        for name, value in values.items():
+            setattr(overrides, name, value)
+    return previous
+
+
+def sleep(seconds: float) -> None:
+    """Blocking sleep; a no-op while ``overrides.no_sleep`` is set."""
+    if overrides.no_sleep:
+        return
+    time.sleep(seconds)
+
+
+async def async_sleep(seconds: float) -> None:
+    """Indirection over `asyncio.sleep` so tests can patch it.
+
+    While ``overrides.no_sleep`` is set it only yields to the event loop once.
+    """
+    await asyncio.sleep(0 if overrides.no_sleep else seconds)
+
+
+_default_logger: LoggerLike = None
+
+
+def get_logger(logger: LoggerLike = None) -> logging.Logger:
+    """Resolve a ``logger=`` argument: a Logger, a logger name, or the package logger."""
+    if logger is None:
+        logger = _default_logger  # set by python_wrap.config.configure(logger=...)
+    if isinstance(logger, logging.Logger):
+        return logger
+    return logging.getLogger(logger or LOGGER_NAME)
+
+
+def is_async(func: Callable[..., Any]) -> bool:
+    """True if calling ``func`` returns a coroutine.
+
+    Covers ``async def`` functions and methods, ``functools.partial`` objects around
+    them, and callable instances whose class defines ``async def __call__``. A class is
+    never async: calling it constructs an instance, even if the class has an async
+    ``__call__``.
+    """
+    while isinstance(func, functools.partial):
+        func = func.func
+    if inspect.iscoroutinefunction(func):
+        return True
+    if inspect.isclass(func) or inspect.isfunction(func) or inspect.ismethod(func):
+        return False
+    # Look the method up on the type, as the call itself does.
+    call = inspect.getattr_static(type(func), "__call__", None)
+    return call is not None and inspect.iscoroutinefunction(call)
+
+
+def qualname(func: Callable[..., Any]) -> str:
+    """A readable name for log messages."""
+    return getattr(func, "__qualname__", None) or getattr(func, "__name__", None) or repr(func)
+
+
+def refuse_pickle(obj: object, advice: str | None = None) -> NoReturn:
+    """Raise a clear ``TypeError`` from ``__reduce__`` of an object with per-process state.
+
+    Locks, counters and timers cannot be shared with another process, so pickling (and
+    copying) such an object fails here instead of deep inside ``pickle``. ``advice``
+    replaces the default hint for objects that are not used as decorators.
+    """
+    name = type(obj).__name__
+    if advice is None:
+        advice = (
+            f"Create one {name} per process instead (e.g. at module level, so each worker "
+            "builds its own); functions decorated with it pickle by reference."
+        )
+    raise TypeError(
+        f"cannot pickle {name!r} object: its state (locks, counters, timers) belongs to "
+        f"one process. {advice}"
+    )
+
+
+# ---------------------------------------------------------------------------- events
+# One process-wide hook for metrics. Decorators call ``_core.emit(...)`` at interesting
+# moments (a retry, a cache hit, a circuit opening); ``python_wrap.events`` is the public
+# face. With no listener registered, ``emit`` is a single list check.
+
+
+@dataclass(frozen=True)
+class Event:
+    """Something a decorator did, for metrics and tracing.
+
+    Attributes:
+        name: Dotted event name, e.g. ``"retry.attempt_failed"``.
+        function: Qualified name of the decorated function (or the breaker/limiter name).
+        fields: Event-specific data, e.g. ``{"attempt": 2, "next_delay": 0.5}``.
+    """
+
+    name: str
+    function: str
+    fields: dict[str, Any]
+
+
+listeners: list[Callable[[Event], None]] = []
+listeners_lock = threading.Lock()
+
+
+def emit(name: str, function: str, **fields: Any) -> None:
+    """Deliver an event to every listener. A failing listener is logged, never raised."""
+    if not listeners:
+        return
+    event = Event(name, function, fields)
+    for listener in tuple(listeners):
+        try:
+            listener(event)
+        except Exception:
+            get_logger().exception("python_wrap event listener %r failed", listener)