python-wrap 0.2.1__py3-none-any.whl

python_wrap/devtools.py

@@ -0,0 +1,385 @@
+"""Developer tools: deprecation warnings, mock data and decorator composition."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import warnings
+from collections.abc import Awaitable, Callable, Iterable
+from typing import Any, TypeVar, cast, overload
+
+from python_wrap import _core
+from python_wrap._core import P, R
+
+F = TypeVar("F", bound=Callable[..., Any])
+T = TypeVar("T")
+
+__all__ = ["compose", "deprecate", "mock_data", "no_debug", "wrap_methods"]
+
+
+def _mark(obj: T, text: str) -> T:
+    """Set the PEP 702 style ``__deprecated__`` attribute."""
+    obj.__deprecated__ = text  # type: ignore[attr-defined]
+    return obj
+
+
+def _message_for(
+    target: Any,
+    message: str | None,
+    since: str | None,
+    removed_in: str | None,
+    alternative: str | None,
+) -> str:
+    """Return an explicit message, or build one from the parts that were given."""
+    if message is not None:
+        return message
+    func = target.__func__ if isinstance(target, (staticmethod, classmethod)) else target
+    text = f"{_core.qualname(func)} is deprecated"
+    if since:
+        text += f" since {since}"
+    if removed_in:
+        text += f" and will be removed in {removed_in}"
+    if alternative:
+        text += f"; use {alternative} instead"
+    return text + "."
+
+
+def _wrap_class(cls: type, text: str, category: type[Warning]) -> type:
+    """Wrap ``__init__`` (or ``__new__``) in place, so the class stays the same object.
+
+    ``__new__`` is wrapped instead when the class has no ``__init__`` of its own but
+    a custom ``__new__`` (``float`` subclasses, ``NamedTuple``...): installing an
+    ``__init__`` there would make ``object.__init__`` reject the arguments.
+    """
+    current_new: Any = cls.__new__
+    use_new = "__init__" not in cls.__dict__ and current_new is not object.__new__
+    if use_new:
+        original_new = current_new
+
+        def warned_new(klass: Any, *args: Any, **kwargs: Any) -> Any:
+            warnings.warn(text, category, stacklevel=2)
+            return original_new(klass, *args, **kwargs)
+
+        warned_new.__name__ = "__new__"
+        warned_new.__qualname__ = f"{cls.__qualname__}.__new__"
+        cls.__new__ = staticmethod(warned_new)  # type: ignore[method-assign,assignment]
+        return _mark(cls, text)
+
+    original_init: Any = cls.__init__  # type: ignore[misc]
+
+    @functools.wraps(original_init)
+    def warned_init(self: Any, *args: Any, **kwargs: Any) -> None:
+        warnings.warn(text, category, stacklevel=2)
+        original_init(self, *args, **kwargs)
+
+    cls.__init__ = warned_init  # type: ignore[misc]
+    return _mark(cls, text)
+
+
+def _wrap_callable(func: Any, text: str, category: type[Warning]) -> Any:
+    """Wrap a plain or async function so each call (or await) warns."""
+    if _core.is_async(func):
+
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            warnings.warn(text, category, stacklevel=2)
+            return await func(*args, **kwargs)
+
+        return _mark(async_wrapper, text)
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        warnings.warn(text, category, stacklevel=2)
+        return func(*args, **kwargs)
+
+    return _mark(wrapper, text)
+
+
+def _wrap(target: Any, text: str, category: type[Warning]) -> Any:
+    """Dispatch on the kind of object being deprecated."""
+    if isinstance(target, (staticmethod, classmethod)):
+        # Keep the descriptor type so the method still binds the same way.
+        return type(target)(_wrap(target.__func__, text, category))
+    if isinstance(target, type):
+        return _wrap_class(target, text, category)
+    return _wrap_callable(target, text, category)
+
+
+@overload
+def deprecate(target: F, /) -> F: ...
+@overload
+def deprecate(
+    message: str | None = None,
+    *,
+    since: str | None = None,
+    removed_in: str | None = None,
+    alternative: str | None = None,
+    category: type[Warning] = DeprecationWarning,
+) -> Callable[[F], F]: ...
+def deprecate(
+    message: str | Callable[..., Any] | None = None,
+    *,
+    since: str | None = None,
+    removed_in: str | None = None,
+    alternative: str | None = None,
+    category: type[Warning] = DeprecationWarning,
+) -> Any:
+    """Mark a function, method, or class as deprecated.
+
+    Every call (or, for ``async def``, every await) emits a warning that points at
+    the caller's line. Classes are changed in place: their ``__init__`` warns, and
+    they stay classes, so ``isinstance`` keeps working.
+
+    Works bare, with a message (the v0.1 form), or with structured parts. The parts
+    are combined into ``"<name> is deprecated since ... and will be removed in ...;
+    use ... instead."``. An explicit ``message`` replaces that generated text.
+
+    Args:
+        message: Full warning text. Replaces the generated text when given.
+        since: Version in which the deprecation started.
+        removed_in: Version in which the target will be removed.
+        alternative: Name of the replacement to use instead.
+        category: Warning class to emit.
+
+    Returns:
+        The decorated object when used bare, otherwise a decorator.
+
+    Example:
+        ```python
+        @deprecate(since="0.2", removed_in="1.0", alternative="new_func")
+        def old_func() -> None: ...
+
+        @deprecate("Use Widget2 instead")
+        class Widget: ...
+        ```
+    """
+    if callable(message):
+        text = _message_for(message, None, since, removed_in, alternative)
+        return _wrap(message, text, category)
+
+    def decorate(target: Any) -> Any:
+        text = _message_for(target, message, since, removed_in, alternative)
+        return _wrap(target, text, category)
+
+    return decorate
+
+
+def mock_data(data: Any, *, enabled: bool | Callable[[], bool] = True) -> Callable[[F], F]:
+    """Replace a function's result with fixed data, for tests and local runs.
+
+    When enabled, the wrapped function is not called and ``data`` is returned. If
+    ``data`` is callable it is called on each call and its result is returned, so use
+    ``lambda: fn`` to return a callable itself. When disabled, the real function runs.
+
+    Args:
+        data: Value to return, or a zero-argument callable producing it.
+        enabled: ``True``/``False``, or a zero-argument callable that returns one.
+            It is evaluated on every call, so it can read an environment variable.
+
+    Returns:
+        A decorator that works on plain and ``async def`` functions.
+
+    Example:
+        ```python
+        @mock_data({"id": 1}, enabled=lambda: os.environ.get("MOCK") == "1")
+        def fetch_user(user_id: int) -> dict[str, int]: ...
+        ```
+    """
+
+    def decorate(func: Callable[P, R]) -> Callable[P, R]:
+        if _core.is_async(func):
+            async_func = cast("Callable[P, Awaitable[Any]]", func)
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
+                if _is_enabled(enabled):
+                    return _mock_value(data)
+                return await async_func(*args, **kwargs)
+
+            return cast("Callable[P, R]", async_wrapper)
+
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
+            if _is_enabled(enabled):
+                return _mock_value(data)
+            return func(*args, **kwargs)
+
+        return cast("Callable[P, R]", wrapper)
+
+    return cast("Callable[[F], F]", decorate)
+
+
+def _is_enabled(enabled: bool | Callable[[], bool]) -> bool:
+    return enabled() if callable(enabled) else enabled
+
+
+def _mock_value(data: Any) -> Any:
+    return data() if callable(data) else data
+
+
+@overload
+def no_debug(func: F, /) -> F: ...
+@overload
+def no_debug(func: None = None, /) -> Callable[[F], F]: ...
+def no_debug(func: Callable[..., Any] | None = None, /) -> Any:
+    """Deprecated no-op, kept only so v0.1 code keeps importing.
+
+    It returns the function unchanged and emits a ``DeprecationWarning`` when applied.
+    It will be removed in 0.3. To hide debug output, configure logging levels instead.
+
+    Args:
+        func: The function to return unchanged. Omit it to get a decorator.
+
+    Returns:
+        ``func`` itself, or an identity decorator when ``func`` is omitted.
+
+    Example:
+        ```python
+        @no_debug  # warns: removed in 0.3, use logging levels instead
+        def compute() -> int:
+            return 1
+        ```
+    """
+    warnings.warn(
+        "no_debug() does nothing and will be removed in 0.3; "
+        "configure logging levels instead (see logging.Logger.setLevel).",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if func is None:
+
+        def decorate(target: F) -> F:
+            return target
+
+        return decorate
+    return func
+
+
+def compose(*decorators: Callable[[Any], Any]) -> Callable[[F], F]:
+    """Combine decorators into one, applied as if stacked from top to bottom.
+
+    ``compose(a, b, c)(f)`` is the same as ``a(b(c(f)))``. With no decorators it
+    returns the function unchanged.
+
+    Args:
+        *decorators: Decorators to combine, outermost first.
+
+    Returns:
+        A single decorator that applies all of them.
+
+    Raises:
+        TypeError: If any argument is not callable.
+
+    Example:
+        ```python
+        @compose(deprecate("old api"), mock_data(7))
+        def value() -> int:
+            return 1
+        ```
+    """
+    for index, decorator in enumerate(decorators):
+        if not callable(decorator):
+            raise TypeError(
+                f"compose() arguments must be callable; argument {index} is {decorator!r}"
+            )
+
+    def decorate(func: F) -> F:
+        result: Any = func
+        for decorator in reversed(decorators):
+            result = decorator(result)
+        return cast(F, result)
+
+    return decorate
+
+
+C = TypeVar("C", bound=type)
+
+
+def _is_dunder(name: str) -> bool:
+    return name.startswith("__") and name.endswith("__")
+
+
+def wrap_methods(
+    *decorators: Callable[[Any], Any],
+    include: Iterable[str] | Callable[[str], bool] | None = None,
+    exclude: Iterable[str] | Callable[[str], bool] | None = None,
+    include_private: bool = False,
+) -> Callable[[C], C]:
+    """Class decorator that applies decorators to the methods of a class.
+
+    Decorators are given outermost first, like `compose`; a `Policy` works too.
+    Plain, ``async def``, static and class methods are all handled: the underlying
+    function is decorated and re-wrapped in ``staticmethod``/``classmethod``. Only
+    methods defined on the class itself are touched, not inherited ones.
+
+    By default dunder methods, names starting with ``_`` and properties are skipped.
+    Naming one in `include` (a collection of names, not a predicate) opts it in;
+    for a property, the getter, setter and deleter are all decorated.
+
+    Args:
+        *decorators: Decorators to apply, outermost first.
+        include: Names (or a predicate on the name) to restrict the selection to.
+            ``None`` selects every eligible method.
+        exclude: Names (or a predicate) to leave alone. Wins over `include`.
+        include_private: Also select single-underscore names such as ``_helper``.
+
+    Returns:
+        A class decorator that modifies and returns the same class.
+
+    Raises:
+        TypeError: If any decorator is not callable.
+
+    Example:
+        ```python
+        @wrap_methods(retry(max_attempts=3, on=ConnectionError), exclude=["close"])
+        class Client:
+            def get(self, url: str) -> str: ...
+            def close(self) -> None: ...
+        ```
+    """
+    for index, decorator in enumerate(decorators):
+        if not callable(decorator):
+            raise TypeError(
+                f"wrap_methods() arguments must be callable; argument {index} is {decorator!r}"
+            )
+
+    def matcher(spec: Iterable[str] | Callable[[str], bool]) -> Callable[[str], bool]:
+        if callable(spec):
+            return spec
+        names = {spec} if isinstance(spec, str) else set(spec)
+        return names.__contains__
+
+    explicit: frozenset[str] = frozenset()
+    if include is not None and not callable(include):
+        explicit = frozenset({include} if isinstance(include, str) else include)
+    include_ok = matcher(include) if include is not None else (lambda _n: True)
+    exclude_ok = matcher(exclude) if exclude is not None else (lambda _n: False)
+
+    def decorate_func(func: Any) -> Any:
+        result = func
+        for decorator in reversed(decorators):
+            result = decorator(result)
+        return result
+
+    def decorate(cls: C) -> C:
+        for name, attr in list(vars(cls).items()):
+            if exclude_ok(name) or not include_ok(name):
+                continue
+            named = name in explicit
+            if not named and (_is_dunder(name) or (name.startswith("_") and not include_private)):
+                continue
+            if isinstance(attr, property):
+                if not named:
+                    continue
+                fget, fset, fdel = (
+                    decorate_func(p) if p is not None else None
+                    for p in (attr.fget, attr.fset, attr.fdel)
+                )
+                setattr(cls, name, property(fget, fset, fdel, attr.__doc__))
+            elif isinstance(attr, (staticmethod, classmethod)):
+                setattr(cls, name, type(attr)(decorate_func(attr.__func__)))
+            elif inspect.isfunction(attr):
+                setattr(cls, name, decorate_func(attr))
+        return cls
+
+    return decorate

python_wrap/errors.py

@@ -0,0 +1,86 @@
+"""Exceptions raised by python-wrap.
+
+Every one subclasses `PythonWrapError`. Those with a natural built-in counterpart also
+subclass it (`TimeoutExpired` is a `TimeoutError`, `ValidationError` a `ValueError`,
+`ArgumentTypeError` a `TypeError`), so ``except TimeoutError`` or ``except ValueError``
+keeps working for code written against v0.1.
+"""
+
+from __future__ import annotations
+
+
+class PythonWrapError(Exception):
+    """Base class for every exception this package raises."""
+
+
+class TimeoutExpired(PythonWrapError, TimeoutError):
+    """The wrapped call did not finish within its time limit."""
+
+    def __init__(self, message: str, *, seconds: float) -> None:
+        super().__init__(message)
+        self.seconds = seconds
+
+
+class RateLimitExceeded(PythonWrapError):
+    """The call was rejected because its rate limit is used up."""
+
+    def __init__(self, message: str, *, retry_after: float) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class CircuitOpenError(PythonWrapError):
+    """The circuit breaker is open, so the call was not attempted."""
+
+    def __init__(self, message: str, *, retry_after: float) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class BulkheadFull(PythonWrapError):
+    """A bulkhead is at capacity: its wait queue is full, or waiting for a slot timed out."""
+
+    def __init__(self, message: str, *, name: str | None, max_concurrent: int) -> None:
+        super().__init__(message)
+        self.name = name
+        self.max_concurrent = max_concurrent
+
+
+class ValidationError(PythonWrapError, ValueError):
+    """An argument failed a validator."""
+
+    def __init__(self, message: str, *, parameter: str, value: object) -> None:
+        super().__init__(message)
+        self.parameter = parameter
+        self.value = value
+
+
+class ArgumentTypeError(PythonWrapError, TypeError):
+    """An argument does not match its expected type."""
+
+    def __init__(self, message: str, *, parameter: str, expected: object, value: object) -> None:
+        super().__init__(message)
+        self.parameter = parameter
+        self.expected = expected
+        self.value = value
+
+
+class BatchError(PythonWrapError):
+    """A batch function broke its output contract for this caller's item.
+
+    Raised by ``batch_calls`` when the batch function returns the wrong number of
+    results, a mapping without this item's key, or something that is neither a sequence
+    nor a mapping.
+    """
+
+
+__all__ = [
+    "ArgumentTypeError",
+    "BatchError",
+    "BulkheadFull",
+    "CircuitOpenError",
+    "PythonWrapError",
+    "RateLimitExceeded",
+    "TimeoutExpired",
+    "ValidationError",
+]

python_wrap/events.py

@@ -0,0 +1,161 @@
+"""Observe what python-wrap decorators do: retries, cache hits, circuit changes, ...
+
+Decorators publish `Event` objects to a process-wide list of listeners. With no
+listener registered, publishing costs a single list check. Use `subscribe` (or the
+`listening` context manager) to feed Prometheus, OpenTelemetry, statsd or your logs.
+`EVENT_NAMES` is the catalogue of every event and its fields.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping
+from contextlib import contextmanager
+from types import MappingProxyType
+
+from python_wrap import _core
+from python_wrap._core import Event
+
+__all__ = ["EVENT_NAMES", "Event", "Listener", "filter_events", "listening", "subscribe"]
+
+Listener = Callable[[Event], None]
+
+#: Event name -> description of its ``fields`` (``Event.function`` is the decorated
+#: function's qualified name unless noted). The docs page renders this mapping.
+EVENT_NAMES: Mapping[str, str] = MappingProxyType(
+    {
+        "retry.attempt_failed": (
+            "An attempt failed and another will follow. Fields: attempt (int, 1-based), "
+            "exception (BaseException, or None for a value rejected by retry_if_result), "
+            "next_delay (float seconds before the next attempt)."
+        ),
+        "retry.succeeded": "The call finally succeeded. Fields: attempts (int, total made).",
+        "retry.budget_exhausted": (
+            "A shared RetryBudget refused another retry; the call stops (retry.gave_up "
+            "follows). Fields: attempts (int), exception (BaseException, or None when "
+            "the last attempt returned a value rejected by retry_if_result)."
+        ),
+        "retry.gave_up": (
+            "Attempts were exhausted. Fields: attempts (int), exception (BaseException, or "
+            "None when the last attempt returned a value rejected by retry_if_result)."
+        ),
+        "timeout.expired": "A call exceeded its time limit. Fields: seconds (float, the limit).",
+        "circuit.state_changed": (
+            "A circuit breaker moved between states. function is the breaker name. "
+            "Fields: old (str), new (str): 'closed', 'open' or 'half_open'."
+        ),
+        "circuit.rejected": (
+            "A call was refused because the circuit is open. Fields: retry_after (float seconds)."
+        ),
+        "rate_limit.rejected": (
+            "A call was refused by a rate limiter. Fields: retry_after (float seconds)."
+        ),
+        "rate_limit.waited": (
+            "A call was delayed by a rate limiter. Fields: seconds (float, time waited)."
+        ),
+        "throttle.skipped": "A call was skipped by throttle. No fields.",
+        "cache.hit": "A cached value was returned. No fields.",
+        "cache.miss": "No cached value; the function ran. No fields.",
+        "cache.evicted": "An entry left the cache. Fields: reason (str): 'lru' or 'ttl'.",
+        "cache.stale": (
+            "A stale value was served (stale-while-revalidate) and a background refresh "
+            "started. No fields."
+        ),
+        "cache.refresh_failed": (
+            "A background refresh failed; the stale value is kept. "
+            "Fields: exception (BaseException)."
+        ),
+        "bulkhead.rejected": (
+            "A call was refused because the bulkhead is full. Fields: active (int), waiting (int)."
+        ),
+        "periodic.run": (
+            "A background run of a periodic function finished. function is its name. "
+            "Fields: run (int, 1-based), seconds (float, how long it took)."
+        ),
+        "periodic.failed": (
+            "A background run of a periodic function raised. Fields: run (int), "
+            "exception (BaseException)."
+        ),
+    }
+)
+
+
+def subscribe(listener: Listener) -> Callable[[], None]:
+    """Register ``listener`` to receive every `Event`.
+
+    Listeners run synchronously in the thread that triggered the event, so keep them
+    fast. An exception raised by a listener is logged and swallowed; it never reaches the
+    decorated function. Subscribing the same callable twice delivers each event twice.
+
+    Args:
+        listener: Callable taking one `Event`.
+
+    Returns:
+        A function that removes this registration. Calling it again does nothing.
+
+    Example:
+        >>> seen = []
+        >>> unsubscribe = subscribe(seen.append)
+        >>> unsubscribe()
+    """
+    with _core.listeners_lock:
+        _core.listeners.append(listener)
+    removed = False
+
+    def unsubscribe() -> None:
+        nonlocal removed
+        with _core.listeners_lock:
+            if removed:
+                return
+            removed = True
+            # ``emit`` iterates over a tuple snapshot, so deleting in place is safe.
+            for i, item in enumerate(_core.listeners):
+                if item is listener:
+                    del _core.listeners[i]
+                    break
+
+    return unsubscribe
+
+
+@contextmanager
+def listening(listener: Listener) -> Iterator[Listener]:
+    """Subscribe ``listener`` for the duration of a ``with`` block.
+
+    Args:
+        listener: Callable taking one `Event`.
+
+    Yields:
+        The listener, so ``with listening(events.append) as handler`` works.
+
+    Example:
+        >>> events = []
+        >>> with listening(events.append):
+        ...     pass
+    """
+    unsubscribe = subscribe(listener)
+    try:
+        yield listener
+    finally:
+        unsubscribe()
+
+
+def filter_events(prefix: str | tuple[str, ...], listener: Listener) -> Listener:
+    """Wrap ``listener`` so it only receives events whose name starts with ``prefix``.
+
+    Args:
+        prefix: A name prefix such as ``"retry."``, or a tuple of prefixes.
+        listener: The listener to call for matching events.
+
+    Returns:
+        A new listener; pass it to `subscribe`.
+
+    Example:
+        >>> retries = []
+        >>> unsubscribe = subscribe(filter_events("retry.", retries.append))
+        >>> unsubscribe()
+    """
+
+    def filtered(event: Event) -> None:
+        if event.name.startswith(prefix):
+            listener(event)
+
+    return filtered