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

python_neva-3.3.0/.envrc

@@ -0,0 +1,2 @@
+export VIRTUAL_ENV="$PWD/.venv"
+layout python

{python_neva-3.2.0 → python_neva-3.3.0}/CHANGELOG.md

@@ -1,3 +1,38 @@
+## 3.3.0 (2026-06-05)
+
+### ✨ Features
+
+- **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
+
+## 3.2.0 (2026-06-05)
+
+### ✨ Features
+
+- **tooling**: placeholder commit
+
+### 🔧🔨📦️ Configuration, Scripts, Packages
+
+- **tooling**: update changelog script
+- **project**: update versioning config
+
+### 📝💡 Documentation
+
+- **core**: placeholde readme
+
 ## 3.1.1 (2026-05-11)
 
 ### 📌➕⬇️➖⬆️ Dependencies

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

@@ -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.3.0/README.md

@@ -0,0 +1,3 @@
+# The Neva framework
+
+PLACEHOLDER

{python_neva-3.2.0 → python_neva-3.3.0}/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
 
 

python_neva-3.3.0/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"]

python_neva-3.3.0/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."""
+        ...

python_neva-3.3.0/neva/events/contracts/event.py

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

python_neva-3.3.0/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."""
+        ...

python_neva-3.3.0/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.
+        """
+        ...

{python_neva-3.2.0 → python_neva-3.3.0}/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)

{python_neva-3.2.0 → python_neva-3.3.0}/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

python_neva-3.3.0/neva/events/event_registry.py

@@ -0,0 +1,59 @@
+"""Event/listener registry."""
+
+import inspect
+from typing import Any, TypeVar
+
+from neva.events import contracts, policy
+
+
+class EventListenerRegistry[T: contracts.Event]:
+    """Event listener registry for a given event."""
+
+    def __init__(self) -> None:
+        self.immediate: list[type[contracts.EventListener[T]]] = []
+        self.deferred: list[type[contracts.EventListener[T]]] = []
+
+    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 policy.HandlingPolicy.IMMEDIATE:
+                self.immediate.append(listener_cls)
+            case policy.HandlingPolicy.DEFERRED:
+                self.deferred.append(listener_cls)
+
+
+T = TypeVar("T", bound=contracts.Event, covariant=True)
+
+
+class EventRegistry:
+    """Event/listener registry."""
+
+    __listeners: dict[type[Any], EventListenerRegistry[Any]]
+
+    def __init__(self) -> None:
+        """Initialize the registry."""
+        self.__listeners = {}
+
+    def register(
+        self,
+        event_cls: list[type[T]],
+        listener_cls: type[contracts.EventListener[T]],
+    ) -> None:
+        """Register a listener for an event."""
+        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]())

{python_neva-3.2.0 → python_neva-3.3.0}/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)

python_neva-3.3.0/neva/events/policy.py

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

{python_neva-3.2.0 → python_neva-3.3.0}/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 → python_neva-3.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-neva"
-version = "3.2.0"
+version = "3.3.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -49,14 +49,10 @@ packages = ["neva"]
 [tool.commitizen]
 name = "cz_gitmoji"
 version_provider = "uv"
-tag_format = "python-neva-v$version"
 version_scheme = "pep440"
 update_changelog_on_bump = true
 annotated_tag = true
 post_bump_hooks = ["scripts/retag-with-changelog.sh"]
-# Only commits scoped to `core` (alone or in a comma-separated scope list) feed
-# this package's changelog. See CONTRIBUTING.md.
-changelog_pattern = '''^(?::[\w_]+:\s+)?\w+\([^)]*\bcore\b[^)]*\)!?:\s'''
 
 [tool.basedpyright]
 enableExperimentalFeatures = true

{python_neva-3.2.0 → python_neva-3.3.0}/scripts/retag-with-changelog.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env sh
 set -e
 
-TAG="python-neva-v${CZ_POST_CURRENT_VERSION}"
+TAG="${CZ_POST_CURRENT_VERSION}"
 
 # Generate the changelog section for this version only
 CHANGELOG=$(cz changelog "${CZ_POST_CURRENT_VERSION}" --dry-run |

python_neva-3.3.0/tests/events/test_binding.py

@@ -0,0 +1,11 @@
+from neva.events import contracts
+from neva.events.dispatcher import EventDispatcher
+from neva.testing.test_case import TestCase
+
+
+class TestEventBinding(TestCase):
+    async def test_binding(self) -> None:
+        dispatcher_from_interface = self.app.make(contracts.EventDispatcher)
+        assert dispatcher_from_interface.is_ok
+        dispatcher_from_implementation = self.app.make(EventDispatcher)
+        assert dispatcher_from_implementation.is_ok

python_neva-3.3.0/tests/events/test_listen_on_parent_class.py

@@ -0,0 +1,77 @@
+from random import randint
+from typing import override
+
+import pydantic
+
+from neva.events import Event, EventDispatcher, EventListener, contracts
+from neva.support import Ok, Result
+
+
+class OrderEvent(Event[int]):
+    id: int = pydantic.Field(default=randint(0, 200))  # noqa: S311
+    order_id: int
+
+
+class RecordableEvent(contracts.Event):
+    pass
+
+
+class OrderDeleted(OrderEvent, RecordableEvent):
+    pass
+
+
+class OrderDeleting(OrderEvent):
+    pass
+
+
+class TestListenOnParentEvent:
+    async def test_dispatching_event_invokes_listener_on_parent(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        called = False
+
+        class OrderEventListener(EventListener[OrderEvent]):
+            @override
+            async def handle(self, event: OrderEvent) -> Result[None, str]:
+                nonlocal called
+                called = True
+                return Ok(None)
+
+        dispatcher.listen(OrderEvent, OrderEventListener)
+        _ = await dispatcher.dispatch(OrderDeleted(event_id=1, order_id=1))
+
+        assert called
+
+    async def test_dispatching_event_invokes_listener_on_all_parents(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        called = False
+
+        class RecordableEventListener(EventListener[RecordableEvent]):
+            @override
+            async def handle(self, event: RecordableEvent) -> Result[None, str]:
+                nonlocal called
+                called = True
+                return Ok(None)
+
+        dispatcher.listen(RecordableEvent, RecordableEventListener)
+        _ = await dispatcher.dispatch(OrderDeleted(event_id=1, order_id=1))
+
+        assert called
+
+    async def test_listening_on_multiple_event_types(
+        self, dispatcher: EventDispatcher
+    ) -> None:
+        called = False
+
+        class OrderEventListener(EventListener[OrderEvent]):
+            @override
+            async def handle(self, event: OrderEvent) -> Result[None, str]:
+                nonlocal called
+                called = True
+                return Ok(None)
+
+        dispatcher.listen([OrderDeleted, OrderDeleting], OrderEventListener)
+        _ = await dispatcher.dispatch(OrderDeleted(event_id=1, order_id=1))
+
+        assert called

{python_neva-3.2.0 → python_neva-3.3.0}/tests/obs/test_correlation.py

@@ -2,6 +2,7 @@
 
 import uuid
 
+import pytest
 from starlette.applications import Starlette
 from starlette.requests import Request
 from starlette.responses import JSONResponse
@@ -12,6 +13,9 @@ from starlette.types import Receive, Scope, Send
 from neva.obs.middleware.correlation import CorrelationMiddleware, is_valid_uuid
 
 
+pytestmark = pytest.mark.skip
+
+
 def _make_app(
     middleware: CorrelationMiddleware | None = None,
 ) -> TestClient:

{python_neva-3.2.0 → python_neva-3.3.0}/tests/obs/test_profiler.py

@@ -2,6 +2,7 @@
 
 from pathlib import Path
 
+import pytest
 from starlette.applications import Starlette
 from starlette.requests import Request
 from starlette.responses import PlainTextResponse
@@ -12,6 +13,9 @@ from starlette.types import Receive, Scope, Send
 from neva.obs.middleware.profiler import ProfilerMiddleware
 
 
+pytestmark = pytest.mark.skip
+
+
 def _make_app(tmp_path: Path, **kwargs: object) -> TestClient:
     async def index(request: Request) -> PlainTextResponse:
         return PlainTextResponse("ok")