python-neva 3.4.0__tar.gz → 3.5.0__tar.gz

{python_neva-3.4.0 → python_neva-3.5.0}/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 3.5.0 (2026-06-11)
+
+### ✨ Features
+
+- **arch**: improve app facade stub
+- **events**: make the event facade properly depend on the dispatcher contract
+- **events**: new tests for events
+
+### 🐛🚑️ Fixes
+
+- **events**: fixing handling of async before-dispatch hooks
+
+### 🏷️ Types
+
+- **events**: improve event facade stub
+
 ## 3.4.0 (2026-06-10)
 
 ### ✨ Features

{python_neva-3.4.0 → python_neva-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-neva
-Version: 3.4.0
+Version: 3.5.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0

{python_neva-3.4.0 → python_neva-3.5.0}/neva/events/dispatcher.py

@@ -1,5 +1,6 @@
 """Base implementation of the event dispatcher."""
 
+import inspect
 from typing import override
 
 from neva.arch.application import Application
@@ -35,11 +36,9 @@ class EventDispatcher(contracts.EventDispatcher):
             event: The event about to be dispatched.
         """
         for hook in self._before_dispatch_hooks:
-            match hook:
-                case contracts.AsyncBeforeDispatchHook():
-                    await hook(event)
-                case contracts.SyncBeforeDispatchHook():
-                    hook(event)
+            result = hook(event)
+            if inspect.isawaitable(result):
+                await result
 
     @override
     async def before_dispatch(self, hook: contracts.BeforeDispatchHook) -> None:

python_neva-3.5.0/neva/support/facade/app.pyi

@@ -0,0 +1,47 @@
+"""Type stub for App facade."""
+
+from contextlib import AbstractAsyncContextManager
+from typing import Any, Self, override
+
+from neva.arch import Facade
+from neva.arch.scopes import BaseScope
+from neva.support import Result
+
+class App(Facade):
+    @classmethod
+    @override
+    def get_facade_accessor(cls) -> type: ...
+    @classmethod
+    async def make_async[T](cls, interface: type[T]) -> Result[T, str]:
+        """Resolve and instanciate a type from the container.
+
+        Returns:
+            Result containing the resolved type instance or an error message.
+        """
+
+    @classmethod
+    def make[T](cls, interface: type[T]) -> Result[T, str]:
+        """Resolve an interface from the container by its alias.
+
+        Attempts to retrieve and instantiate an object from the dependency
+        injection container.
+
+        Args:
+            interface: The interface to resolve.
+
+        Returns:
+            Result containing the resolved service instance or an error message.
+
+        """
+
+    @classmethod
+    async def scope(
+        cls,
+        scope: BaseScope | None = None,
+        context: dict[type, Any] | None = None,
+    ) -> AbstractAsyncContextManager[Self]:
+        """Enter a new scope.
+
+        Yields:
+            The application instance with the new scope.
+        """

{python_neva-3.4.0 → python_neva-3.5.0}/neva/support/facade/event.py

@@ -5,7 +5,7 @@ from contextlib import contextmanager
 from typing import TYPE_CHECKING, override
 
 from neva.arch import Facade
-from neva.events import EventDispatcher
+from neva.events import contracts
 
 
 if TYPE_CHECKING:
@@ -23,7 +23,7 @@ class Event(Facade):
         Returns:
             EventDispatcher class.
         """
-        return EventDispatcher
+        return contracts.EventDispatcher
 
     @classmethod
     def fake(cls) -> "EventFake":

{python_neva-3.4.0 → python_neva-3.5.0}/neva/support/facade/event.pyi

@@ -13,10 +13,15 @@ class Event(Facade):
     @override
     def get_facade_accessor(cls) -> type: ...
     @classmethod
-    async def dispatch(cls, event: contracts.Event) -> list[Result[None, str]]: ...
+    async def before_dispatch(cls, hook: contracts.BeforeDispatchHook) -> None:
+        """Register a hook to be called before listeners are invoked."""
+    @classmethod
+    async def dispatch(cls, event: contracts.Event) -> list[Result[None, str]]:
+        """Dispatch an event to all registered listeners."""
     @classmethod
     def listen[T: contracts.Event](
         cls,
         event_cls: type[T],
         listener_cls: type[contracts.EventListener[T]],
-    ) -> None: ...
+    ) -> None:
+        """Register a listener for an event."""

{python_neva-3.4.0 → python_neva-3.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-neva"
-version = "3.4.0"
+version = "3.5.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12"

python_neva-3.5.0/tests/events/test_before_dispatch.py

@@ -0,0 +1,177 @@
+"""Before-dispatch hook tests."""
+
+from typing import override
+
+import pytest
+
+from neva.database.manager import DatabaseManager
+from neva.events import EventDispatcher, EventListener, HandlingPolicy
+from neva.events.contracts.event import Event
+from neva.support import Ok, Result
+from tests.events.conftest import OrderPlaced, UserCreated
+
+
+class TestBeforeDispatchHook:
+    async def test_async_hook_is_called_on_dispatch(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        called = False
+
+        async def hook(context: Event) -> None:
+            nonlocal called
+            called = True
+
+        await dispatcher.before_dispatch(hook)
+        _ = await dispatcher.dispatch(OrderPlaced(event_id=1, order_id=1))
+
+        assert called
+
+    async def test_sync_hook_is_called_on_dispatch(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        called = False
+
+        def hook(context: Event) -> None:
+            nonlocal called
+            called = True
+
+        await dispatcher.before_dispatch(hook)
+        _ = await dispatcher.dispatch(OrderPlaced(event_id=1, order_id=1))
+
+        assert called
+
+    async def test_hook_receives_the_dispatched_event(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        received: Event | None = None
+
+        async def hook(context: Event) -> None:
+            nonlocal received
+            received = context
+
+        await dispatcher.before_dispatch(hook)
+        event = OrderPlaced(event_id=2, order_id=42)
+        _ = await dispatcher.dispatch(event)
+
+        assert received is event
+
+    async def test_hooks_called_in_registration_order(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        order: list[str] = []
+
+        async def first(context: Event) -> None:
+            order.append("first")
+
+        def second(context: Event) -> None:
+            order.append("second")
+
+        await dispatcher.before_dispatch(first)
+        await dispatcher.before_dispatch(second)
+        _ = await dispatcher.dispatch(OrderPlaced(event_id=1, order_id=1))
+
+        assert order == ["first", "second"]
+
+    async def test_hook_runs_before_listeners(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        order: list[str] = []
+
+        async def hook(context: Event) -> None:
+            order.append("hook")
+
+        class OrderPlacedListener(EventListener[OrderPlaced]):
+            @override
+            async def handle(self, event: OrderPlaced) -> Result[None, str]:
+                order.append("listener")
+                return Ok(None)
+
+        await dispatcher.before_dispatch(hook)
+        dispatcher.listen(OrderPlaced, OrderPlacedListener)
+        _ = await dispatcher.dispatch(OrderPlaced(event_id=1, order_id=1))
+
+        assert order == ["hook", "listener"]
+
+    async def test_hook_fires_with_no_listeners(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        called = False
+
+        async def hook(context: Event) -> None:
+            nonlocal called
+            called = True
+
+        await dispatcher.before_dispatch(hook)
+        results = await dispatcher.dispatch(OrderPlaced(event_id=1, order_id=1))
+
+        assert called
+        assert results == []
+
+    async def test_hook_fires_once_per_dispatch(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        call_count = 0
+
+        async def hook(context: Event) -> None:
+            nonlocal call_count
+            call_count += 1
+
+        await dispatcher.before_dispatch(hook)
+        _ = await dispatcher.dispatch(OrderPlaced(event_id=1, order_id=1))
+        _ = await dispatcher.dispatch(OrderPlaced(event_id=2, order_id=2))
+
+        assert call_count == 2
+
+    async def test_no_hooks_registered_is_a_noop(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        results = await dispatcher.dispatch(OrderPlaced(event_id=1, order_id=1))
+
+        assert results == []
+
+
+class TestBeforeDispatchWithTransaction:
+    async def test_hook_fires_at_dispatch_time_for_deferred_event(
+        self, dispatcher: EventDispatcher, db: DatabaseManager
+    ) -> None:
+        hook_calls: list[str] = []
+
+        async def hook(context: Event) -> None:
+            hook_calls.append("hook")
+
+        class UserCreatedListener(EventListener[UserCreated]):
+            policy = HandlingPolicy.DEFERRED
+
+            @override
+            async def handle(self, event: UserCreated) -> Result[None, str]:
+                hook_calls.append("listener")
+                return Ok(None)
+
+        await dispatcher.before_dispatch(hook)
+        dispatcher.listen(UserCreated, UserCreatedListener)
+
+        async with db.begin():
+            _ = await dispatcher.dispatch(UserCreated(event_id=1, user_id=1))
+            # Hook runs eagerly even though the listener is deferred.
+            assert hook_calls == ["hook"]
+
+        assert hook_calls == ["hook", "listener"]
+
+    async def test_hook_fires_even_when_transaction_rolls_back(
+        self, dispatcher: EventDispatcher, db: DatabaseManager
+    ) -> None:
+        called = False
+
+        async def hook(context: Event) -> None:
+            nonlocal called
+            called = True
+
+        await dispatcher.before_dispatch(hook)
+
+        with pytest.raises(RuntimeError):
+            async with db.begin():
+                _ = await dispatcher.dispatch(UserCreated(event_id=1, user_id=1))
+                msg = "rollback"
+                raise RuntimeError(msg)
+
+        assert called

{python_neva-3.4.0 → python_neva-3.5.0}/uv.lock

@@ -1733,7 +1733,7 @@ wheels = [
 
 [[package]]
 name = "python-neva"
-version = "3.4.0"
+version = "3.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },

python_neva-3.4.0/neva/support/facade/app.pyi

@@ -1,25 +0,0 @@
-"""Type stub for App facade."""
-
-from typing import override
-
-from neva.arch import Facade
-from neva.support import Result
-
-class App(Facade):
-    @classmethod
-    @override
-    def get_facade_accessor(cls) -> type: ...
-    @classmethod
-    def make[T](cls, interface: type[T]) -> Result[T, str]:
-        """Resolve an interface from the container by its alias.
-
-        Attempts to retrieve and instantiate an object from the dependency
-        injection container.
-
-        Args:
-            interface: The interface to resolve.
-
-        Returns:
-            Result containing the resolved service instance or an error message.
-
-        """