flowevent 1.2__py3-none-any.whl

eventflow/__init__.py

@@ -0,0 +1,123 @@
+"""Synchronous and asyncio-native in-process event delivery."""
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+__version__ = "1.2"
+
+from .actions import (
+    AsyncEventBusActions,
+    EventBusActions,
+    EventErrorContext,
+    EventTimeoutContext,
+)
+from .async_event_bus import AsyncEventBus
+from .base import BaseEventBus
+from .callback import CallbackContext, CallbackSubscription
+from .contracts import DeliveryMode, ErrorPolicy, EventBusStats, PublishResult
+from .engine import AsyncEventEngine, EventEngine
+from .errors import (
+    CallbackTimeoutError,
+    EventBusClosedError,
+    EventBusError,
+    EventShutdownTimeoutError,
+    InvalidEventHandlerError,
+)
+from .event_bus import EventBus
+from .filtering import EventFilter
+from .history import EventHistory, MemoryEventHistory
+from .subscription import AsyncSubscription, Subscription
+
+if TYPE_CHECKING:
+    from .context import EventEnvelope, correlation_context, current_correlation_id
+    from .observability import (
+        ExecutionMetrics,
+        PipelineObservation,
+        PipelineObserver,
+        PipelineStats,
+        PipelineStatsSnapshot,
+    )
+    from .pipeline import AsyncPipeline, Pipeline, PipelineExecutionError
+    from .scopes import AsyncCancelHandle, AsyncSubscriptionScope, CancelHandle, SubscriptionScope
+    from .stream import AsyncStream
+
+# Optional execution components load only when requested, keeping legacy bus
+# imports independent of pipeline, stream, context and observability modules.
+_OPTIONAL_EXPORTS = {
+    **dict.fromkeys(("EventEnvelope", "correlation_context", "current_correlation_id"), ".context"),
+    **dict.fromkeys(
+        (
+            "ExecutionMetrics",
+            "PipelineObservation",
+            "PipelineObserver",
+            "PipelineStats",
+            "PipelineStatsSnapshot",
+        ),
+        ".observability",
+    ),
+    **dict.fromkeys(("AsyncPipeline", "Pipeline", "PipelineExecutionError"), ".pipeline"),
+    **dict.fromkeys(
+        ("AsyncCancelHandle", "AsyncSubscriptionScope", "CancelHandle", "SubscriptionScope"),
+        ".scopes",
+    ),
+    "AsyncStream": ".stream",
+}
+
+
+def __getattr__(name: str) -> Any:
+    module = _OPTIONAL_EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(import_module(module, __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))
+
+
+__all__ = [
+    "__version__",
+    "AsyncEventBus",
+    "AsyncEventBusActions",
+    "AsyncEventEngine",
+    "AsyncSubscription",
+    "BaseEventBus",
+    "CallbackContext",
+    "CallbackSubscription",
+    "CallbackTimeoutError",
+    "DeliveryMode",
+    "ErrorPolicy",
+    "EventBus",
+    "EventBusActions",
+    "EventBusClosedError",
+    "EventBusError",
+    "EventBusStats",
+    "EventEngine",
+    "EventFilter",
+    "EventErrorContext",
+    "EventHistory",
+    "EventShutdownTimeoutError",
+    "EventTimeoutContext",
+    "InvalidEventHandlerError",
+    "MemoryEventHistory",
+    "PublishResult",
+    "Subscription",
+    "AsyncCancelHandle",
+    "AsyncPipeline",
+    "AsyncStream",
+    "AsyncSubscriptionScope",
+    "CancelHandle",
+    "EventEnvelope",
+    "ExecutionMetrics",
+    "Pipeline",
+    "PipelineExecutionError",
+    "PipelineObservation",
+    "PipelineObserver",
+    "PipelineStats",
+    "PipelineStatsSnapshot",
+    "SubscriptionScope",
+    "correlation_context",
+    "current_correlation_id",
+]

eventflow/_callbacks.py

@@ -0,0 +1,22 @@
+"""Callback guards shared by opt-in execution and lifecycle components."""
+
+import inspect
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def is_async_callable(callback: object) -> bool:
+    if not callable(callback):
+        return False
+    return inspect.iscoroutinefunction(callback) or inspect.iscoroutinefunction(
+        type(callback).__call__
+    )
+
+
+def synchronous_result(result: T) -> T:
+    if result is not None and inspect.isawaitable(result):
+        if inspect.iscoroutine(result):
+            result.close()
+        raise TypeError("Synchronous callback returned an awaitable")
+    return result

eventflow/_lifecycle.py

@@ -0,0 +1,31 @@
+"""Wait for owned cleanup even when the caller is cancelled repeatedly."""
+
+import asyncio
+from collections.abc import Awaitable
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+async def finish_cleanup(operation: Awaitable[T]) -> T:
+    task = asyncio.ensure_future(operation)
+    if task is asyncio.current_task():
+        raise RuntimeError("Cleanup cannot await itself")
+    cancellation: asyncio.CancelledError | None = None
+    if not task.done():
+        completed = asyncio.Event()
+        task.add_done_callback(lambda _task: completed.set())
+        while not task.done():
+            try:
+                await completed.wait()
+            except asyncio.CancelledError as exc:
+                cancellation = exc
+    try:
+        result = task.result()
+    except BaseException as error:
+        if cancellation is not None:
+            raise cancellation from error
+        raise
+    if cancellation is not None:
+        raise cancellation
+    return result

eventflow/actions.py

@@ -0,0 +1,53 @@
+"""Optional hooks shared by every operation on an event bus."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from .contracts import PublishResult
+from .filtering import EventFilter
+
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class EventErrorContext(Generic[T]):
+    event: T
+    error: Exception
+
+
+@dataclass(frozen=True)
+class EventTimeoutContext(Generic[T]):
+    event_filter: EventFilter[T]
+    timeout: float | None
+
+
+@dataclass(frozen=True)
+class EventBusActions(Generic[T]):
+    on_error: Callable[[EventErrorContext[T]], None] | None = None
+    on_timeout: Callable[[EventTimeoutContext[T]], None] | None = None
+    on_before: Callable[[T], None] | None = None
+    on_after: Callable[[T, PublishResult], None] | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("on_before", "on_after", "on_error", "on_timeout"):
+            action = getattr(self, name)
+            if action is not None and not callable(action):
+                raise TypeError(f"Event action {name} must be callable")
+
+
+@dataclass(frozen=True)
+class AsyncEventBusActions(Generic[T]):
+    on_error: Callable[[EventErrorContext[T]], Awaitable[None]] | None = None
+    on_timeout: Callable[[EventTimeoutContext[T]], Awaitable[None]] | None = None
+    on_before: Callable[[T], Awaitable[None]] | None = None
+    on_after: Callable[[T, PublishResult], Awaitable[None]] | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("on_before", "on_after", "on_error", "on_timeout"):
+            action = getattr(self, name)
+            if action is not None and not callable(action):
+                raise TypeError(f"Async event action {name} must be callable")