flowevent 1.2__py3-none-any.whl

eventflow/base.py

@@ -0,0 +1,180 @@
+"""Common contracts and pure helpers shared by both event buses."""
+
+from __future__ import annotations
+
+import inspect
+import math
+import threading
+import weakref
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar
+
+from .contracts import ErrorPolicy, EventBusStats
+from .errors import EventBusClosedError
+from .filtering import EventFilter, EventType, coerce_event_filter
+from .history import EventHistory, MemoryEventHistory, _validate_query_limit
+
+
+T = TypeVar("T")
+
+
+def validate_positive_capacity(value: int, *, name: str) -> int:
+    """Validate a bounded collection/schedule capacity."""
+
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ValueError(f"{name} must be a positive integer")
+    return value
+
+
+def normalize_replay_capacity(value: int) -> int:
+    """Validate a replay buffer capacity as a positive integer."""
+
+    return validate_positive_capacity(value, name="Replay buffer limit")
+
+
+def validate_positive_timeout(value: float, *, name: str) -> float:
+    """Validate and normalize a finite timeout value."""
+
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or value <= 0
+    ):
+        raise ValueError(f"{name} must be positive and finite")
+    return float(value)
+
+
+def validate_nonnegative_count(value: int, *, name: str) -> int:
+    """Validate a count that may be zero."""
+
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise ValueError(f"{name} must be a non-negative integer")
+    return value
+
+
+def validate_nonnegative_timeout(value: float, *, name: str) -> float:
+    """Validate and normalize a finite timeout that may be zero."""
+
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{name} must be non-negative and finite")
+    try:
+        normalized = float(value)
+    except OverflowError as exc:
+        raise ValueError(f"{name} must be non-negative and finite") from exc
+    if not math.isfinite(normalized) or normalized < 0:
+        raise ValueError(f"{name} must be non-negative and finite")
+    return normalized
+
+
+class BaseEventBus(Generic[T], ABC):
+    def __init__(
+        self,
+        *,
+        history: EventHistory[T] | int | None = None,
+        error_policy: ErrorPolicy = ErrorPolicy.ISOLATE,
+    ) -> None:
+        if history is None or isinstance(history, EventHistory):
+            self._history = history
+        elif isinstance(history, bool) or not isinstance(history, int):
+            raise TypeError("Event history must be a positive capacity or EventHistory")
+        else:
+            self._history = MemoryEventHistory[T](history)
+        self._error_policy = ErrorPolicy(error_policy)
+        self._engine_owner_lock = threading.Lock()
+        self._engine_owner: weakref.ReferenceType[Any] | None = None
+        self._published = 0
+        self._delivered = 0
+        self._failed = 0
+
+    def _claim_engine_ownership(self, owner: Any) -> bool:
+        """Atomically assign this bus to one live engine without retaining it."""
+        with self._engine_owner_lock:
+            current_owner = self._engine_owner() if self._engine_owner is not None else None
+            if current_owner is not None and current_owner is not owner:
+                return False
+            self._engine_owner = weakref.ref(owner)
+            return True
+
+    @property
+    def history(self) -> EventHistory[T] | None:
+        return self._history
+
+    @property
+    def error_policy(self) -> ErrorPolicy:
+        return self._error_policy
+
+    @property
+    @abstractmethod
+    def closed(self) -> bool: ...
+
+    @property
+    @abstractmethod
+    def subscriber_count(self) -> int: ...
+
+    @property
+    @abstractmethod
+    def stats(self) -> EventBusStats: ...
+
+    def _ensure_open(self) -> None:
+        if self.closed:
+            raise EventBusClosedError("Event bus is closed")
+
+    def _record(self, event: T) -> None:
+        if self._history is not None:
+            self._history.append(event)
+
+    @staticmethod
+    def _delivery_limit(*, once: bool, times: int | None) -> int | None:
+        if times is not None:
+            if isinstance(times, bool) or not isinstance(times, int) or times <= 0:
+                raise ValueError("Subscription times must be a positive integer")
+            if once and times != 1:
+                raise ValueError("Use once=True or times, not both")
+            return times
+        return 1 if once else None
+
+    def latest(
+        self,
+        *,
+        event_filter: EventFilter[T] | None = None,
+        event_type: EventType | None = None,
+        predicate: Callable[[T], bool] | None = None,
+    ) -> T | None:
+        normalized_filter = coerce_event_filter(
+            event_filter,
+            event_type=event_type,
+            predicate=predicate,
+        )
+        if self._history is None:
+            return None
+        if event_filter is None and event_type is None and predicate is None:
+            return self._history.latest()
+        return self._history.latest(normalized_filter)
+
+    def query(
+        self,
+        *,
+        event_filter: EventFilter[T] | None = None,
+        event_type: EventType | None = None,
+        predicate: Callable[[T], bool] | None = None,
+        limit: int | None = None,
+    ) -> tuple[T, ...]:
+        _validate_query_limit(limit)
+        normalized_filter = coerce_event_filter(
+            event_filter,
+            event_type=event_type,
+            predicate=predicate,
+        )
+        if self._history is None:
+            return ()
+        if event_filter is None and event_type is None and predicate is None:
+            return self._history.query(limit=limit)
+        return self._history.query(normalized_filter, limit=limit)
+
+    @staticmethod
+    def _is_async_handler(handler: Any) -> bool:
+        if inspect.iscoroutinefunction(handler):
+            return True
+        return callable(handler) and inspect.iscoroutinefunction(type(handler).__call__)

eventflow/callback.py

@@ -0,0 +1,318 @@
+"""Configurable callback registrations, independent of transport and event bus."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import math
+import threading
+import time
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from ._callbacks import synchronous_result
+from .compatibility import ExceptionGroup
+from .errors import CallbackTimeoutError
+from ._lifecycle import finish_cleanup
+from .subscription import Subscription
+
+
+async def _cancel_task(task: asyncio.Future[Any]) -> None:
+    task.cancel()
+    await finish_cleanup(asyncio.gather(task, return_exceptions=True))
+
+
+@dataclass(slots=True)
+class CallbackContext:
+    event: Any
+    result: Any = None
+    error: BaseException | None = None
+    elapsed: float = 0.0
+
+
+class CallbackSubscription(Subscription):
+    """Callable decorator result with execution policy and per-registration hooks.
+
+    Predicates run at delivery time. Rate-limited/disabled/filtered events do
+    not consume max_calls. Sync timeout is observational, never thread killing.
+    Hooks receive CallbackContext and run outside the registration lock.
+    """
+
+    def __init__(
+        self,
+        identifier: int,
+        cancel: Callable[[], None],
+        callback: Callable,
+        *,
+        asynchronous: bool = False,
+        once: bool = False,
+        max_calls: int | None = None,
+        frequency_hz: float | None = None,
+        timeout: float | None = None,
+        predicate: Callable | None = None,
+        enabled: bool = True,
+        on_before: Callable | None = None,
+        on_success: Callable | None = None,
+        on_error: Callable | None = None,
+        on_timeout: Callable | None = None,
+        on_after: Callable | None = None,
+    ) -> None:
+        super().__init__(identifier, cancel)
+        if once and max_calls is not None:
+            raise ValueError("once and max_calls cannot be combined")
+        if max_calls is not None and (
+            isinstance(max_calls, bool) or not isinstance(max_calls, int) or max_calls < 1
+        ):
+            raise ValueError("max_calls must be a positive integer")
+        for value in (frequency_hz, timeout):
+            if value is not None and (
+                isinstance(value, bool) or not math.isfinite(value) or value <= 0
+            ):
+                raise ValueError("frequency_hz and timeout must be positive and finite")
+        if not isinstance(enabled, bool):
+            raise TypeError("enabled must be a bool")
+        if predicate is not None and (
+            not callable(predicate) or inspect.iscoroutinefunction(predicate)
+        ):
+            raise TypeError("predicate must be a synchronous callable")
+        self.callback = callback
+        self.asynchronous = asynchronous
+        self.timeout = timeout
+        self.predicate = predicate
+        self._enabled = enabled
+        self._maximum = 1 if once else max_calls
+        self._interval = 0.0 if frequency_hz is None else 1.0 / frequency_hz
+        self._last = float("-inf")
+        self._calls = 0
+        self._policy_lock = threading.RLock()
+        self._hooks: dict[str, list[Callable]] = {}
+        for name, hook in (
+            ("before", on_before),
+            ("success", on_success),
+            ("error", on_error),
+            ("timeout", on_timeout),
+            ("after", on_after),
+        ):
+            if hook is not None:
+                self._hook(name, hook)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.callback(*args, **kwargs)
+
+    @property
+    def enabled(self) -> bool:
+        with self._policy_lock:
+            return self._enabled
+
+    def enable(self) -> None:
+        with self._policy_lock:
+            self._enabled = True
+
+    def disable(self) -> None:
+        with self._policy_lock:
+            self._enabled = False
+
+    def _hook(self, name: str, callback: Callable) -> Callable:
+        if not callable(callback):
+            raise TypeError("Hook must be callable")
+        asynchronous = inspect.iscoroutinefunction(callback) or inspect.iscoroutinefunction(
+            type(callback).__call__
+        )
+        if asynchronous != self.asynchronous:
+            raise TypeError("Hook must match callback sync/async mode")
+        with self._policy_lock:
+            self._hooks.setdefault(name, []).append(callback)
+        return callback
+
+    def on_before(self, callback: Callable) -> Callable:
+        return self._hook("before", callback)
+
+    def on_success(self, callback: Callable) -> Callable:
+        return self._hook("success", callback)
+
+    def on_error(self, callback: Callable) -> Callable:
+        return self._hook("error", callback)
+
+    def on_timeout(self, callback: Callable) -> Callable:
+        return self._hook("timeout", callback)
+
+    def on_after(self, callback: Callable) -> Callable:
+        return self._hook("after", callback)
+
+    def _accept(self, event: Any) -> bool:
+        if not self.active or not self.enabled:
+            return False
+        if self.predicate is not None:
+            accepted = self.predicate(event)
+            if inspect.isawaitable(accepted):
+                if inspect.iscoroutine(accepted):
+                    accepted.close()
+                raise TypeError("predicate returned an awaitable")
+            if not isinstance(accepted, bool):
+                raise TypeError("predicate must return bool")
+            if not accepted:
+                return False
+        with self._policy_lock:
+            now = time.monotonic()
+            if not self.active or not self._enabled or now - self._last < self._interval:
+                return False
+            if self._maximum is not None and self._calls >= self._maximum:
+                return False
+            self._calls += 1
+            self._last = now
+            exhausted = self._calls == self._maximum
+        if exhausted:
+            self.cancel()
+        return True
+
+    def _snapshot(self, name: str) -> tuple[Callable, ...]:
+        with self._policy_lock:
+            return tuple(self._hooks.get(name, ()))
+
+    def _run_hooks(self, name: str, context: CallbackContext) -> None:
+        errors = []
+        for hook in self._snapshot(name):
+            try:
+                synchronous_result(hook(context))
+            except Exception as error:
+                errors.append(error)
+        self._raise_errors(errors)
+
+    async def _run_hooks_async(self, name: str, context: CallbackContext) -> None:
+        errors = []
+        for hook in self._snapshot(name):
+            try:
+                await hook(context)
+            except Exception as error:
+                errors.append(error)
+        self._raise_errors(errors)
+
+    @staticmethod
+    def _raise_errors(errors: list[Exception]) -> None:
+        if len(errors) == 1:
+            raise errors[0]
+        if errors:
+            raise ExceptionGroup("Callback and hook failures", errors)
+
+    def _report_failure(self, name: str, context: CallbackContext, error: Exception) -> None:
+        context.error = error
+        try:
+            self._run_hooks(name, context)
+        except Exception as hook_error:
+            raise ExceptionGroup("Callback and error hook failed", [error, hook_error]) from None
+
+    async def _report_failure_async(
+        self, name: str, context: CallbackContext, error: Exception
+    ) -> None:
+        context.error = error
+        try:
+            await self._run_hooks_async(name, context)
+        except Exception as hook_error:
+            raise ExceptionGroup("Callback and error hook failed", [error, hook_error]) from None
+
+    def invoke(self, event: Any) -> Any:
+        context = CallbackContext(event)
+        started = time.monotonic()
+        try:
+            if not self._accept(event):
+                return None
+        except Exception as error:
+            self._report_failure("error", context, error)
+            raise
+        try:
+            self._run_hooks("before", context)
+            context.result = self.callback(event)
+            if inspect.isawaitable(context.result):
+                if inspect.iscoroutine(context.result):
+                    context.result.close()
+                raise TypeError("Sync callback returned an awaitable")
+            context.elapsed = time.monotonic() - started
+            if self.timeout is not None and context.elapsed > self.timeout:
+                raise CallbackTimeoutError("Callback exceeded its synchronous time budget")
+            self._run_hooks("success", context)
+        except Exception as error:
+            self._report_failure(
+                "timeout" if isinstance(error, CallbackTimeoutError) else "error", context, error
+            )
+            raise
+        else:
+            return context.result
+        finally:
+            context.elapsed = time.monotonic() - started
+            pending = sys.exc_info()[1]
+            try:
+                self._run_hooks("after", context)
+            except Exception as error:
+                failures = [pending] if isinstance(pending, Exception) else []
+                try:
+                    self._report_failure("error", context, error)
+                except Exception as report_error:
+                    failures.append(report_error)
+                else:
+                    failures.append(error)
+                if pending is not None and not isinstance(pending, Exception):
+                    raise pending from ExceptionGroup("Cleanup failed", failures)
+                self._raise_errors(failures)
+
+    async def invoke_async(self, event: Any) -> Any:
+        context = CallbackContext(event)
+        started = time.monotonic()
+        try:
+            if not self._accept(event):
+                return None
+        except Exception as error:
+            await self._report_failure_async("error", context, error)
+            raise
+        try:
+            await self._run_hooks_async("before", context)
+            operation = self.callback(event)
+            if self.timeout is None:
+                context.result = await operation
+            else:
+                remaining = self.timeout - (time.monotonic() - started)
+                if remaining <= 0:
+                    if inspect.iscoroutine(operation):
+                        operation.close()
+                    else:
+                        await _cancel_task(asyncio.ensure_future(operation))
+                    raise CallbackTimeoutError("Callback exceeded its asynchronous time budget")
+                task = asyncio.ensure_future(operation)
+                try:
+                    done, _ = await asyncio.wait({task}, timeout=remaining)
+                except asyncio.CancelledError:
+                    await _cancel_task(task)
+                    raise
+                if task not in done:
+                    await _cancel_task(task)
+                    raise CallbackTimeoutError("Callback exceeded its asynchronous time budget")
+                context.result = await task
+            context.elapsed = time.monotonic() - started
+            await self._run_hooks_async("success", context)
+        except asyncio.CancelledError as error:
+            context.error = error
+            raise
+        except Exception as error:
+            await self._report_failure_async(
+                "timeout" if isinstance(error, CallbackTimeoutError) else "error", context, error
+            )
+            raise
+        else:
+            return context.result
+        finally:
+            context.elapsed = time.monotonic() - started
+            pending = sys.exc_info()[1]
+            try:
+                await self._run_hooks_async("after", context)
+            except Exception as error:
+                failures = [pending] if isinstance(pending, Exception) else []
+                try:
+                    await self._report_failure_async("error", context, error)
+                except Exception as report_error:
+                    failures.append(report_error)
+                else:
+                    failures.append(error)
+                if pending is not None and not isinstance(pending, Exception):
+                    raise pending from ExceptionGroup("Cleanup failed", failures)
+                self._raise_errors(failures)

eventflow/compatibility.py

@@ -0,0 +1,14 @@
+"""Expose standard-library features across supported Python versions."""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 11):
+    from builtins import BaseExceptionGroup, ExceptionGroup
+    from enum import StrEnum
+else:  # pragma: no cover - exercised by the Python 3.10 environment
+    from backports.strenum import StrEnum
+    from exceptiongroup import BaseExceptionGroup, ExceptionGroup
+
+__all__ = ["BaseExceptionGroup", "ExceptionGroup", "StrEnum"]

eventflow/context.py

@@ -0,0 +1,103 @@
+"""Optional immutable event envelopes and task-local correlation identifiers."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from copy import deepcopy
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from types import MappingProxyType
+from typing import Any, Generic, TypeVar
+from uuid import uuid4
+
+T = TypeVar("T")
+_correlation: ContextVar[str | None] = ContextVar("eventflow_correlation", default=None)
+__all__ = ["EventEnvelope", "correlation_context", "current_correlation_id"]
+
+
+def current_correlation_id() -> str | None:
+    """Return the identifier in the current context, if one was bound."""
+    return _correlation.get()
+
+
+class _ReadOnlyMetadata(Mapping[str, object]):
+    """Copied read-only metadata that supports deepcopy and pickle."""
+
+    __slots__ = ("_mapping",)
+
+    def __init__(self, values: Mapping[str, object]) -> None:
+        self._mapping = MappingProxyType(dict(values))
+
+    def __getitem__(self, key: str) -> object:
+        return self._mapping[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._mapping)
+
+    def __len__(self) -> int:
+        return len(self._mapping)
+
+    def __repr__(self) -> str:
+        return f"mappingproxy({dict(self._mapping)!r})"
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> dict[str, object]:
+        return deepcopy(dict(self._mapping), memo)
+
+    def __reduce__(self) -> tuple[type[_ReadOnlyMetadata], tuple[dict[str, object]]]:
+        return type(self), (dict(self._mapping),)
+
+
+@contextmanager
+def correlation_context(correlation_id: str) -> Iterator[str]:
+    """Bind an identifier until exit; nested and async task contexts are isolated."""
+    if not isinstance(correlation_id, str) or not correlation_id.strip():
+        raise ValueError("Correlation ID must be a non-empty string")
+    token = _correlation.set(correlation_id)
+    try:
+        yield correlation_id
+    finally:
+        _correlation.reset(token)
+
+
+@dataclass(frozen=True)
+class EventEnvelope(Generic[T]):
+    """Opt-in event metadata; metadata is copied and shallowly read-only.
+
+    The payload and nested metadata values retain their original mutability.
+    A missing correlation ID inherits the current context or the envelope ID.
+    """
+
+    event: T
+    id: str = field(default_factory=lambda: uuid4().hex)
+    correlation_id: str | None = None
+    source: str | None = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.id, str) or not self.id.strip():
+            raise ValueError("Envelope ID must be a non-empty string")
+        correlation = self.correlation_id
+        if correlation is None:
+            correlation = current_correlation_id() or self.id
+        if not isinstance(correlation, str) or not correlation.strip():
+            raise ValueError("Correlation ID must be a non-empty string")
+        if not isinstance(self.timestamp, datetime) or self.timestamp.utcoffset() is None:
+            raise ValueError("Envelope timestamp must be timezone-aware")
+        object.__setattr__(self, "timestamp", self.timestamp.astimezone(timezone.utc))
+        object.__setattr__(self, "correlation_id", correlation)
+        object.__setattr__(self, "metadata", _ReadOnlyMetadata(self.metadata))
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> EventEnvelope[T]:
+        existing = memo.get(id(self))
+        if existing is not None:
+            return existing
+        copied = type(self).__new__(type(self))
+        memo[id(self)] = copied
+        for name in ("event", "id", "correlation_id", "source", "timestamp"):
+            object.__setattr__(copied, name, deepcopy(getattr(self, name), memo))
+        metadata = deepcopy(dict(self.metadata), memo)
+        object.__setattr__(copied, "metadata", _ReadOnlyMetadata(metadata))
+        return copied

eventflow/contracts.py

@@ -0,0 +1,40 @@
+"""Small shared contracts used by synchronous and asynchronous event buses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .compatibility import StrEnum
+
+
+class ErrorPolicy(StrEnum):
+    """Define how subscriber failures are reported by publish operations."""
+
+    ISOLATE = "isolate"
+    RAISE = "raise"
+
+
+class DeliveryMode(StrEnum):
+    """Define ordering for asynchronous subscriber delivery."""
+
+    SEQUENTIAL = "sequential"
+    CONCURRENT = "concurrent"
+
+
+@dataclass(frozen=True, slots=True)
+class PublishResult:
+    matched: int = 0
+    delivered: int = 0
+    failed: int = 0
+    errors: tuple[Exception, ...] = ()
+
+    @property
+    def successful(self) -> bool:
+        return self.failed == 0
+
+
+@dataclass(frozen=True, slots=True)
+class EventBusStats:
+    published: int = 0
+    delivered: int = 0
+    failed: int = 0