flowevent 1.2__py3-none-any.whl

eventflow/pipeline/registry.py

@@ -0,0 +1,95 @@
+"""Copy-on-change ordered registries; callers serialize configuration changes."""
+
+from __future__ import annotations
+
+import heapq
+from dataclasses import dataclass, replace
+from typing import Generic, TypeVar
+
+C = TypeVar("C")
+
+
+def _name(value: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError("Pipeline component name must be a non-empty string")
+    return value.strip()
+
+
+@dataclass(frozen=True, slots=True)
+class _Entry(Generic[C]):
+    name: str
+    callback: C
+    before: str | None = None
+    after: str | None = None
+    enabled: bool = True
+
+
+class _Registry(Generic[C]):
+    def __init__(self) -> None:
+        self._entries: dict[str, _Entry[C]] = {}
+        self.ordered: tuple[_Entry[C], ...] = ()
+        self.plan: tuple[_Entry[C], ...] = ()
+
+    def _commit(self, entries: dict[str, _Entry[C]]) -> None:
+        positions = {name: index for index, name in enumerate(entries)}
+        edges: dict[str, set[str]] = {name: set() for name in entries}
+        degree = dict.fromkeys(entries, 0)
+        for entry in entries.values():
+            for source, target in ((entry.name, entry.before), (entry.after, entry.name)):
+                if source is None or target is None:
+                    continue
+                if source not in entries or target not in entries:
+                    raise KeyError(f"Unknown pipeline ordering reference: {source!r}, {target!r}")
+                if target not in edges[source]:
+                    edges[source].add(target)
+                    degree[target] += 1
+        ready = [(positions[name], name) for name, count in degree.items() if count == 0]
+        heapq.heapify(ready)
+        ordered = []
+        while ready:
+            _, name = heapq.heappop(ready)
+            ordered.append(entries[name])
+            for target in edges[name]:
+                degree[target] -= 1
+                if degree[target] == 0:
+                    heapq.heappush(ready, (positions[target], target))
+        if len(ordered) != len(entries):
+            raise ValueError("Pipeline ordering contains a cycle")
+        self._entries = entries
+        self.ordered = tuple(ordered)
+        self.plan = tuple(entry for entry in ordered if entry.enabled)
+
+    def add(self, name: str, callback: C, before: str | None, after: str | None) -> None:
+        name = _name(name)
+        if name in self._entries:
+            raise ValueError(f"Pipeline component already exists: {name}")
+        entry = _Entry(
+            name,
+            callback,
+            _name(before) if before is not None else None,
+            _name(after) if after is not None else None,
+        )
+        self._commit({**self._entries, name: entry})
+
+    def remove(self, name: str) -> C:
+        name = _name(name)
+        removed = self._entries[name]
+        entries = {
+            key: replace(
+                value,
+                before=None if value.before == name else value.before,
+                after=None if value.after == name else value.after,
+            )
+            for key, value in self._entries.items()
+            if key != name
+        }
+        self._commit(entries)
+        return removed.callback
+
+    def replace(self, name: str, callback: C) -> None:
+        name = _name(name)
+        self._commit({**self._entries, name: replace(self._entries[name], callback=callback)})
+
+    def enable(self, name: str, enabled: bool) -> None:
+        name = _name(name)
+        self._commit({**self._entries, name: replace(self._entries[name], enabled=enabled)})

eventflow/pipeline/sync.py

@@ -0,0 +1,92 @@
+"""Thread-safe configuration and snapshot execution for synchronous pipelines."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from threading import get_ident
+from time import perf_counter
+from typing import Generic, Literal, TypeVar
+
+from .._callbacks import synchronous_result
+from .base import _PipelineBase
+from .registry import _Entry
+
+T = TypeVar("T")
+Stage = Callable[[T], T]
+Middleware = Callable[[T, Callable[[T], T]], T]
+
+
+class Pipeline(_PipelineBase[Stage[T], Middleware[T]], Generic[T]):
+    """Run same-type transformations with optional around middleware.
+
+    Each run uses a compiled immutable plan. Configuration changes apply to
+    future runs. Payload mutation is the caller's responsibility.
+    """
+
+    def _invoke(
+        self,
+        name: str,
+        phase: Literal["stage", "middleware"],
+        callback: Callable[..., T],
+        context: T,
+        continuation: Callable[[T], T] | None = None,
+    ) -> T:
+        started = perf_counter() if self._observer is not None else 0.0
+        try:
+            result = callback(context) if continuation is None else callback(context, continuation)
+            result = synchronous_result(result)
+        except BaseException as error:
+            self._raise(error, self._observe(phase, name, started, error), name, phase, context)
+        diagnostic = self._observe(phase, name, started)
+        if diagnostic is not None:
+            self._raise(diagnostic, None, name, "observer", context)
+        return result
+
+    def _compile(self) -> None:
+        stages = self._stages.plan
+
+        def execute(context: T) -> T:
+            for entry in stages:
+                context = self._invoke(entry.name, "stage", entry.callback, context)
+            return context
+
+        chain = execute
+        for entry in reversed(self._middleware.plan):
+            chain = self._layer(entry, chain)
+        self._execution = chain
+
+    def _layer(self, entry: _Entry[Middleware[T]], following: Callable[[T], T]) -> Callable[[T], T]:
+        def execute(context: T) -> T:
+            used = False
+            active = True
+            owner = get_ident()
+
+            def next_(value: T) -> T:
+                nonlocal used
+                if used or not active or get_ident() != owner:
+                    raise RuntimeError(
+                        "Middleware continuation is single-use and scoped to its call"
+                    )
+                used = True
+                return following(value)
+
+            try:
+                return self._invoke(entry.name, "middleware", entry.callback, context, next_)
+            finally:
+                active = False
+
+        return execute
+
+    def run(self, context: T) -> T:
+        """Execute one snapshot; failures preserve their cause and stop later stages."""
+        with self._lock:
+            execute = self._execution
+        started = perf_counter() if self._observer is not None else 0.0
+        try:
+            result = execute(context)
+        except BaseException as error:
+            self._raise(error, self._observe("run", None, started, error), None, "run", context)
+        diagnostic = self._observe("run", None, started)
+        if diagnostic is not None:
+            self._raise(diagnostic, None, None, "observer", context)
+        return result

eventflow/scopes.py

@@ -0,0 +1,185 @@
+"""Explicit ownership of existing subscription and cancellation handles."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+from collections.abc import Awaitable
+from typing import Protocol, TypeVar
+
+from ._callbacks import is_async_callable, synchronous_result
+from ._lifecycle import finish_cleanup
+from .compatibility import BaseExceptionGroup, ExceptionGroup
+
+__all__ = ["CancelHandle", "AsyncCancelHandle", "SubscriptionScope", "AsyncSubscriptionScope"]
+
+
+class CancelHandle(Protocol):
+    """A synchronous, preferably idempotent cancellation handle."""
+
+    def cancel(self) -> None: ...
+
+
+class AsyncCancelHandle(Protocol):
+    """A handle whose cancel method returns an awaitable, preferably idempotently."""
+
+    def cancel(self) -> Awaitable[None]: ...
+
+
+H = TypeVar("H", bound=CancelHandle)
+A = TypeVar("A", bound=AsyncCancelHandle)
+
+
+def _raise_cleanup_errors(errors: list[BaseException]) -> None:
+    if not errors:
+        return
+    for index, error in enumerate(errors):
+        if not isinstance(error, Exception):
+            remaining = errors[:index] + errors[index + 1 :]
+            if remaining:
+                raise error from BaseExceptionGroup("Subscription scope cleanup failed", remaining)
+            raise error
+    ordinary = [error for error in errors if isinstance(error, Exception)]
+    raise ExceptionGroup("Subscription scope cleanup failed", ordinary)
+
+
+class SubscriptionScope:
+    """Cancel owned handles in reverse registration order on exit.
+
+    All handles are attempted. Failed handles remain owned for a later retry.
+    A closed scope rejects additions, including after an unsuccessful close.
+    """
+
+    def __init__(self) -> None:
+        self._handles: list[CancelHandle] = []
+        self._lock = threading.RLock()
+        self._close_lock = threading.RLock()
+        self._closed = False
+
+    @property
+    def closed(self) -> bool:
+        """Whether the scope has stopped accepting handles."""
+        with self._lock:
+            return self._closed
+
+    def add(self, handle: H) -> H:
+        """Own a handle and return it unchanged; duplicate identities are ignored."""
+        cancel = getattr(handle, "cancel", None)
+        if not callable(cancel) or is_async_callable(cancel):
+            raise TypeError("SubscriptionScope requires a synchronous cancel handle")
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("Cannot add a handle to a closed subscription scope")
+            if not any(item is handle for item in self._handles):
+                self._handles.append(handle)
+        return handle
+
+    def close(self) -> None:
+        """Attempt every cancellation, retaining failures and reporting them together."""
+        with self._close_lock:
+            with self._lock:
+                self._closed = True
+                pending, self._handles = list(reversed(self._handles)), []
+            failed: list[CancelHandle] = []
+            errors: list[BaseException] = []
+            for handle in pending:
+                try:
+                    synchronous_result(handle.cancel())
+                except BaseException as error:
+                    failed.append(handle)
+                    errors.append(error)
+            with self._lock:
+                self._handles = list(reversed(failed))
+            _raise_cleanup_errors(errors)
+
+    def __enter__(self) -> SubscriptionScope:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+
+class AsyncSubscriptionScope:
+    """Own async handles on one loop and finish cleanup despite caller cancellation.
+
+    Cleanup runs sequentially in reverse registration order. Concurrent aclose
+    callers await the same cleanup task. Failed handles can be retried.
+    """
+
+    def __init__(self) -> None:
+        self._handles: list[AsyncCancelHandle] = []
+        self._closed = False
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._cleanup: asyncio.Task[list[BaseException]] | None = None
+
+    def _bind_loop(self) -> None:
+        loop = asyncio.get_running_loop()
+        if self._loop is None:
+            self._loop = loop
+        elif self._loop is not loop:
+            raise RuntimeError("AsyncSubscriptionScope belongs to a different event loop")
+
+    @property
+    def closed(self) -> bool:
+        """Whether the scope has stopped accepting handles."""
+        return self._closed
+
+    def add(self, handle: A) -> A:
+        """Own an awaitable cancel handle and return it unchanged.
+
+        The cancel method is not called here because doing so would cancel the
+        handle. Its return value is validated when the scope closes.
+        """
+        if not callable(getattr(handle, "cancel", None)):
+            raise TypeError("AsyncSubscriptionScope requires an awaitable cancel handle")
+        if self._loop is not None:
+            self._bind_loop()
+        if self._closed:
+            raise RuntimeError("Cannot add a handle to a closed subscription scope")
+        if not any(item is handle for item in self._handles):
+            self._handles.append(handle)
+        return handle
+
+    async def _cancel_handles(self) -> list[BaseException]:
+        pending, self._handles = list(reversed(self._handles)), []
+        failed: list[AsyncCancelHandle] = []
+        errors: list[BaseException] = []
+        for handle in pending:
+            try:
+                operation = handle.cancel()
+                if not inspect.isawaitable(operation):
+                    raise TypeError("Async cancel handle cancel() must return an awaitable")
+                synchronous_result(await operation)
+            except BaseException as error:
+                failed.append(handle)
+                errors.append(error)
+        self._handles = list(reversed(failed))
+        return errors
+
+    async def aclose(self) -> None:
+        """Finish all cancellations; caller cancellation propagates after cleanup."""
+        self._bind_loop()
+        self._closed = True
+        if self._cleanup is None or (self._cleanup.done() and self._handles):
+            self._cleanup = asyncio.create_task(
+                self._cancel_handles(), name="EventFlowScopeCleanup"
+            )
+        try:
+            errors = await finish_cleanup(self._cleanup)
+        except asyncio.CancelledError as cancellation:
+            if self._cleanup.done() and not self._cleanup.cancelled():
+                errors = self._cleanup.result()
+                if errors:
+                    raise cancellation from BaseExceptionGroup(
+                        "Subscription scope cleanup failed", errors
+                    )
+            raise
+        _raise_cleanup_errors(errors)
+
+    async def __aenter__(self) -> AsyncSubscriptionScope:
+        self._bind_loop()
+        return self
+
+    async def __aexit__(self, *_args: object) -> None:
+        await self.aclose()

eventflow/stream.py

@@ -0,0 +1,241 @@
+"""Lazy single-consumer async streams with opt-in bounded prefetch."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import AsyncIterable, AsyncIterator, Awaitable, Callable
+from typing import Any, Generic, NoReturn, TypeVar, cast
+
+from ._lifecycle import finish_cleanup
+from .base import validate_positive_capacity
+
+T = TypeVar("T")
+U = TypeVar("U")
+__all__ = ["AsyncStream"]
+
+
+def _raise_with_cleanup(primary: BaseException, cleanup: BaseException) -> NoReturn:
+    if cleanup is primary:
+        raise primary
+    if isinstance(cleanup, Exception):
+        raise primary from cleanup
+    raise cleanup from primary
+
+
+class AsyncStream(AsyncIterator[T], Generic[T]):
+    """Own one async source and consume it once on one event loop.
+
+    map/filter/batch are lazy and create no worker tasks. Use ``async with``
+    around the terminal stream for deterministic cleanup on an early break.
+    aclose cancels an outstanding read, then closes sources and producers.
+    """
+
+    def __init__(
+        self, source: AsyncIterable[T], *, _upstream: AsyncStream[Any] | None = None
+    ) -> None:
+        if not isinstance(source, AsyncIterable):
+            raise TypeError("AsyncStream source must be async iterable")
+        self._source = source
+        self._upstream = _upstream
+        self._iterator: AsyncIterator[T] | None = None
+        self._claimed = False
+        self._closed = False
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._consumer: asyncio.Task[Any] | None = None
+        self._reader: asyncio.Task[Any] | None = None
+        self._read_finished: asyncio.Event | None = None
+        self._cleanup: asyncio.Task[None] | None = None
+
+    def _bind_loop(self) -> None:
+        loop = asyncio.get_running_loop()
+        if self._loop is None:
+            self._loop = loop
+        elif self._loop is not loop:
+            raise RuntimeError("AsyncStream belongs to a different event loop")
+
+    @property
+    def closed(self) -> bool:
+        """Whether the stream no longer accepts reads."""
+        return self._closed
+
+    def __aiter__(self) -> AsyncStream[T]:
+        self._bind_loop()
+        if self._claimed:
+            raise RuntimeError("AsyncStream supports one consumption only")
+        if self._closed:
+            raise RuntimeError("AsyncStream is closed")
+        self._claimed = True
+        return self
+
+    async def __anext__(self) -> T:
+        self._bind_loop()
+        if self._closed:
+            raise StopAsyncIteration
+        if self._reader is not None:
+            raise RuntimeError("Concurrent reads from one AsyncStream are not supported")
+        task = asyncio.current_task()
+        if self._consumer is None:
+            self._consumer = task
+        elif self._consumer is not task:
+            raise RuntimeError("AsyncStream must be consumed by one task")
+        self._claimed = True
+        self._reader = task
+        try:
+            if self._iterator is None:
+                self._iterator = self._source.__aiter__()
+            return await self._iterator.__anext__()
+        except BaseException as error:
+            self._reader = None
+            if not self._closed:
+                try:
+                    await self.aclose()
+                except BaseException as cleanup_error:
+                    if isinstance(error, StopAsyncIteration):
+                        raise cleanup_error
+                    _raise_with_cleanup(error, cleanup_error)
+            raise
+        finally:
+            self._reader = None
+            if self._read_finished is not None:
+                self._read_finished.set()
+            self._read_finished = None
+
+    def map(self, callback: Callable[[T], U | Awaitable[U]]) -> AsyncStream[U]:
+        """Transform each item with a sync or awaitable callback, without threads."""
+        if not callable(callback):
+            raise TypeError("Stream map callback must be callable")
+
+        async def transformed() -> AsyncIterator[U]:
+            async for item in self:
+                result = callback(item)
+                yield await result if inspect.isawaitable(result) else cast(U, result)
+
+        return AsyncStream(transformed(), _upstream=self)
+
+    def filter(self, predicate: Callable[[T], bool | Awaitable[bool]]) -> AsyncStream[T]:
+        """Keep matching items using a synchronous or awaitable predicate."""
+        if not callable(predicate):
+            raise TypeError("Stream filter predicate must be callable")
+
+        async def filtered() -> AsyncIterator[T]:
+            async for item in self:
+                accepted = predicate(item)
+                if inspect.isawaitable(accepted):
+                    accepted = await accepted
+                if type(accepted) is not bool:
+                    raise TypeError("Stream filter predicates must return bool")
+                if accepted:
+                    yield item
+
+        return AsyncStream(filtered(), _upstream=self)
+
+    def batch(self, size: int, *, partial: bool = True) -> AsyncStream[tuple[T, ...]]:
+        """Yield fixed-size tuples and optionally the final partial tuple."""
+        size = validate_positive_capacity(size, name="Stream batch size")
+        if not isinstance(partial, bool):
+            raise TypeError("Stream partial flag must be a bool")
+
+        async def batched() -> AsyncIterator[tuple[T, ...]]:
+            items = []
+            async for item in self:
+                items.append(item)
+                if len(items) == size:
+                    yield tuple(items)
+                    items.clear()
+            if items and partial:
+                yield tuple(items)
+
+        return AsyncStream(batched(), _upstream=self)
+
+    def buffer(self, capacity: int) -> AsyncStream[T]:
+        """Prefetch at most capacity queued items plus one in-flight source item.
+
+        A full queue blocks its single producer. Values are never dropped.
+        Source failures propagate after already queued items have been read.
+        """
+        capacity = validate_positive_capacity(capacity, name="Stream buffer capacity")
+
+        async def buffered() -> AsyncIterator[T]:
+            queue: asyncio.Queue[object] = asyncio.Queue(maxsize=capacity)
+            end = object()
+            error: BaseException | None = None
+            closing = False
+
+            async def produce() -> None:
+                nonlocal error
+                try:
+                    async for item in self:
+                        await queue.put(item)
+                except BaseException as exc:
+                    if closing and isinstance(exc, asyncio.CancelledError):
+                        raise
+                    error = exc
+                await queue.put(end)
+
+            producer = asyncio.create_task(produce(), name="EventFlowStreamProducer")
+            try:
+                while True:
+                    item = await queue.get()
+                    if item is end:
+                        if error is not None:
+                            raise error
+                        break
+                    yield cast(T, item)
+            finally:
+                closing = True
+                producer.cancel()
+                await finish_cleanup(asyncio.gather(producer, return_exceptions=True))
+
+        return AsyncStream(buffered(), _upstream=self)
+
+    async def _shutdown(
+        self, reader: asyncio.Task[Any] | None, read_finished: asyncio.Event | None
+    ) -> None:
+        if reader is not None and not reader.done():
+            reader.cancel()
+            if read_finished is not None:
+                await read_finished.wait()
+        source_error: BaseException | None = None
+        try:
+            source = self._iterator if self._iterator is not None else self._source
+            close = getattr(source, "aclose", None)
+            if close is not None:
+                await close()
+        except BaseException as error:
+            source_error = error
+        if self._upstream is not None:
+            try:
+                await self._upstream.aclose()
+            except BaseException as cleanup_error:
+                if source_error is not None:
+                    _raise_with_cleanup(source_error, cleanup_error)
+                raise
+        if source_error is not None:
+            raise source_error
+
+    async def aclose(self) -> None:
+        """Stop reads and await producer/source cleanup, even during repeated cancellation."""
+        self._bind_loop()
+        if self._reader is asyncio.current_task():
+            raise RuntimeError("Cannot close an AsyncStream from its active read task")
+        if self._cleanup is None:
+            self._closed = True
+            reader = self._reader
+            if reader is not None:
+                # Only external concurrent close needs a read-completion event.
+                self._read_finished = asyncio.Event()
+            self._cleanup = asyncio.create_task(
+                self._shutdown(reader, self._read_finished),
+                name="EventFlowStreamCleanup",
+            )
+        await finish_cleanup(self._cleanup)
+
+    async def __aenter__(self) -> AsyncStream[T]:
+        self._bind_loop()
+        if self._closed:
+            raise RuntimeError("AsyncStream is closed")
+        return self
+
+    async def __aexit__(self, *_args: object) -> None:
+        await self.aclose()