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

python_neva-3.5.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+## 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
+
+- **arch**: new from_context method
+- **tooling**: placeholder commit
+
+### 💚👷 CI & Build
+
+- **tooling**: default to base tag version for commitizen
+
+### 📝💡 Documentation
+
+- **project**: update doc
+- **core**: placeholde readme
+
+### 🔧🔨📦️ Configuration, Scripts, Packages
+
+- **tooling**: update changelog script
+- **project**: update versioning config

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

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

{python_neva-3.3.0 → python_neva-3.5.0}/neva/arch/service_provider.py

@@ -175,6 +175,10 @@ class ServiceProvider(abc.ABC):
         _ = self.provider.decorate(source, provides=interface, scope=scope, when=when)
         return self
 
+    def from_context(self, interface: type, scope: Scope | None = None) -> None:
+        """Declares an interface as provided by the current context."""
+        _ = self.provider.from_context(provides=interface, scope=scope)
+
     @abc.abstractmethod
     def register(self) -> Result[Self, str]:
         """Register services into the application container.

python_neva-3.5.0/neva/events/contracts/__init__.py

@@ -0,0 +1,20 @@
+from neva.events.contracts.dispatcher import (
+    AsyncBeforeDispatchHook,
+    BeforeDispatchHook,
+    EventDispatcher,
+    SyncBeforeDispatchHook,
+)
+from neva.events.contracts.event import Event
+from neva.events.contracts.handler import EventHandler
+from neva.events.contracts.listener import EventListener
+
+
+__all__ = [
+    "AsyncBeforeDispatchHook",
+    "BeforeDispatchHook",
+    "Event",
+    "EventDispatcher",
+    "EventHandler",
+    "EventListener",
+    "SyncBeforeDispatchHook",
+]

python_neva-3.5.0/neva/events/contracts/dispatcher.py

@@ -0,0 +1,47 @@
+from typing import Protocol, runtime_checkable
+
+from neva.events.contracts.event import Event
+from neva.events.contracts.listener import EventListener
+from neva.support import Result
+
+
+@runtime_checkable
+class AsyncBeforeDispatchHook(Protocol):
+    """Asynchronous hook to be called before listeners are invoked."""
+
+    async def __call__(self, context: Event) -> None:
+        """Execute the hook."""
+
+
+@runtime_checkable
+class SyncBeforeDispatchHook(Protocol):
+    """Synchronous hook to be called before listeners are invoked."""
+
+    def __call__(self, context: Event) -> None:
+        """Execute the hook."""
+
+
+BeforeDispatchHook = AsyncBeforeDispatchHook | SyncBeforeDispatchHook
+
+
+class EventDispatcher(Protocol):
+    """Event dispatcher protocol."""
+
+    async def dispatch(
+        self,
+        event: Event,
+    ) -> list[Result[None, str]]:
+        """Dispatch an event to all registered listeners."""
+        ...
+
+    async def before_dispatch(self, hook: BeforeDispatchHook) -> None:
+        """Register a hook to be called before listeners are invoked."""
+        ...
+
+    def listen[T: Event](
+        self,
+        event_cls: type[T],
+        listener_cls: type[EventListener[T]],
+    ) -> None:
+        """Register a listener for an event."""
+        ...

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

@@ -1,6 +1,7 @@
 """Base implementation of the event dispatcher."""
 
-from typing import Callable, Protocol, override, runtime_checkable
+import inspect
+from typing import override
 
 from neva.arch.application import Application
 from neva.database.manager import DatabaseManager
@@ -10,19 +11,6 @@ from neva.events.event_registry import EventRegistry
 from neva.support import Err, Nothing, Result, Some
 
 
-@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."""
 
@@ -35,7 +23,7 @@ class EventDispatcher(contracts.EventDispatcher):
         self._registry: EventRegistry = registry
         self._app: Application = app
         self._db: DatabaseManager = db
-        self._before_dispatch_hooks: list[BeforeDispatchHook] = []
+        self._before_dispatch_hooks: list[contracts.BeforeDispatchHook] = []
 
     async def _apply_before_dispatch(self, event: contracts.Event) -> None:
         """Extension hook called before listeners are invoked.
@@ -48,13 +36,12 @@ class EventDispatcher(contracts.EventDispatcher):
             event: The event about to be dispatched.
         """
         for hook in self._before_dispatch_hooks:
-            match hook:
-                case AsyncBeforeDispatchHook():
-                    await hook(event)
-                case SyncBeforeDispatchHook():
-                    hook(event)
+            result = hook(event)
+            if inspect.isawaitable(result):
+                await result
 
-    async def before_dispatch(self, hook: BeforeDispatchHook) -> None:
+    @override
+    async def before_dispatch(self, hook: contracts.BeforeDispatchHook) -> None:
         """Register a hook to be called before listeners are invoked."""
         self._before_dispatch_hooks.append(hook)
 

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.3.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.5.0/neva/support/facade/event.pyi

@@ -0,0 +1,27 @@
+"""Event facade."""
+
+from typing import override
+
+from neva.arch import Facade
+from neva.events import contracts
+from neva.support import Result
+
+class Event(Facade):
+    """Event system facade."""
+
+    @classmethod
+    @override
+    def get_facade_accessor(cls) -> type: ...
+    @classmethod
+    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:
+        """Register a listener for an event."""

{python_neva-3.3.0 → python_neva-3.5.0}/neva/testing/fakes.py

@@ -1,19 +1,20 @@
 """Testing fakes for Neva facades."""
 
 from collections.abc import Callable
-from typing import Any
+from typing import override
 
-from neva.events.event import Event as BaseEvent
+from neva.events import contracts
 from neva.support import Result
 
 
-class EventFake:
+class EventFake(contracts.EventDispatcher):
     """Recording fake for the Event facade. No listeners are dispatched."""
 
     def __init__(self) -> None:
-        self._dispatched: list[BaseEvent[Any]] = []
+        self._dispatched: list[contracts.Event] = []
 
-    async def dispatch(self, event: BaseEvent[Any]) -> list[Result[None, str]]:
+    @override
+    async def dispatch(self, event: contracts.Event) -> list[Result[None, str]]:
         """Record the event without invoking any listeners.
 
         Returns:
@@ -22,10 +23,17 @@ class EventFake:
         self._dispatched.append(event)
         return []
 
-    def listen[T: BaseEvent[Any]](self, event_cls: type[T], listener_cls: type) -> None:
+    @override
+    def listen[T: contracts.Event](
+        self, event_cls: type[T], listener_cls: type[contracts.EventListener[T]]
+    ) -> None:
         """No-op."""
 
-    def dispatched[E: BaseEvent[Any]](self, event_cls: type[E]) -> list[E]:
+    @override
+    async def before_dispatch(self, hook: contracts.BeforeDispatchHook) -> None:
+        """Register a hook to be called before listeners are invoked."""
+
+    def dispatched[E: contracts.Event](self, event_cls: type[E]) -> list[E]:
         """Return all recorded events of the given type.
 
         Returns:
@@ -33,7 +41,7 @@ class EventFake:
         """
         return [e for e in self._dispatched if isinstance(e, event_cls)]
 
-    def assert_dispatched[E: BaseEvent[Any]](
+    def assert_dispatched[E: contracts.Event](
         self,
         event_cls: type[E],
         *,
@@ -61,7 +69,7 @@ class EventFake:
         if match is not None and not any(match(e) for e in matching):
             raise AssertionError(f"No {event_cls.__name__} matched the predicate")
 
-    def assert_not_dispatched[E: BaseEvent[Any]](self, event_cls: type[E]) -> None:
+    def assert_not_dispatched[E: contracts.Event](self, event_cls: type[E]) -> None:
         """Assert that no event of the given type was dispatched.
 
         Args:

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

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

python_neva-3.5.0/tests/arch/test_context.py

@@ -0,0 +1,60 @@
+from pathlib import Path
+from typing import Self, override
+
+
+from neva import arch
+from neva.arch.scopes import Scope
+from neva.support import Ok, Result
+from neva.support.facade import Log
+from neva.testing import TestCase
+
+
+class RequestService:
+    """A service scoped to REQUEST."""
+
+    def __init__(self) -> None:
+        self.value: int = id(self)
+
+
+class RequestScopedProvider(arch.ServiceProvider):
+    """Registers a REQUEST-scoped service."""
+
+    @override
+    def register(self) -> Result[Self, str]:
+        self.from_context(RequestService, scope=Scope.REQUEST)
+        return Ok(self)
+
+
+def _make_config_dir(tmp_path: Path) -> Path:
+    config_dir = tmp_path / "config"
+    config_dir.mkdir()
+
+    _ = (config_dir / "app.py").write_text(
+        'config = {"name": "TestApp", "debug": True}'
+    )
+    _ = (config_dir / "providers.py").write_text(
+        """
+from tests.arch.test_context import RequestScopedProvider
+
+config = {"providers": [RequestScopedProvider]}
+"""
+    )
+
+    return config_dir
+
+
+class TestScopeEntersChildScope(TestCase):
+    @override
+    def create_config(self, tmp_path: Path) -> Path:
+        return _make_config_dir(tmp_path)
+
+    async def test_request_scoped_service_resolved_in_scope(self) -> None:
+        test_service = RequestService()
+        async with self.app.scope(
+            scope=Scope.REQUEST,
+            context={RequestService: test_service},
+        ):
+            new_service_result = self.app.make(RequestService)
+            new_service = new_service_result.unwrap()
+
+            assert new_service.value == test_service.value

{python_neva-3.3.0 → python_neva-3.5.0}/tests/arch/test_extends.py

@@ -1,4 +1,3 @@
-from dataclasses import dataclass
 import uuid
 from datetime import datetime
 from pathlib import Path

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.3.0 → python_neva-3.5.0}/uv.lock

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