observe-kit 0.1.1__py3-none-any.whl

observe_kit/__init__.py

@@ -0,0 +1,36 @@
+"""@observed: timing, outcome classification, structured logs and events for any call.
+
+    from observe_kit import observed
+
+    class Billing:
+        def __init__(self, log, sink):          # Provider finds these by name
+            self.log, self.sink = log, sink
+
+        @observed("billing.charge", expected=(CardDeclined,), fields=("customer_id",))
+        def charge(self, customer_id: str, cents: int) -> Receipt: ...
+
+Every call emits `billing.charge.finished` (or `.expected`, `.swallowed`, `.raised`) with
+`duration_ms` and `customer_id`, as a structlog line and as an `ObservedEvent` to the sink.
+"""
+
+from .decorator import observed
+from .events import CallOutcome, ObservedEvent
+from .policy import DEFAULT_POLICY, NotifyPolicy
+from .provider import Provider
+from .sinks import EventSink, MemorySink, Notifier, NullNotifier, NullSink
+from .text import withhold_urls
+
+__all__ = [
+    "DEFAULT_POLICY",
+    "CallOutcome",
+    "EventSink",
+    "MemorySink",
+    "Notifier",
+    "NotifyPolicy",
+    "NullNotifier",
+    "NullSink",
+    "ObservedEvent",
+    "Provider",
+    "observed",
+    "withhold_urls",
+]

observe_kit/decorator.py

@@ -0,0 +1,238 @@
+"""The `observed` decorator."""
+
+from __future__ import annotations
+
+import inspect
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from functools import wraps
+from typing import Any, Literal, ParamSpec, TypeVar, cast
+
+from .events import CallOutcome, ObservedEvent
+from .policy import DEFAULT_POLICY, NotifyPolicy
+from .provider import Provider
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+ExcTypes = tuple[type[BaseException], ...]
+
+
+def observed(
+    name: str,
+    *,
+    expected: ExcTypes = (),
+    swallow: ExcTypes = (),
+    default: Any = None,
+    fields: tuple[str, ...] = (),
+    detail: str | None = None,
+    level: Literal["debug", "info"] = "info",
+    notify_policy: NotifyPolicy = DEFAULT_POLICY,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Time a call, classify how it ended, log it and emit an event, on every invocation.
+
+    Args:
+        name: Event root, dotted, e.g. "billing.charge". The outcome is appended:
+            "billing.charge.finished".
+        expected: Exceptions that are a normal part of operating. Logged as a warning and
+            **re-raised** for the caller to handle.
+        swallow: Exceptions that mean "that thing wasn't there". Logged at debug and replaced by
+            `default`. This is how `except Exception: pass` becomes explicit and visible.
+        default: Returned when a `swallow` exception was caught.
+        fields: Argument names to add to the event and the log line, e.g. ("user_id",).
+            Resolved against the signature, so positional and keyword arguments both work.
+        detail: One argument name whose value, as a string, becomes the event's `detail`. It is
+            not added to the context: it is for a later query to read back, not for every log line.
+        level: Log level of the FINISHED outcome. "debug" for chatty inner calls.
+        notify_policy: What a RAISED notification may carry. The default allows no context
+            fields; see `NotifyPolicy`.
+
+    Anything that is an `Exception` and in neither tuple is RAISED: logged as an error with the
+    traceback, sent to the instance's notifier if it has one, and re-raised. A type in both
+    tuples counts as `expected`. `BaseException`s that are not `Exception`s (KeyboardInterrupt,
+    SystemExit, asyncio.CancelledError) pass through untouched unless listed.
+
+    Works on plain and `async def` functions and methods. Generators are refused, because the
+    call returns before the work happens and the timing would be meaningless.
+
+    Collaborators (logger, sink, notifier, context) come from the instance via `Provider`.
+    """
+
+    def decorate(func: Callable[P, R]) -> Callable[P, R]:
+        if inspect.isgeneratorfunction(func) or inspect.isasyncgenfunction(func):
+            raise TypeError(
+                f"@observed({name!r}) cannot wrap generator {func.__qualname__}: the call returns "
+                "before the work happens. Observe the function that consumes it instead."
+            )
+        spec = _Spec(
+            name=name,
+            expected=expected,
+            swallow=swallow,
+            default=default,
+            fields=fields,
+            detail=detail,
+            level=level,
+            policy=notify_policy,
+            sig=inspect.signature(func),
+            module=func.__module__,
+            qualname=f"{func.__module__}.{func.__qualname__}",
+        )
+
+        if inspect.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def awrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
+                call = _Call(spec, args, kwargs)
+                try:
+                    result = await cast(Awaitable[Any], func(*args, **kwargs))
+                except BaseException as exc:
+                    if not call.failed(exc):
+                        raise
+                    return spec.default
+                call.finished()
+                return result
+
+            return cast(Callable[P, R], awrapper)
+
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            call = _Call(spec, args, kwargs)
+            try:
+                result = func(*args, **kwargs)
+            except BaseException as exc:
+                if not call.failed(exc):
+                    raise
+                return cast(R, spec.default)
+            call.finished()
+            return result
+
+        return wrapper
+
+    return decorate
+
+
+class _Spec:
+    """Everything fixed at decoration time."""
+
+    __slots__ = (
+        "name",
+        "expected",
+        "swallow",
+        "default",
+        "fields",
+        "detail",
+        "level",
+        "policy",
+        "sig",
+        "module",
+        "qualname",
+    )
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        expected: ExcTypes,
+        swallow: ExcTypes,
+        default: Any,
+        fields: tuple[str, ...],
+        detail: str | None,
+        level: str,
+        policy: NotifyPolicy,
+        sig: inspect.Signature,
+        module: str,
+        qualname: str,
+    ) -> None:
+        self.name = name
+        self.expected = expected
+        self.swallow = swallow
+        self.default = default
+        self.fields = fields
+        self.detail = detail
+        self.level = level
+        self.policy = policy
+        self.sig = sig
+        self.module = module
+        self.qualname = qualname
+
+
+class _Call:
+    """One invocation: collaborators resolved, clock started. Sync and async share it."""
+
+    __slots__ = ("spec", "args", "log", "sink", "context", "detail", "started")
+
+    def __init__(self, spec: _Spec, args: tuple[Any, ...], kwargs: dict[str, Any]) -> None:
+        self.spec = spec
+        self.args = args
+        self.sink = Provider.sink(args)
+        bound = _bound(spec.sig, args, kwargs)
+        self.context = _context(spec.fields, Provider.context(args), bound)
+        self.detail = _detail(spec.detail, bound)
+        self.log = Provider.logger(args, spec.module).bind(**self.context)
+        self.started = time.perf_counter()
+
+    def finished(self) -> None:
+        ev = self._event(CallOutcome.FINISHED, None)
+        getattr(self.log, self.spec.level)(ev.event, duration_ms=ev.duration_ms)
+        self.sink.emit(ev)
+
+    def failed(self, exc: BaseException) -> bool:
+        """Record `exc`, from inside the `except` block. True when it is swallowed; the caller
+        re-raises otherwise, with a bare `raise`, so the traceback gains no frame from here."""
+        spec = self.spec
+        if isinstance(exc, spec.expected):
+            ev = self._event(CallOutcome.EXPECTED, exc)
+            self.log.warning(ev.event, duration_ms=ev.duration_ms, error=ev.error)
+            self.sink.emit(ev)
+            return False
+        if isinstance(exc, spec.swallow):
+            ev = self._event(CallOutcome.SWALLOWED, exc)
+            self.log.debug(
+                ev.event, duration_ms=ev.duration_ms, error=ev.error, default=spec.default
+            )
+            self.sink.emit(ev)
+            return True
+        if not isinstance(exc, Exception):
+            return False
+        ev = self._event(CallOutcome.RAISED, exc)
+        self.log.error(ev.event, duration_ms=ev.duration_ms, error=ev.error, exc_info=True)
+        self.sink.emit(ev)
+        notifier = Provider.notifier(self.args)
+        if notifier is not None:
+            notifier.error(
+                title=f"{spec.name} raised {type(exc).__name__}",
+                text=spec.policy.text(spec.qualname, ev.error, self.context),
+            )
+        return False
+
+    def _event(self, outcome: CallOutcome, exc: BaseException | None) -> ObservedEvent:
+        # perf_counter, then round: truncating to whole seconds first would report 0 ms for
+        # anything under a second.
+        duration_ms = round((time.perf_counter() - self.started) * 1000)
+        error = f"{type(exc).__name__}: {exc}" if exc is not None else None
+        return ObservedEvent(self.spec.name, outcome, duration_ms, error, self.context, self.detail)
+
+
+def _bound(
+    sig: inspect.Signature, args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> Mapping[str, Any]:
+    """The call's arguments by name, which `fields` and `detail` are resolved against."""
+    try:
+        return sig.bind_partial(*args, **kwargs).arguments
+    except TypeError:  # the call itself is malformed; let func() raise the real error
+        return {}
+
+
+def _context(
+    fields: tuple[str, ...], base: Mapping[str, object], bound: Mapping[str, Any]
+) -> dict[str, object]:
+    ctx: dict[str, object] = dict(base)
+    for f in fields:
+        if f in bound:
+            ctx[f] = bound[f]
+    return ctx
+
+
+def _detail(name: str | None, bound: Mapping[str, Any]) -> str | None:
+    value = bound.get(name) if name is not None else None
+    return None if value is None else str(value)

observe_kit/events.py

@@ -0,0 +1,48 @@
+"""What one observed call produced."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class CallOutcome(StrEnum):
+    """How a call ended. Exactly one per call."""
+
+    FINISHED = "finished"  # returned normally
+    EXPECTED = "expected"  # listed in `expected`: warned, re-raised
+    SWALLOWED = "swallowed"  # listed in `swallow`: debug-logged, `default` returned
+    RAISED = "raised"  # any other Exception: error + traceback, notified, re-raised
+
+    @property
+    def level(self) -> str:
+        """The log level this outcome is written at (FINISHED's can be lowered per call)."""
+        return _LEVELS[self]
+
+
+_LEVELS: dict[CallOutcome, str] = {
+    CallOutcome.FINISHED: "info",
+    CallOutcome.EXPECTED: "warning",
+    CallOutcome.SWALLOWED: "debug",
+    CallOutcome.RAISED: "error",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ObservedEvent:
+    """One call, as the sink receives it."""
+
+    name: str  # the decorator's name, e.g. "billing.charge"
+    outcome: CallOutcome
+    duration_ms: int
+    error: str | None = None  # "TypeName: message" when the call did not finish
+    context: Mapping[str, object] = field(default_factory=dict)  # observe_context + `fields`
+    # The value of the argument `observed(detail=...)` names, as a string. For a call whose
+    # event a later query reads back, not for log lines: it is not part of `context`.
+    detail: str | None = None
+
+    @property
+    def event(self) -> str:
+        """The log event name: `<name>.<outcome>`."""
+        return f"{self.name}.{self.outcome}"

observe_kit/policy.py

@@ -0,0 +1,63 @@
+"""What a RAISED notification may carry.
+
+A notification leaves the process: it lands on a phone, in a chat channel, in somebody's inbox.
+The log line and the event keep the whole context and the whole error; the notification's job
+is "something is wrong, come and look", and it carries only what the policy allows.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from .text import withhold_urls
+
+
+@dataclass(frozen=True, slots=True)
+class NotifyPolicy:
+    """Which context fields travel, and how the error is cut down.
+
+    Args:
+        fields: Context names allowed into the message. An **allow**-list: `fields=` is chosen
+            per call site, so a deny-list would have to grow with every new argument, and
+            forgetting one would leak it. The default allows none.
+        withheld_hint: Where to find what was withheld, e.g. "see logs/app.jsonl". Appended to
+            the count of withheld fields.
+
+    The error is always cut to its first line, with URLs withheld (`withhold_urls`), and the
+    message says how many lines and fields it left out, so a policy that is too narrow shows up
+    as a number instead of as a call that seemed to have no context.
+    """
+
+    fields: frozenset[str] = frozenset()
+    withheld_hint: str = "see the log"
+
+    def context(self, context: Mapping[str, object]) -> str:
+        """The allowed `key=value` pairs, plus a count of the rest."""
+        kept = " ".join(f"{k}={v}" for k, v in context.items() if k in self.fields)
+        withheld = sum(1 for key in context if key not in self.fields)
+        if not withheld:
+            return kept
+        note = f"({withheld} field(s) withheld — {self.withheld_hint})"
+        return f"{kept} {note}" if kept else note
+
+    def error(self, error: str | None) -> str:
+        """The first line of the error with URLs withheld, plus a count of the dropped lines.
+
+        Only the first line, because libraries append their own detail below it (Playwright's
+        `Call log:`, a server's response body) and that is where identifiers tend to be. URLs are
+        taken out of the line that is kept, because some errors put them in the first line.
+        """
+        if not error:
+            return ""
+        first, _, rest = error.partition("\n")
+        line = withhold_urls(first).rstrip()
+        dropped = len(rest.splitlines()) if rest else 0
+        return f"{line} (+{dropped} line(s) withheld)" if dropped else line
+
+    def text(self, qualname: str, error: str | None, context: Mapping[str, object]) -> str:
+        """The notification body: where it raised, what it raised, the allowed context."""
+        return f"{qualname}\n{self.error(error)}\n{self.context(context)}"
+
+
+DEFAULT_POLICY = NotifyPolicy()

observe_kit/provider.py

@@ -0,0 +1,51 @@
+"""Find the collaborators `observed` needs on the decorated method's instance, or default.
+
+Convention over wiring: if the object the method was called on has a `.log`, `.sink`,
+`.notifier` or `.observe_context` of the right shape, it is used. Otherwise a module logger, no
+sink, no notifier, no context. Plain functions always get the defaults.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import structlog
+
+from .sinks import EventSink, Notifier, NullSink
+
+
+class Provider:
+    @staticmethod
+    def _self(args: tuple[Any, ...]) -> Any | None:
+        return args[0] if args else None
+
+    @staticmethod
+    def logger(args: tuple[Any, ...], default_name: str) -> Any:
+        """The instance's `.log` if it has a `bind` method, else a module structlog logger."""
+        log = getattr(Provider._self(args), "log", None)
+        if log is not None and callable(getattr(log, "bind", None)):
+            return log
+        return structlog.get_logger(default_name)
+
+    @staticmethod
+    def sink(args: tuple[Any, ...]) -> EventSink:
+        """The instance's `.sink` if it has an `emit` method, else a NullSink."""
+        sink = getattr(Provider._self(args), "sink", None)
+        if sink is not None and callable(getattr(sink, "emit", None)):
+            return sink  # type: ignore[no-any-return]
+        return NullSink()
+
+    @staticmethod
+    def notifier(args: tuple[Any, ...]) -> Notifier | None:
+        """The instance's `.notifier` if it has an `error` method, else None."""
+        notifier = getattr(Provider._self(args), "notifier", None)
+        if notifier is not None and callable(getattr(notifier, "error", None)):
+            return notifier  # type: ignore[no-any-return]
+        return None
+
+    @staticmethod
+    def context(args: tuple[Any, ...]) -> Mapping[str, object]:
+        """Fields bound to every event from this instance, e.g. {"run_id": ...}."""
+        ctx = getattr(Provider._self(args), "observe_context", None)
+        return ctx if isinstance(ctx, Mapping) else {}

observe_kit/sinks.py

@@ -0,0 +1,57 @@
+"""Where events go, and who is told when a call raises something unexpected.
+
+Both are Protocols: anything with the right method satisfies them, without importing this
+package.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from .events import ObservedEvent
+
+
+@runtime_checkable
+class EventSink(Protocol):
+    """Receives every event: a metrics client, a database table, a queue, a list in a test."""
+
+    def emit(self, event: ObservedEvent) -> None: ...
+
+
+@runtime_checkable
+class Notifier(Protocol):
+    """Told about RAISED outcomes only: chat, e-mail, a pager.
+
+    `observed` calls `error(title=..., text=...)` by keyword. A notifier with a richer
+    signature (extra keyword-only arguments with defaults) still satisfies this.
+    """
+
+    def error(self, title: str, text: str) -> None: ...
+
+
+class NullSink:
+    """Drops every event. What a call gets when its instance has no `.sink`."""
+
+    def emit(self, event: ObservedEvent) -> None:
+        return None
+
+
+class NullNotifier:
+    """Tells nobody."""
+
+    def error(self, title: str, text: str) -> None:
+        return None
+
+
+class MemorySink:
+    """Keeps every event in a list. For tests, and for inspecting a run afterwards."""
+
+    def __init__(self) -> None:
+        self.events: list[ObservedEvent] = []
+
+    def emit(self, event: ObservedEvent) -> None:
+        self.events.append(event)
+
+    def named(self, name: str) -> list[ObservedEvent]:
+        """The events of one decorated call, oldest first."""
+        return [e for e in self.events if e.name == name]

observe_kit/text.py

@@ -0,0 +1,19 @@
+"""Taking URLs out of a string before it leaves the process."""
+
+from __future__ import annotations
+
+import re
+
+URL_RE = re.compile(r"\bhttps?://\S+", re.IGNORECASE)
+WITHHELD_URL = "<url withheld>"
+
+
+def withhold_urls(text: str) -> str:
+    """Replace every URL-shaped run with `<url withheld>`, whole.
+
+    Deliberately blunt: a URL can carry an identifier, a signed query string or a token, and it
+    can come back truncated or re-encoded inside somebody else's error message, so it is not
+    matched against a known secret. A URL in a message a human reads adds nothing they could act
+    on anyway.
+    """
+    return URL_RE.sub(WITHHELD_URL, text)

observe_kit-0.1.1.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: observe-kit
+Version: 0.1.1
+Summary: @observed: one decorator that times a call, classifies how it ended, logs it and emits an event.
+Project-URL: Homepage, https://github.com/MdaaaaO/observe-kit
+Project-URL: Changelog, https://github.com/MdaaaaO/observe-kit/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/MdaaaaO/observe-kit/issues
+Author: Georg Kasper
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: decorator,events,logging,metrics,observability,structlog
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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 :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: structlog>=24.1
+Description-Content-Type: text/markdown
+
+# observe-kit
+
+[![PyPI](https://img.shields.io/pypi/v/observe-kit)](https://pypi.org/project/observe-kit/)
+[![Python](https://img.shields.io/pypi/pyversions/observe-kit)](https://pypi.org/project/observe-kit/)
+[![CI](https://github.com/MdaaaaO/observe-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/MdaaaaO/observe-kit/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/MdaaaaO/observe-kit/python-coverage-comment-action-data/badge.svg)](https://github.com/MdaaaaO/observe-kit/tree/python-coverage-comment-action-data)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
+
+One decorator, `@observed`, that times a call, decides how it ended, writes a
+[structlog](https://www.structlog.org) line and emits an event to a sink you choose. It works on
+plain and `async def` functions and methods. Its only dependency is structlog.
+
+```console
+pip install observe-kit
+```
+
+```python
+from observe_kit import observed
+
+
+class Billing:
+    def __init__(self, log, sink, notifier):
+        self.log, self.sink, self.notifier = log, sink, notifier
+
+    @observed("billing.charge", expected=(CardDeclined,), fields=("customer_id",))
+    def charge(self, customer_id: str, cents: int) -> Receipt: ...
+```
+
+Each call to `charge` then produces one log line and one event:
+
+```text
+billing.charge.finished   customer_id=c_42 duration_ms=183
+billing.charge.expected   customer_id=c_42 duration_ms=95  error="CardDeclined: insufficient funds"
+```
+
+## Four outcomes
+
+Every call ends in exactly one of them. You decide which exceptions are which, so there is no
+bare `except Exception: pass` anywhere in your code.
+
+| outcome | when | logged at | then |
+|---|---|---|---|
+| `finished` | the call returned | info (`level="debug"` for chatty calls) | the value is returned |
+| `expected` | raised one of `expected=` | warning | re-raised for the caller |
+| `swallowed` | raised one of `swallow=` | debug | `default=` is returned |
+| `raised` | raised any other `Exception` | error, with traceback | the notifier is told, then re-raised |
+
+A type listed in both `expected` and `swallow` counts as expected. `BaseException`s that are not
+`Exception`s (`KeyboardInterrupt`, `SystemExit`, `asyncio.CancelledError`) pass through untouched
+unless you list them. The re-raise is a bare `raise`, so tracebacks gain no frame from the decorator.
+
+## Arguments
+
+```python
+@observed(
+    "orders.ship",              # event root; the outcome is appended: orders.ship.finished
+    expected=(OutOfStock,),     # normal operation, re-raised
+    swallow=(KeyError,),        # "it wasn't there", replaced by default
+    default=None,
+    fields=("order_id",),       # argument names added to the log line and the event
+    detail="carrier",           # one argument kept as a string on the event, not in the log context
+    level="info",               # log level of `finished`
+    notify_policy=POLICY,       # what a `raised` notification may carry (below)
+)
+```
+
+`fields` and `detail` are resolved against the signature, so positional and keyword arguments both
+work. `duration_ms` is measured with `perf_counter` and, for `async def`, covers the whole await.
+Generators are refused at decoration time: the call returns before any work happens, so the timing
+would mean nothing. Decorate the function that consumes the generator instead.
+
+## Where the logger, sink and notifier come from
+
+`observed` looks at the first argument (`self` for a method) for these attributes, and falls back
+to a default when one is missing or has the wrong shape:
+
+| attribute | expected shape | fallback |
+|---|---|---|
+| `log` | a structlog logger (has `.bind`) | `structlog.get_logger(module)` |
+| `sink` | an `EventSink`: `emit(event)` | `NullSink`, which drops events |
+| `notifier` | a `Notifier`: `error(title, text)` | none; nobody is told |
+| `observe_context` | a mapping, e.g. `{"run_id": 7}` | `{}` |
+
+`observe_context` is bound onto every log line and event from that instance. Plain functions get
+the fallbacks, so `@observed` on a module-level function just logs.
+
+## Events and sinks
+
+Each outcome becomes an `ObservedEvent`:
+
+```python
+ObservedEvent(
+    name="billing.charge",
+    outcome=CallOutcome.EXPECTED,
+    duration_ms=95,
+    error="CardDeclined: insufficient funds",  # None when finished
+    context={"customer_id": "c_42"},
+    detail=None,
+)
+event.event  # "billing.charge.expected"
+```
+
+A sink is anything with `emit(event)`. Write one that increments a Prometheus counter, inserts a
+row into a table, or pushes to a queue:
+
+```python
+class CountingSink:
+    def __init__(self, counter):
+        self.counter = counter
+
+    def emit(self, event):
+        self.counter.labels(event.name, event.outcome).inc()
+```
+
+## Testing with MemorySink
+
+`MemorySink` keeps every event in a list, so tests assert on what happened instead of parsing logs:
+
+```python
+from observe_kit import CallOutcome, MemorySink
+
+
+def test_declined_card_is_expected():
+    sink = MemorySink()
+    billing = Billing(log=structlog.get_logger(), sink=sink, notifier=None)
+
+    with pytest.raises(CardDeclined):
+        billing.charge("c_42", 500)
+
+    [event] = sink.named("billing.charge")
+    assert event.outcome is CallOutcome.EXPECTED
+```
+
+## Notifications and NotifyPolicy
+
+On `raised`, the instance's notifier gets a title (`"billing.charge raised TimeoutError"`) and a
+short text. Alerts end up in chat apps, phones and mailboxes, so the text is deliberately thin:
+
+- only context fields you allow travel; the rest are counted, never shown;
+- only the first line of the error travels; the lines after it are counted;
+- URLs in that line are replaced by `<url withheld>`.
+
+The default policy allows no fields. Set your own once and pass it where you decorate:
+
+```python
+from functools import partial
+from observe_kit import NotifyPolicy, observed as _observed
+
+POLICY = NotifyPolicy(
+    fields=frozenset({"run_id", "count", "duration_ms"}),
+    withheld_hint="see logs/app.jsonl",
+)
+observed = partial(_observed, notify_policy=POLICY)
+```
+
+```text
+billing.charge raised TimeoutError
+
+app.billing.Billing.charge
+TimeoutError: Page.goto: Timeout 30000ms exceeded. (+2 line(s) withheld)
+run_id=7 (1 field(s) withheld — see logs/app.jsonl)
+```
+
+The full error, traceback and context are still in the log line and the event; only the
+notification is trimmed.
+
+## Lineage
+
+observe-kit is a rewrite of [atlassian-labs/observe](https://github.com/atlassian-labs/observe),
+which I wrote at Atlassian in 2020. It keeps the idea and the Apache-2.0 license; the code is new.
+See [NOTICE](NOTICE).
+
+## License
+
+[Apache-2.0](LICENSE)

observe_kit-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+observe_kit/__init__.py,sha256=0CnbLiWeRzAjUpHUF7oZbgr6LZugrEUifkDCf9U3ftc,1118
+observe_kit/decorator.py,sha256=dYU_yqVN4Kj6pYIVExGcXvgxY9pWPUYb_0lWfitFDr0,8791
+observe_kit/events.py,sha256=4D9mPtWjPp0A9RgdZ6rDdSMzFJsUX4pMJVe3mEuh3ak,1627
+observe_kit/policy.py,sha256=d0gBO5SHhzxo1PilZ1-T2L1J9OCAseigguwxRbVGX-0,2794
+observe_kit/provider.py,sha256=shbRaG6DW28Wi6HeNbHBIiPF6q-YjYIV3p3xIY7IDcA,2060
+observe_kit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+observe_kit/sinks.py,sha256=Gc68aIdRxMzGVTSovPNLjzS-IWzoBB7CesnJq3R12mw,1577
+observe_kit/text.py,sha256=KTgxUSQH9vqvwH9VDe-top-YVe6ouDEvomvMqAnX0Dk,655
+observe_kit-0.1.1.dist-info/METADATA,sha256=beVrslfyE4J6TKJuY8JHvCOJdRcOVFXz-BmRbFLnFBc,7839
+observe_kit-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+observe_kit-0.1.1.dist-info/licenses/LICENSE,sha256=515cJROAdHB0IS3GKEE3DdY4OH_Jh-ogd1Cbc_eB2NI,11343
+observe_kit-0.1.1.dist-info/licenses/NOTICE,sha256=1eAA_MXNRwflnCtFs6uLhSHphH8XX2X1ySAMlCRYRcg,606
+observe_kit-0.1.1.dist-info/RECORD,,

observe_kit-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

observe_kit-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Georg Kasper
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

observe_kit-0.1.1.dist-info/licenses/NOTICE

@@ -0,0 +1,11 @@
+observe-kit
+Copyright 2026 Georg Kasper
+
+This product is a rewrite of "observe" (https://github.com/atlassian-labs/observe),
+Copyright [2020] Atlassian Pty Ltd, licensed under the Apache License, Version 2.0.
+Georg Kasper was the author of that project.
+
+Changes from the original: new code base built around a single `observed` decorator with four
+explicit outcomes (finished, expected, swallowed, raised); structlog logging; pluggable event
+sinks and notifiers found on the decorated instance; async support; and a notification policy
+that keeps context fields, extra error lines and URLs out of alerts.