python-neva 3.2.0__py3-none-any.whl → 3.3.0__py3-none-any.whl

neva/events/__init__.py

@@ -9,7 +9,8 @@ Three components are of particular interest:
 
 from neva.events.dispatcher import EventDispatcher
 from neva.events.event import Event
-from neva.events.listener import EventListener, HandlingPolicy, listener
+from neva.events.listener import EventListener, listener
+from neva.events.policy import HandlingPolicy
 from neva.events.provider import EventServiceProvider
 
 

neva/events/contracts/__init__.py

@@ -0,0 +1,7 @@
+from neva.events.contracts.dispatcher import EventDispatcher
+from neva.events.contracts.event import Event
+from neva.events.contracts.handler import EventHandler
+from neva.events.contracts.listener import EventListener
+
+
+__all__ = ["Event", "EventDispatcher", "EventHandler", "EventListener"]

neva/events/contracts/dispatcher.py

@@ -0,0 +1,24 @@
+from typing import Protocol
+
+from neva.events.contracts.event import Event
+from neva.events.contracts.listener import EventListener
+from neva.support import Result
+
+
+class EventDispatcher(Protocol):
+    """Event dispatcher protocol."""
+
+    async def dispatch(
+        self,
+        event: Event,
+    ) -> list[Result[None, str]]:
+        """Dispatch an event to all registered listeners."""
+        ...
+
+    def listen[T: Event](
+        self,
+        event_cls: type[T],
+        listener_cls: type[EventListener[T]],
+    ) -> None:
+        """Register a listener for an event."""
+        ...

neva/events/contracts/event.py

@@ -0,0 +1,7 @@
+import pydantic
+
+
+class Event(pydantic.BaseModel):
+    """Base Event class."""
+
+    pass

neva/events/contracts/handler.py

@@ -0,0 +1,14 @@
+from typing import Protocol
+
+from neva.events.contracts.event import Event
+from neva.support import Result
+
+
+class EventHandler[T: Event](Protocol):
+    """Define a valid function for event handling."""
+
+    __name__: str
+
+    async def __call__(self, event: T) -> Result[None, str]:
+        """Handle an event."""
+        ...

neva/events/contracts/listener.py

@@ -0,0 +1,19 @@
+from typing import Protocol
+
+from neva.events.contracts.event import Event
+from neva.events.policy import HandlingPolicy
+from neva.support import Result
+
+
+class EventListener[T: Event](Protocol):
+    """Event listener protocol."""
+
+    policy: HandlingPolicy
+
+    async def handle(self, event: T) -> Result[None, str]:
+        """Handle an event.
+
+        Returns:
+            A result indicating whether the event was handled successfully.
+        """
+        ...

neva/events/dispatcher.py

@@ -1,15 +1,29 @@
 """Base implementation of the event dispatcher."""
 
+from typing import Callable, Protocol, override, runtime_checkable
+
 from neva.arch.application import Application
 from neva.database.manager import DatabaseManager
 from neva.database.transaction import TransactionCallback
-from neva.events.event import Event
+from neva.events import contracts
 from neva.events.event_registry import EventRegistry
-from neva.events.listener import EventListener
 from neva.support import Err, Nothing, Result, Some
 
 
-class EventDispatcher:
+@runtime_checkable
+class AsyncBeforeDispatchHook(Protocol):
+    async def __call__(self, context: contracts.Event) -> None: ...
+
+
+@runtime_checkable
+class SyncBeforeDispatchHook(Protocol):
+    def __call__(self, context: contracts.Event) -> None: ...
+
+
+BeforeDispatchHook = AsyncBeforeDispatchHook | SyncBeforeDispatchHook
+
+
+class EventDispatcher(contracts.EventDispatcher):
     """Event dispatcher implementation."""
 
     def __init__(
@@ -18,11 +32,12 @@ class EventDispatcher:
         db: DatabaseManager,
         registry: EventRegistry,
     ) -> None:
-        self._registry = registry
-        self._app = app
-        self._db = db
+        self._registry: EventRegistry = registry
+        self._app: Application = app
+        self._db: DatabaseManager = db
+        self._before_dispatch_hooks: list[BeforeDispatchHook] = []
 
-    async def _before_dispatch(self, event: Event) -> None:
+    async def _apply_before_dispatch(self, event: contracts.Event) -> None:
         """Extension hook called before listeners are invoked.
 
         Override in a subclass to add cross-cutting behaviour such as
@@ -32,8 +47,19 @@ class EventDispatcher:
         Args:
             event: The event about to be dispatched.
         """
-
-    async def dispatch(self, event: Event) -> list[Result[None, str]]:
+        for hook in self._before_dispatch_hooks:
+            match hook:
+                case AsyncBeforeDispatchHook():
+                    await hook(event)
+                case SyncBeforeDispatchHook():
+                    hook(event)
+
+    async def before_dispatch(self, hook: BeforeDispatchHook) -> None:
+        """Register a hook to be called before listeners are invoked."""
+        self._before_dispatch_hooks.append(hook)
+
+    @override
+    async def dispatch(self, event: contracts.Event) -> list[Result[None, str]]:
         """Dispatch an event to all registered listeners.
 
         Listeners are resolved from the DI container when available,
@@ -45,20 +71,23 @@ class EventDispatcher:
         Returns:
             A list of results, one per listener invocation.
         """
-        await self._before_dispatch(event)
+        await self._apply_before_dispatch(event)
         results: list[Result[None, str]] = []
-        listeners = self._registry.get_listeners(event)
+        listeners = self._registry.resolve_listeners(event)
 
-        to_execute = listeners.immediate.copy()
+        immediate: list[type[contracts.EventListener[contracts.Event]]] = []
+        deferred: list[type[contracts.EventListener[contracts.Event]]] = []
+        [immediate.extend(listener.immediate.copy()) for listener in listeners]
+        [deferred.extend(listener.deferred.copy()) for listener in listeners]
 
         match self._db.current():
             case Some(tx):
-                for listener_cls in listeners.deferred:
+                for listener_cls in deferred:
                     _ = tx.on_commit(self._build_callback(event, listener_cls))
             case Nothing():
-                to_execute += listeners.deferred
+                immediate.extend(deferred)
 
-        for listener_cls in to_execute:
+        for listener_cls in immediate:
             listener = self._resolve_listener(listener_cls)
             try:
                 results.append(await listener.handle(event))
@@ -67,17 +96,20 @@ class EventDispatcher:
 
         return results
 
-    def listen[T: Event](
+    @override
+    def listen[T: contracts.Event](
         self,
-        event_cls: type[T],
-        listener_cls: type[EventListener[T]],
+        event_cls: type[T] | list[type[T]],
+        listener_cls: type[contracts.EventListener[T]],
     ) -> None:
         """Register a listener for an event."""
+        if not isinstance(event_cls, list):
+            event_cls = [event_cls]
         self._registry.register(event_cls, listener_cls)
 
-    def _resolve_listener[T: Event](
-        self, listener_cls: type[EventListener[T]]
-    ) -> EventListener[T]:
+    def _resolve_listener[T: contracts.Event](
+        self, listener_cls: type[contracts.EventListener[T]]
+    ) -> contracts.EventListener[T]:
         """Resolve a listener from the container.
 
         Listeners are resolved from the DI container when available,
@@ -91,10 +123,10 @@ class EventDispatcher:
             return result.unwrap()
         return listener_cls()
 
-    def _build_callback[T: Event](
+    def _build_callback[T: contracts.Event](
         self,
         event: T,
-        listener_cls: type[EventListener[T]],
+        listener_cls: type[contracts.EventListener[T]],
     ) -> TransactionCallback:
         async def callback() -> Result[None, str]:
             listener = self._resolve_listener(listener_cls)

neva/events/event.py

@@ -4,10 +4,11 @@ import datetime as dt
 
 import pydantic
 
+from neva.events import contracts
 from neva.support import time
 
 
-class Event[T](pydantic.BaseModel):
+class Event[T](contracts.Event):
     """Base event class."""
 
     event_id: T

neva/events/event_registry.py

@@ -1,27 +1,30 @@
 """Event/listener registry."""
 
-from typing import Any
+import inspect
+from typing import Any, TypeVar
 
-from neva.events.event import Event
-from neva.events.listener import EventListener, HandlingPolicy
+from neva.events import contracts, policy
 
 
-class EventListenerRegistry[T: Event]:
+class EventListenerRegistry[T: contracts.Event]:
     """Event listener registry for a given event."""
 
     def __init__(self) -> None:
-        self.immediate: list[type[EventListener[T]]] = []
-        self.deferred: list[type[EventListener[T]]] = []
+        self.immediate: list[type[contracts.EventListener[T]]] = []
+        self.deferred: list[type[contracts.EventListener[T]]] = []
 
-    def add_listener(self, listener_cls: type[EventListener[T]]) -> None:
+    def add_listener(self, listener_cls: type[contracts.EventListener[T]]) -> None:
         """Add a listener to the correct category in the registry."""
         match listener_cls.policy:
-            case HandlingPolicy.IMMEDIATE:
+            case policy.HandlingPolicy.IMMEDIATE:
                 self.immediate.append(listener_cls)
-            case HandlingPolicy.DEFERRED:
+            case policy.HandlingPolicy.DEFERRED:
                 self.deferred.append(listener_cls)
 
 
+T = TypeVar("T", bound=contracts.Event, covariant=True)
+
+
 class EventRegistry:
     """Event/listener registry."""
 
@@ -31,14 +34,26 @@ class EventRegistry:
         """Initialize the registry."""
         self.__listeners = {}
 
-    def register[T: Event](
-        self, event_cls: type[T], listener_cls: type[EventListener[T]]
+    def register(
+        self,
+        event_cls: list[type[T]],
+        listener_cls: type[contracts.EventListener[T]],
     ) -> None:
         """Register a listener for an event."""
-        self.__listeners.setdefault(event_cls, EventListenerRegistry()).add_listener(
-            listener_cls
-        )
-
-    def get_listeners[T: Event](self, event: T) -> EventListenerRegistry[T]:
+        for cls in event_cls:
+            self.__listeners.setdefault(cls, EventListenerRegistry()).add_listener(
+                listener_cls
+            )
+
+    def resolve_listeners(self, event: T) -> list[EventListenerRegistry[T]]:
+        """Return all listeners registries for an event type."""
+        registries = [
+            self.__listeners[cls]
+            for cls in inspect.getmro(type(event))
+            if cls in self.__listeners
+        ]
+        return registries
+
+    def get_listeners(self, event: T) -> EventListenerRegistry[T]:
         """Return all listeners registered for an event type."""
         return self.__listeners.get(type(event), EventListenerRegistry[T]())

neva/events/listener.py

@@ -1,49 +1,26 @@
 """Event listener protocol."""
 
-import abc
-from enum import StrEnum
 from types import new_class
-from typing import Callable, Protocol
+from typing import Callable, override
 
-from neva.events.event import Event
+from neva.events import contracts
+from neva.events.policy import HandlingPolicy
 from neva.support import Result
 from neva.support.strconv import snake2pascal
 
 
-class HandlingPolicy(StrEnum):
-    """Event dispatch policy."""
-
-    IMMEDIATE = "immediate"
-    DEFERRED = "deferred"
-
-
-class EventListener[T: Event](abc.ABC):
-    """Event listener protocol."""
+class EventListener[T: contracts.Event](contracts.EventListener[T]):
+    """Base event listener class."""
 
     policy: HandlingPolicy = HandlingPolicy.IMMEDIATE
 
-    @abc.abstractmethod
-    async def handle(self, event: T) -> Result[None, str]:
-        """Handle an event.
-
-        Returns:
-            A result indicating whether the event was handled successfully.
-        """
-
-
-class EventHandler[T: Event](Protocol):
-    """Define a valid function for event handling."""
-
-    __name__: str
-
-    async def __call__(self, event: T) -> Result[None, str]:
-        """Handle an event."""
-        ...
+    @override
+    async def handle(self, event: contracts.Event) -> Result[None, str]: ...
 
 
-def listener[T: Event](
+def listener[T: contracts.Event](
     policy: HandlingPolicy = HandlingPolicy.IMMEDIATE,
-) -> Callable[[EventHandler[T]], type[EventListener[T]]]:
+) -> Callable[[contracts.EventHandler[T]], type[EventListener[T]]]:
     """Create a listener from a function.
 
     Returns:
@@ -51,7 +28,7 @@ def listener[T: Event](
     """
 
     def decorator(
-        func: EventHandler[T],
+        func: contracts.EventHandler[T],
     ) -> type[EventListener[T]]:
         async def handle(_: EventListener[T], event: T) -> Result[None, str]:
             return await func(event)

neva/events/policy.py

@@ -0,0 +1,8 @@
+import enum
+
+
+class HandlingPolicy(enum.StrEnum):
+    """Determines when a listener is invoked."""
+
+    IMMEDIATE = "immediate"
+    DEFERRED = "deferred"

neva/events/provider.py

@@ -3,6 +3,8 @@
 from typing import Self, override
 
 from neva.arch.service_provider import ServiceProvider
+from neva.events import contracts
+from neva.events.dispatcher import EventDispatcher
 from neva.events.event_registry import EventRegistry
 from neva.support import Ok, Result
 
@@ -22,8 +24,7 @@ class EventServiceProvider(ServiceProvider):
         Returns:
             Result[Self, str]: The result of the registration.
         """
-        from neva.events.dispatcher import EventDispatcher
-
         self.bind(EventRegistry)
         self.bind(EventDispatcher)
+        self.bind(EventDispatcher, interface=contracts.EventDispatcher)
         return Ok(self)

{python_neva-3.2.0.dist-info → python_neva-3.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-neva
-Version: 3.2.0
+Version: 3.3.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0
@@ -20,3 +20,8 @@ Requires-Dist: neva-fastapi>=1.0.0; extra == 'fastapi'
 Provides-Extra: testing
 Requires-Dist: pytest-asyncio>=0.25.3; extra == 'testing'
 Requires-Dist: pytest>=9.0.2; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# The Neva framework
+
+PLACEHOLDER

{python_neva-3.2.0.dist-info → python_neva-3.3.0.dist-info}/RECORD

@@ -20,13 +20,19 @@ neva/database/manager.py,sha256=VNvhVumZD2hoGKpkdXMAkT6KykE4H80WcG2DgShK5Hs,4240
 neva/database/provider.py,sha256=l2be4Ri53RtQq1-qzohy3cqzJQpTaNzqXGVhXPKUCXc,1674
 neva/database/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neva/database/transaction.py,sha256=_0Dsao_vhCJT5YRUmrHOLb0uxvfdE-5k3n0yMPLC1o8,5167
-neva/events/__init__.py,sha256=xwIAXNcOASpuCY4DJpshZc1gtxQHimzwy-s7c-4QuiQ,746
-neva/events/dispatcher.py,sha256=mSjOvP1-new7z2QRBY3cbUzZ1Y_mlHSXMRt4NGhB8e0,3295
-neva/events/event.py,sha256=g3vAx-2qiR3QRM_or8G9mK5qx66A2LZiZ3n517R4lGQ,251
-neva/events/event_registry.py,sha256=jucYOUjCERz-ICdPiDrxYw_ySvmPJOcRzYKCgka29qY,1491
-neva/events/listener.py,sha256=-7RQOhVusKN8lopB3T2yfoQVlxX6GOSM5Pk1mPEMMro,1833
-neva/events/provider.py,sha256=HE7k915m8lQiqBC6kaGtb3ZfoxrgsuXXZmxkaaSnlmM,857
+neva/events/__init__.py,sha256=Gpi5q-pNlIi-q23U2ZOsNf8Y9rB6AQtsBbbBFU0tkFc,776
+neva/events/dispatcher.py,sha256=fFhF39sba1VOiwLa2eHzib5qWk4n_SOoWiYkmZL044o,4686
+neva/events/event.py,sha256=q-KyyxNkU3AN2YSaujuNPIoXQMXhGOwClTap5y8fU5I,282
+neva/events/event_registry.py,sha256=IZnpR3oLyvt5K2pn9KMCBw5W4JP7Ok_zMKI2SgQoXVM,1945
+neva/events/listener.py,sha256=2d5RHVKO0pU-eL_evLReTG0DIoX9tZyOcn8PWLeECZo,1435
+neva/events/policy.py,sha256=I67ziob0IEVeXdkilNPpj2f48gEz2EZneR1Fz8Nlt2U,154
+neva/events/provider.py,sha256=cVxADLv7VXCK6gTMJsDNRzspMOH2lrIkvMRhqVh2cK4,954
 neva/events/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+neva/events/contracts/__init__.py,sha256=6-xRFR_5t6PbU-owl0WtM8mmdvmNvuHPUyL1sbFfqU8,293
+neva/events/contracts/dispatcher.py,sha256=jJ4qLM_5-bXcBPH_txnbwHXAs6GFB080MiDkEViatTk,594
+neva/events/contracts/event.py,sha256=kUUECex_AlmaPJ-fXRg32eMkiqNS75CHldOr7bbpFqo,89
+neva/events/contracts/handler.py,sha256=SwLuuRtXhCzGkcBBLdH3MjUAkjEr0_rhqgE6dkWVJxI,327
+neva/events/contracts/listener.py,sha256=0xwPrjprkMzXu9vY1Z-EjSLFdvOUpomiE65hH16nfxA,465
 neva/obs/__init__.py,sha256=dVzgljk9Hvo44LI34RcwbDyT42_z4nSnFVmL4GLbKD0,331
 neva/obs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neva/obs/instrumentation/__init__.py,sha256=SfIAvuCs-L0kEzOxUJ4aOIkhbydCe7qBwWtGeDELVA0,36
@@ -85,6 +91,6 @@ neva/testing/fakes.py,sha256=5HuuwMeAKhFSZfn9T8raQIjdgHkjFeZsFXDud0T4v7Q,2674
 neva/testing/fixtures.py,sha256=oiPa5ntUkW-SbySDvwEHXtti8NqSwI-R0CT1_ezTx_Y,1445
 neva/testing/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neva/testing/test_case.py,sha256=zJBZJeKI-sv-EOaXNuSJ0V2Zp_6hdk64W4dOh0eP8RI,3290
-python_neva-3.2.0.dist-info/METADATA,sha256=2wZeNjt-ooHN3AIU1LE-K636R4shKM0-cIDXUGg1X2g,771
-python_neva-3.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-python_neva-3.2.0.dist-info/RECORD,,
+python_neva-3.3.0.dist-info/METADATA,sha256=7J-vn_EdbJAX-DgR0zsWf8NWVIq2BPd5Fp5YYiZcbic,846
+python_neva-3.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+python_neva-3.3.0.dist-info/RECORD,,