opendataframework 0.3.0__tar.gz → 0.4.0__tar.gz

{opendataframework-0.3.0 → opendataframework-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opendataframework
-Version: 0.3.0
+Version: 0.4.0
 Summary: Lightweight dependency-injection framework for data applications.
 License-Expression: MIT
 License-File: LICENSE

{opendataframework-0.3.0 → opendataframework-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opendataframework"
-version = "0.3.0"
+version = "0.4.0"
 description = "Lightweight dependency-injection framework for data applications."
 authors = [
     {name = "mykytapavlov",email = "mykytapavlov@users.noreply.github.com"}

{opendataframework-0.3.0 → opendataframework-0.4.0}/src/opendataframework/__init__.py

@@ -5,7 +5,8 @@ from opendataframework.component import Component
 from opendataframework.config import Config
 from opendataframework.context import Context, Lifecycle, Resolver
 from opendataframework.entity import Entity
-from opendataframework.function import Function
+from opendataframework.events import Event, Events
+from opendataframework.function import Function, FunctionProtocol
 from opendataframework.layer import Analytics, Api, Layer, Messaging, Monitoring, Security, Storage
 from opendataframework.logger import Logger
 from opendataframework.namespace import Namespace
@@ -51,7 +52,10 @@ __all__ = [
     "DataViewProtocol",
     "DocumentView",
     "Entity",
+    "Event",
+    "Events",
     "Function",
+    "FunctionProtocol",
     "ImageView",
     "Layer",
     "Lifecycle",

{opendataframework-0.3.0 → opendataframework-0.4.0}/src/opendataframework/context.py

@@ -7,8 +7,11 @@ dispatch: setup/run/stop for services, on_start/on_stop for components),
 and ``StreamManager`` (background threads for ``StreamableProtocol``
 repositories). ``Context`` is the only public entry point of the three —
 ``Resolver``/``Lifecycle``/``StreamManager`` are internal collaborators.
+Every protocol call the three make is logged and also reported as an
+``Event`` to the ``Context``'s ``Events`` (see ``opendataframework.events``).
 """
 
+import contextvars
 import functools
 import inspect
 import threading
@@ -18,13 +21,14 @@ from pathlib import Path
 from queue import Empty, Full, Queue
 from typing import Annotated, TypeAliasType, TypeVar, cast, get_origin, overload
 
-from opendataframework.agent import Agent
+from opendataframework.agent import Agent, AgentProtocol
 from opendataframework.component import Component, OnStartProtocol, OnStopProtocol
 from opendataframework.config import Config
-from opendataframework.function import Function, bind, string_hint
+from opendataframework.events import Events
+from opendataframework.function import Function, FunctionProtocol, bind, string_hint
 from opendataframework.logger import Logger, LogManager
 from opendataframework.namespace import Namespace, parse, qualified
-from opendataframework.pipeline import Pipeline
+from opendataframework.pipeline import Pipeline, PipelineProtocol
 from opendataframework.repository import (
     CloseStreamProtocol,
     OpenStreamProtocol,
@@ -32,7 +36,7 @@ from opendataframework.repository import (
     StreamableProtocol,
 )
 from opendataframework.service import Service, ServiceProtocol
-from opendataframework.task import Task
+from opendataframework.task import Task, TaskProtocol
 from opendataframework.utils import normalize
 
 _STREAM_ENDED = object()
@@ -54,27 +58,31 @@ def _is_async(func: object) -> bool:
     return inspect.iscoroutinefunction(func) or inspect.isasyncgenfunction(func)
 
 
-def _logged_execute(execute, name: str, log_manager: LogManager, label: str = "execute()"):
+def _logged_execute(
+    execute, name: str, log_manager: LogManager, events: Events, protocol: type, method: str
+):
     """Wrap a bound ``execute`` method to log its start, duration, and errors.
 
-    ``label`` names the operation in the log lines, so the same wrapper also
-    serves an ``Agent``'s ``invoke()`` and a ``Function`` called through the
-    ``Context``.
+    ``protocol`` and ``method`` name the protocol call being wrapped, so the
+    same wrapper also serves an ``Agent``'s ``invoke()`` and a ``Function``
+    called through the ``Context``. Each call is also reported to ``events``.
     """
+    label = "call" if protocol is FunctionProtocol else f"{method}()"
 
     @functools.wraps(execute)
     def wrapped(*args, **kwargs):
         """Call the wrapped ``execute``, logging its start, duration, and errors."""
-        log_manager.write(name, "INFO", f"{label} started")
-        start = time.monotonic()
-        try:
-            result = execute(*args, **kwargs)
-        except Exception as exc:
-            log_manager.write(name, "ERROR", f"{label} raised {exc!r}")
-            raise
-        elapsed_ms = (time.monotonic() - start) * 1000
-        log_manager.write(name, "INFO", f"{label} completed in {elapsed_ms:.1f}ms")
-        return result
+        with events.notify(name, protocol, method):
+            log_manager.write(name, "INFO", f"{label} started")
+            start = time.monotonic()
+            try:
+                result = execute(*args, **kwargs)
+            except Exception as exc:
+                log_manager.write(name, "ERROR", f"{label} raised {exc!r}")
+                raise
+            elapsed_ms = (time.monotonic() - start) * 1000
+            log_manager.write(name, "INFO", f"{label} completed in {elapsed_ms:.1f}ms")
+            return result
 
     return wrapped
 
@@ -113,16 +121,21 @@ class Resolver:
     derives the dependency graph from their signatures, sorts them
     topologically, and instantiates each class — or binds each function —
     with its dependencies injected. Has no knowledge
-    of lifecycle or framework protocols — the one exception is ``Logger``
+    of lifecycle or framework protocols — the exceptions are ``Logger``
     (see ``opendataframework.logger``), which is resolved contextually: a ``logger: Logger``
     constructor parameter receives an instance bound to the *consuming*
     class's own key rather than a single shared instance, and every
-    instantiation is logged to that component's file.
+    instantiation is logged to that component's file — and ``Events``
+    (see ``opendataframework.events``): an ``events: Events`` parameter
+    receives the ``Context``'s own instance, and every call of a bound
+    function is reported to it as a ``FunctionProtocol`` call.
 
     Args:
         namespaces: Namespace subclasses to collect registered classes from.
         log_manager: Owns per-component log files. Defaults to a disabled
             ``LogManager`` (writes become no-ops) when omitted.
+        events: Receives an event for every call of a bound function.
+            Defaults to an ``Events`` with no listeners when omitted.
 
     Example:
         >>> class NS(Namespace): ...
@@ -144,6 +157,7 @@ class Resolver:
         namespaces: Iterable[type[Namespace]],
         extra_instances: dict[type, object] | None = None,
         log_manager: LogManager | None = None,
+        events: Events | None = None,
     ) -> None:
         """See class docstring for ``Args``."""
         self._namespaces = set(namespaces)
@@ -154,6 +168,7 @@ class Resolver:
         self._keys: dict[type | Callable[..., object], str] = {}
         self._by_key: dict[str, type | Callable[..., object]] = {}
         self._log_manager = log_manager if log_manager is not None else LogManager()
+        self._events = events if events is not None else Events(self._log_manager)
 
     @property
     def instances(self) -> dict[type, object]:
@@ -254,7 +269,9 @@ class Resolver:
                     bind(node, self._injected[node]),
                     self._keys[node],
                     self._log_manager,
-                    label="call",
+                    self._events,
+                    FunctionProtocol,
+                    "__call__",
                 )
 
     def _index(self) -> None:
@@ -470,7 +487,8 @@ class Resolver:
 
         A ``dep`` annotated exactly as ``Logger`` is special-cased: instead of
         a shared instance, ``target`` receives a ``Logger`` bound to its own
-        key (see ``opendataframework.logger.LogManager.logger_for``). A class is
+        key (see ``opendataframework.logger.LogManager.logger_for``). One
+        annotated exactly as ``Events`` receives the ``Context``'s ``Events``. A class is
         supplied only if already present in ``self._instances``, and a
         function only if already bound — unregistered ones in the signature
         are silently ignored.
@@ -479,6 +497,8 @@ class Resolver:
         for name, dep in self.dependencies(target).items():
             if dep is Logger:
                 supplied[name] = self._log_manager.logger_for(self._keys[target])
+            elif dep is Events:
+                supplied[name] = self._events
             elif dep in self._instances:
                 supplied[name] = self._instances[dep]
             elif dep in self._functions:
@@ -495,7 +515,8 @@ class Lifecycle:
 
     Every stage transition is also logged to the component's own log file via
     ``log_manager`` (see ``opendataframework.logger``), giving every ``Service`` a log
-    record with no code changes required.
+    record with no code changes required, and every protocol call is reported
+    to ``events`` (see ``opendataframework.events``).
 
     Args:
         instances: Class-to-instance mapping produced by ``Resolver``.
@@ -504,6 +525,8 @@ class Lifecycle:
             ``Resolver.keys``. Names each class's log file.
         log_manager: Owns per-component log files. Defaults to a disabled
             ``LogManager`` (writes become no-ops) when omitted.
+        events: Receives an event for every protocol call. Defaults to an
+            ``Events`` with no listeners when omitted.
 
     Example:
         >>> lifecycle = Lifecycle(instances={...}, order=[...], keys={...})
@@ -517,12 +540,14 @@ class Lifecycle:
         order: list[type],
         keys: dict[type, str],
         log_manager: LogManager | None = None,
+        events: Events | None = None,
     ) -> None:
         """See class docstring for ``Args``."""
         self._instances = instances
         self._order = order
         self._keys = keys
         self._log_manager = log_manager if log_manager is not None else LogManager()
+        self._events = events if events is not None else Events(self._log_manager)
         self._threads: list[threading.Thread] = []
         self._running: dict[type, bool] = {}
 
@@ -552,9 +577,10 @@ class Lifecycle:
     def _activate_one(self, cls: type, instance: object) -> None:
         """Call a non-``Service`` instance's ``on_start()`` hook."""
         name = self._keys[cls]
-        self._log_manager.write(name, "INFO", "on_start() called")
-        instance.on_start()
-        self._log_manager.write(name, "INFO", "on_start() complete")
+        with self._events.notify(name, OnStartProtocol, "on_start"):
+            self._log_manager.write(name, "INFO", "on_start() called")
+            instance.on_start()
+            self._log_manager.write(name, "INFO", "on_start() complete")
 
     def start_one(self, cls: type) -> None:
         """Start a single ``ServiceProtocol`` instance. No-op if already running.
@@ -571,10 +597,15 @@ class Lifecycle:
             return
         instance = self._instances[cls]
         name = self._keys[cls]
-        self._log_manager.write(name, "INFO", "setup() starting")
-        instance.setup()
-        self._log_manager.write(name, "INFO", "setup() complete")
-        t = threading.Thread(target=self._run, args=(cls, instance), daemon=True)
+        with self._events.notify(name, ServiceProtocol, "setup"):
+            self._log_manager.write(name, "INFO", "setup() starting")
+            instance.setup()
+            self._log_manager.write(name, "INFO", "setup() complete")
+        # An empty context, so run() is a top-level call rather than a child
+        # of whatever call started the service.
+        t = threading.Thread(
+            target=self._run, args=(cls, instance), daemon=True, context=contextvars.Context()
+        )
         t.start()
         self._threads.append(t)
         self._running[cls] = True
@@ -594,9 +625,10 @@ class Lifecycle:
             return
         instance = self._instances[cls]
         name = self._keys[cls]
-        self._log_manager.write(name, "INFO", "stop() called")
-        instance.stop()
-        self._log_manager.write(name, "INFO", "stop() complete")
+        with self._events.notify(name, ServiceProtocol, "stop"):
+            self._log_manager.write(name, "INFO", "stop() called")
+            instance.stop()
+            self._log_manager.write(name, "INFO", "stop() complete")
         self._running[cls] = False
 
     def is_running(self, cls: type) -> bool:
@@ -606,13 +638,14 @@ class Lifecycle:
     def _run(self, cls: type, instance: ServiceProtocol) -> None:
         """Run ``instance.run()``, logging its start, return, and any exception."""
         name = self._keys[cls]
-        self._log_manager.write(name, "INFO", "run() started")
-        try:
-            instance.run()
-            self._log_manager.write(name, "INFO", "run() returned")
-        except Exception as exc:
-            self._log_manager.write(name, "ERROR", f"run() raised {exc!r}")
-            raise
+        with self._events.notify(name, ServiceProtocol, "run"):
+            self._log_manager.write(name, "INFO", "run() started")
+            try:
+                instance.run()
+                self._log_manager.write(name, "INFO", "run() returned")
+            except Exception as exc:
+                self._log_manager.write(name, "ERROR", f"run() raised {exc!r}")
+                raise
 
     def on_stop(self) -> None:
         """Deactivate all instances in reverse dependency order.
@@ -638,9 +671,10 @@ class Lifecycle:
     def _deactivate_one(self, cls: type, instance: object) -> None:
         """Call a non-``Service`` instance's ``on_stop()`` hook."""
         name = self._keys[cls]
-        self._log_manager.write(name, "INFO", "on_stop() called")
-        instance.on_stop()
-        self._log_manager.write(name, "INFO", "on_stop() complete")
+        with self._events.notify(name, OnStopProtocol, "on_stop"):
+            self._log_manager.write(name, "INFO", "on_stop() called")
+            instance.on_stop()
+            self._log_manager.write(name, "INFO", "on_stop() complete")
 
 
 def _publish_latest(q: Queue, item: object) -> None:
@@ -694,15 +728,21 @@ class StreamManager:
     """
 
     def __init__(
-        self, keys: dict[type, str] | None = None, log_manager: LogManager | None = None
+        self,
+        keys: dict[type, str] | None = None,
+        log_manager: LogManager | None = None,
+        events: Events | None = None,
     ) -> None:
         """See class docstring; ``log_manager`` defaults to a disabled ``LogManager``.
 
         ``keys`` maps each class to the ``<namespace>.<name>`` key its log
-        lines go under, as returned by ``Resolver.keys``.
+        lines go under, as returned by ``Resolver.keys``. ``events`` receives
+        an event for every ``open_stream()``/``stream()``/``close_stream()``
+        call, and defaults to an ``Events`` with no listeners.
         """
         self._keys = keys if keys is not None else {}
         self._log_manager = log_manager if log_manager is not None else LogManager()
+        self._events = events if events is not None else Events(self._log_manager)
         self._threads: dict[type, threading.Thread] = {}
         self._stop_events: dict[type, threading.Event] = {}
         self._subscribers: dict[type, list[Queue]] = {}
@@ -724,15 +764,19 @@ class StreamManager:
         name = self._keys[cls]
         try:
             if isinstance(instance, OpenStreamProtocol):
-                self._log_manager.write(name, "INFO", "open_stream() called")
-                instance.open_stream()
-                self._log_manager.write(name, "INFO", "open_stream() complete")
+                with self._events.notify(name, OpenStreamProtocol, "open_stream"):
+                    self._log_manager.write(name, "INFO", "open_stream() called")
+                    instance.open_stream()
+                    self._log_manager.write(name, "INFO", "open_stream() complete")
             with self._lock:
                 self._subscribers[cls] = []
                 event = threading.Event()
                 self._stop_events[cls] = event
                 thread = threading.Thread(
-                    target=self._run, args=(cls, instance, event), daemon=True
+                    target=self._run,
+                    args=(cls, instance, event),
+                    daemon=True,
+                    context=contextvars.Context(),
                 )
                 self._threads[cls] = thread
         finally:
@@ -789,11 +833,12 @@ class StreamManager:
         """Drive ``instance.stream()``, fanning entities out to subscribers until done."""
         name = self._keys[cls]
         try:
-            for entity in instance.stream():
-                if stop_event.is_set():
-                    break
-                for q in list(self._subscribers.get(cls, ())):
-                    _publish_latest(q, entity)
+            with self._events.notify(name, StreamableProtocol, "stream"):
+                for entity in instance.stream():
+                    if stop_event.is_set():
+                        break
+                    for q in list(self._subscribers.get(cls, ())):
+                        _publish_latest(q, entity)
         except Exception as exc:
             self._log_manager.write(name, "ERROR", f"stream raised {exc!r}")
         finally:
@@ -802,9 +847,10 @@ class StreamManager:
             # exception — close_stream() releases the resource in all three
             # cases, not just an explicit stop_stream() call.
             if isinstance(instance, CloseStreamProtocol):
-                self._log_manager.write(name, "INFO", "close_stream() called")
                 try:
-                    instance.close_stream()
+                    with self._events.notify(name, CloseStreamProtocol, "close_stream"):
+                        self._log_manager.write(name, "INFO", "close_stream() called")
+                        instance.close_stream()
                 except Exception as exc:
                     self._log_manager.write(name, "ERROR", f"close_stream() raised {exc!r}")
                 else:
@@ -885,13 +931,15 @@ class Context:
         """See class docstring for ``Args``."""
         extra = {Config: Config(config)} if config is not None else {}
         self._log_manager = LogManager(log_dir)
+        self._events = Events(self._log_manager)
         self._resolver = Resolver(
             namespaces if namespaces is not None else _DEFAULT_NAMESPACES,
             extra_instances=extra,
             log_manager=self._log_manager,
+            events=self._events,
         )
         self._lifecycle: Lifecycle | None = None
-        self._stream_manager = StreamManager(log_manager=self._log_manager)
+        self._stream_manager = StreamManager(log_manager=self._log_manager, events=self._events)
         self._functions: dict[Callable[..., object], Callable[..., object]] = {}
 
     @property
@@ -904,6 +952,22 @@ class Context:
         """
         return self._resolver.instances
 
+    @property
+    def events(self) -> Events:
+        """The ``Events`` every protocol call this ``Context`` makes is reported to.
+
+        The same instance an ``events: Events`` constructor parameter
+        receives. Usable before ``open()``, so a listener subscribed first
+        also sees the startup calls ``open()`` makes. See
+        ``opendataframework.events``.
+
+        Example:
+            >>> unsubscribe = context.events.subscribe(print, protocol=ServiceProtocol)
+            >>> context.open()
+            Event(key='service.postgres', protocol=<class '...ServiceProtocol'>, ...)
+        """
+        return self._events
+
     @property
     def functions(self) -> dict[Callable[..., object], Callable[..., object]]:
         """Registered ``Function`` → bound callable mapping, populated by ``open()``.
@@ -988,9 +1052,9 @@ class Context:
         keys = self._resolver.keys
         self._instrument(keys)
         self._functions = self._resolver.functions
-        self._stream_manager = StreamManager(keys, self._log_manager)
+        self._stream_manager = StreamManager(keys, self._log_manager, self._events)
         self._lifecycle = Lifecycle(
-            self._resolver.instances, self._resolver.order, keys, self._log_manager
+            self._resolver.instances, self._resolver.order, keys, self._log_manager, self._events
         )
         self._lifecycle.on_start()
 
@@ -1291,18 +1355,34 @@ class Context:
 
         Logs start, completion (with duration), and any exception to that
         component's own log file — with no code changes required in the
-        classes themselves. The wrapper is set on the instance, so a call
-        made directly (from a ``Pipeline``, say) is logged the same as one
-        made through the ``Context``.
+        classes themselves — and reports each call to ``events`` as a
+        ``TaskProtocol``, ``PipelineProtocol`` or ``AgentProtocol`` call. The
+        wrapper is set on the instance, so a call made directly (from a
+        ``Pipeline``, say) is logged the same as one made through the
+        ``Context``.
         """
-        executable = set(dict(Task.items()).values()) | set(dict(Pipeline.items()).values())
+        tasks = set(dict(Task.items()).values())
+        pipelines = set(dict(Pipeline.items()).values())
         agents = set(dict(Agent.items()).values())
         for cls, instance in self._resolver.instances.items():
-            if cls in executable and hasattr(instance, "execute"):
-                instance.execute = _logged_execute(instance.execute, keys[cls], self._log_manager)
+            if cls in tasks | pipelines and hasattr(instance, "execute"):
+                protocol = PipelineProtocol if cls in pipelines else TaskProtocol
+                instance.execute = _logged_execute(
+                    instance.execute,
+                    keys[cls],
+                    self._log_manager,
+                    self._events,
+                    protocol,
+                    "execute",
+                )
             if cls in agents:
                 instance.invoke = _logged_execute(
-                    instance.invoke, keys[cls], self._log_manager, label="invoke()"
+                    instance.invoke,
+                    keys[cls],
+                    self._log_manager,
+                    self._events,
+                    AgentProtocol,
+                    "invoke",
                 )
 
     def __enter__(self) -> Context:

opendataframework-0.4.0/src/opendataframework/events.py

@@ -0,0 +1,188 @@
+"""Protocol events — an Observer over the protocol calls the framework drives.
+
+Every time the ``Context`` calls a lifecycle or execution protocol method on
+a component — a ``Service``'s ``setup()``/``run()``/``stop()``, an
+``on_start()``/``on_stop()`` hook, a ``Task``'s or ``Pipeline``'s
+``execute()``, an ``Agent``'s ``invoke()``, a ``@Function`` call, a
+repository's ``open_stream()``/``stream()``/``close_stream()`` — it emits an
+``Event`` when the call starts and when it completes or fails. Nothing else
+emits one.
+
+``Events`` is the subject, one per ``Context`` — no process-global state, so
+multiple ``Project`` instances in the same process never share listeners
+(see ``CLAUDE.md``'s "no global mutable state" constraint). Like ``Logger``,
+it is injectable: a constructor parameter annotated ``events: Events``
+receives the ``Context``'s own instance. Code holding the ``Context`` reaches
+it as ``context.events``.
+"""
+
+import threading
+import time
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from uuid import uuid4
+
+from opendataframework.logger import LogManager
+
+# The ``call_id`` of the protocol call in progress in this thread (or task).
+# A ``ContextVar`` holds a separate value per thread, so it is not shared state.
+_current_call: ContextVar[str | None] = ContextVar("opendataframework_call", default=None)
+
+
+@dataclass(frozen=True)
+class Event:
+    """One state change of a protocol call the framework made.
+
+    Attributes:
+        key: The ``<namespace>.<name>`` key of the component called, as
+            ``Context.key()`` returns it.
+        protocol: The protocol whose method was called — ``ServiceProtocol``,
+            ``OnStartProtocol``, ``TaskProtocol``, ``FunctionProtocol``, ...
+        method: The method called — ``"setup"``, ``"on_start"``,
+            ``"execute"``, ``"__call__"``, ``"stream"``, ...
+        state: ``"started"``, ``"completed"``, or ``"failed"``.
+        call_id: Identifies the call; shared by its ``started`` and its
+            ``completed``/``failed`` event.
+        parent: ``call_id`` of the call in progress in this thread when this
+            one started — a pipeline for its steps, a task for a function it
+            calls — or ``None`` for a top-level call.
+        ts: ``time.time()`` when the event was emitted.
+        elapsed_ms: Duration of the call, on ``completed``/``failed`` only.
+        error: ``repr()`` of the exception raised, on ``failed`` only.
+    """
+
+    key: str
+    protocol: type
+    method: str
+    state: str
+    call_id: str
+    parent: str | None
+    ts: float
+    elapsed_ms: float | None = None
+    error: str | None = None
+
+
+class Events:
+    """Delivers every ``Event`` of a single ``Context`` to its listeners.
+
+    Not constructed by user code — declare ``events: Events`` in a
+    constructor to receive the ``Context``'s instance, or use
+    ``context.events``. A listener is any callable taking an ``Event``; it
+    runs synchronously, in the thread that made the call, so it must be quick
+    and thread-safe — hand slow work off to a queue instead.
+
+    Args:
+        log_manager: Where a listener's exception is logged, as a ``WARNING``
+            on the event's component. Defaults to a disabled ``LogManager``.
+
+    Example:
+        >>> @Component
+        ... class FailureAlerts:
+        ...     def __init__(self, events: Events) -> None:
+        ...         self.queue: Queue[Event | None] = Queue()
+        ...         self._unsubscribe = events.subscribe(self.queue.put)
+        ...
+        ...     def on_stop(self) -> None:
+        ...         self._unsubscribe()
+    """
+
+    def __init__(self, log_manager: LogManager | None = None) -> None:
+        """See class docstring for ``Args``."""
+        self._log_manager = log_manager if log_manager is not None else LogManager()
+        self._listeners: list[tuple[Callable[[Event], None], type | None]] = []
+        self._lock = threading.Lock()
+
+    def subscribe(
+        self, listener: Callable[[Event], None], protocol: type | None = None
+    ) -> Callable[[], None]:
+        """Call ``listener`` with every event, or only with calls of ``protocol``'s methods.
+
+        Args:
+            listener: Called with each matching ``Event``.
+            protocol: Deliver only events whose ``protocol`` is exactly this
+                one — ``TaskProtocol`` does not match a ``Pipeline``'s
+                ``execute()``. ``None`` (the default) delivers every event.
+
+        Returns:
+            A function that unsubscribes ``listener``. Calling it more than
+            once is a no-op.
+
+        Example:
+            >>> unsubscribe = events.subscribe(on_service, protocol=ServiceProtocol)
+            >>> unsubscribe()
+        """
+        entry = (listener, protocol)
+        with self._lock:
+            self._listeners.append(entry)
+
+        def unsubscribe() -> None:
+            """Stop delivering events to ``listener``."""
+            with self._lock:
+                if entry in self._listeners:
+                    self._listeners.remove(entry)
+
+        return unsubscribe
+
+    @contextmanager
+    def notify(self, key: str, protocol: type, method: str) -> Iterator[None]:
+        """Emit ``started``, then ``completed`` or ``failed``, around one protocol call.
+
+        Used by the framework at each place it calls a protocol method; not
+        meant for user code. While the call runs, it is the current call, so
+        calls made inside it get it as their ``parent``. An exception from
+        the call is re-raised unchanged.
+
+        Example:
+            >>> with events.notify("service.postgres", ServiceProtocol, "setup"):
+            ...     instance.setup()
+        """
+        call_id = uuid4().hex
+        parent = _current_call.get()
+        self._dispatch(Event(key, protocol, method, "started", call_id, parent, time.time()))
+        token = _current_call.set(call_id)
+        start = time.monotonic()
+        try:
+            yield
+        except Exception as exc:
+            elapsed_ms = (time.monotonic() - start) * 1000
+            failed = Event(
+                key, protocol, method, "failed", call_id, parent, time.time(), elapsed_ms, repr(exc)
+            )
+            self._dispatch(failed)
+            raise
+        else:
+            elapsed_ms = (time.monotonic() - start) * 1000
+            completed = Event(
+                key, protocol, method, "completed", call_id, parent, time.time(), elapsed_ms
+            )
+            self._dispatch(completed)
+        finally:
+            _current_call.reset(token)
+
+    def _dispatch(self, event: Event) -> None:
+        """Call every listener subscribed to ``event``'s protocol, isolating their failures.
+
+        Listeners run with no current call, so a call one of them makes is a
+        top-level call rather than a child of the call that emitted
+        ``event``. An exception from a listener is logged and never reaches
+        the call.
+        """
+        with self._lock:
+            listeners = [
+                listener
+                for listener, protocol in self._listeners
+                if protocol is None or protocol is event.protocol
+            ]
+        if not listeners:
+            return
+        token = _current_call.set(None)
+        try:
+            for listener in listeners:
+                try:
+                    listener(event)
+                except Exception as exc:
+                    self._log_manager.write(event.key, "WARNING", f"listener raised {exc!r}")
+        finally:
+            _current_call.reset(token)

{opendataframework-0.3.0 → opendataframework-0.4.0}/src/opendataframework/function.py

@@ -10,6 +10,7 @@ to call it by name with its managed dependencies filled in.
 import functools
 import inspect
 from collections.abc import Callable, ItemsView, Iterable
+from typing import Protocol
 
 from opendataframework.namespace import Namespace, describe
 from opendataframework.utils import normalize
@@ -18,6 +19,28 @@ _POSITIONAL = (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_O
 _VARIADIC = (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
 
 
+class FunctionProtocol(Protocol):
+    """Expected interface for functions registered with ``@Function``.
+
+    A function is called with arguments and returns a result — the
+    function-shaped counterpart of ``TaskProtocol``. It is a label for type
+    hints and for events, not a way to detect a function: any callable would
+    match it structurally, so it is deliberately not ``runtime_checkable``
+    and ``isinstance()`` against it raises ``TypeError``. The ``Context``
+    knows a function by its ``@Function`` registration instead.
+
+    Every call of a registered function made through the ``Context`` —
+    injected, ``context.call()``, or ``context.get(func)`` — emits events
+    with this protocol (see ``opendataframework.events``)::
+
+        events.subscribe(on_call, protocol=FunctionProtocol)
+    """
+
+    def __call__(self, *args, **kwargs) -> object:
+        """Run the function with its arguments and return a result."""
+        ...
+
+
 class Function(Namespace):
     """Decorator that registers a plain function with the Context.
 

{opendataframework-0.3.0 → opendataframework-0.4.0}/src/opendataframework/view.py

@@ -12,7 +12,9 @@ on the other end (e.g. the sibling ``odf`` package's UI).
 
 Every variant points at its field(s) generically (``field``/``fields``),
 never with a domain-specific attribute name — the meaning comes from which
-``View`` subclass it is, not from the attribute name.
+``View`` subclass it is, not from the attribute name. A variant may also
+name a field by its role in the representation (``TimeseriesView.group``),
+never by what it means in the domain (``run_id``).
 
 A view says nothing about the content itself, though. A repository whose
 view points at content (``ImageView``/``VideoView``/``AudioView``/
@@ -129,14 +131,23 @@ class LocationView:
 
 @dataclass
 class TimeseriesView:
-    """A line chart — the entity's other numeric fields plotted against a
-    timestamp field.
+    """A line chart — the entity's numeric fields plotted against an
+    ordering field, optionally one line per group.
 
     Attributes:
-        field: The entity's timestamp field.
+        field: The entity's ordering field, plotted as the x axis — a
+            timestamp, or any field records are ordered by (e.g. a
+            training ``step``).
+        fields: The numeric fields to plot, in order. ``None`` means every
+            numeric entity field other than ``field`` and ``group``.
+        group: A field whose distinct values each get their own line (e.g.
+            ``run_id``), so groups can be compared on one chart. ``None``
+            means all records form a single line.
     """
 
     field: str
+    fields: tuple[str, ...] | None = None
+    group: str | None = None
 
 
 DataView = (
@@ -206,7 +217,7 @@ class ReplayProtocol(Protocol):
     ``field()`` gets no such affordance — this only matters for
     ``LocationView``/``VideoView``/``AudioView``-backed repositories; a
     ``TimeseriesView`` repository is always replayable since it already
-    names its own timestamp via ``field``.
+    names its own ordering field via ``field``.
     """
 
     def field(self) -> str: