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

python_neva-3.3.0/CHANGELOG.md

@@ -0,0 +1,115 @@
+## 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
+
+- bump opt dep on neva-fastapi
+
+## 3.1.0 (2026-05-11)
+
+### ✨ Features
+
+- fixing db facade
+- Add eq method to Some / Ok
+- Deprecate register_engine, add register_connection
+- RefreshDatabase now properly use the testcase inner app
+- Add neva-fastapi as optional dependency
+- renaming of make / make_async for retrocompatibility
+
+### 🐛🚑️ Fixes
+
+- Fix provider registration ordering
+
+### ♻️ Refactorings
+
+- refactor of results / db toolkit
+
+## 3.1.0a1 (2026-05-05)
+
+### build
+
+- add commitizen + versioningit
+
+### 💚👷 CI & Build
+
+- update perms on tag script
+- tweaking cz tags
+- remove auto-annotated tags
+- configure versioningit + cz
+- Fix cz config >>> ⏰ 1
+- add and configure cz_gitmoji >>> ⏰ 5m
+
+### 📝💡 Documentation
+
+- clear changelog
+
+### 🔧🔨📦️ Configuration, Scripts, Packages
+
+- improve auto-annotation of tags
+- Fix tagging script
+
+## python-neva-v3.2.0 (2026-06-04)
+
+### ✨ Features
+
+- **core**: add optional activator on all binding functions
+- **core**: remove scoping option from scoped, default to request scope
+- **core**: introduce conditional activation
+- **core**: add specifying interface in extends method
+- **core**: add extends feature
+
+### build
+
+- **core**: remove redundant .envrc files
+- **core**: fixing version derivation
+
+### docs
+
+- **core,-fastapi**: add contributing documentation
+
+### feat
+
+- **core**: allow passing context data to scope method
+- **core**: add some utility functions for binding
+- **core**: add some utility functions for binding
+- **core**: add the possibility to turn off dependency caching
+- **core,-fastapi**: add .envrc file
+
+### refactor
+
+- **core**: cleaning up type hints
+- **core**: update type hints on main application

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-neva
-Version: 3.1.1
+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.1.1 → python_neva-3.3.0}/neva/arch/application.py

@@ -2,7 +2,7 @@
 
 import os
 from collections import OrderedDict
-from collections.abc import AsyncIterator, Sequence
+from collections.abc import AsyncGenerator, Sequence
 from contextlib import AsyncExitStack, asynccontextmanager
 from contextvars import ContextVar
 from pathlib import Path
@@ -13,6 +13,7 @@ from dishka.provider import BaseProvider
 from typing_extensions import deprecated
 
 from neva.arch.facade import Facade
+from neva.arch.scopes import BaseScope, Scope
 from neva.arch.service_provider import Bootable, ServiceProvider
 from neva.config.loader import ConfigLoader
 from neva.support import Err, Ok, Result
@@ -41,7 +42,7 @@ class Application:
 
         self.config: ConfigRepository = ConfigRepository()
         self.providers: OrderedDict[type, ServiceProvider] = OrderedDict()
-        self.root_provider: dishka.Provider = dishka.Provider(scope=dishka.Scope.APP)
+        self.root_provider: dishka.Provider = dishka.Provider(scope=Scope.APP)
 
         configuration_path = (
             config_path
@@ -112,7 +113,7 @@ class Application:
         source: type | Callable[..., Any],
         *,
         interface: type | None = None,
-        scope: dishka.BaseScope | None = None,
+        scope: BaseScope | None = None,
     ) -> None:
         """Binds a source to the container."""
         _ = self.root_provider.provide(
@@ -146,14 +147,18 @@ class Application:
             return Err(f"Failed to resolve service '{interface.__name__}': {e}")
 
     @asynccontextmanager
-    async def scope(self, scope: dishka.BaseScope | None = None) -> AsyncIterator[Self]:
+    async def scope(
+        self,
+        scope: BaseScope | None = None,
+        context: dict[type, Any] | None = None,
+    ) -> AsyncGenerator[Self]:
         """Enter a new scope.
 
         Yields:
             The application instance with the new scope.
         """
         parent = _current_container.get(self.container)
-        async with parent(scope=scope) as container:
+        async with parent(scope=scope, context=context) as container:
             token = _current_container.set(container)
             try:
                 yield self
@@ -161,7 +166,7 @@ class Application:
                 _current_container.reset(token)
 
     @asynccontextmanager
-    async def lifespan(self) -> AsyncIterator[None]:
+    async def lifespan(self) -> AsyncGenerator[None]:
         """Wire the facades and providers."""
         Facade.set_facade_application(self)
 

python_neva-3.3.0/neva/arch/markers.py

@@ -0,0 +1,4 @@
+from dishka.entities.marker import BaseMarker, Has, Marker
+
+
+__all__ = ["BaseMarker", "Has", "Marker"]

python_neva-3.3.0/neva/arch/scopes.py

@@ -0,0 +1,5 @@
+from dishka.entities.scope import BaseScope, Scope
+
+
+__all__ = ["BaseScope", "Scope"]
+

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

@@ -21,6 +21,8 @@ from typing import (
 
 import dishka
 
+from neva.arch.markers import BaseMarker, Marker
+from neva.arch.scopes import BaseScope, Scope
 from neva.support import Result
 
 
@@ -69,6 +71,7 @@ class ServiceProvider(abc.ABC):
 
     app: "Application"
     listen: ClassVar[dict[type[Event], list[type[EventListener[Any]]]]] = {}
+    when: ClassVar[Marker | None] = None
 
     def __init__(self, app: "Application") -> None:
         """Initialize the service provider.
@@ -77,23 +80,101 @@ class ServiceProvider(abc.ABC):
             app: The application instance.
 
         """
-        self.provider: dishka.Provider = dishka.Provider(scope=dishka.Scope.APP)
+        self.provider: dishka.Provider = dishka.Provider(
+            scope=dishka.Scope.APP,
+            when=self.when,
+        )
         self.app = app
 
+    def activator(
+        self,
+        activation_fn: Callable[..., bool],
+        *markers: Marker | type[Marker],
+    ) -> None:
+        """Registers an activator function for the given markers.
+
+        Args:
+            activation_fn: The activator function.
+            markers: Markers triggered by this function.
+        """
+        _ = self.provider.activate(activation_fn, *markers)
+
     def bind(
         self,
         source: type | Callable[..., Any],
         *,
         interface: type | None = None,
-        scope: dishka.BaseScope | None = None,
+        scope: BaseScope | None = None,
+        when: BaseMarker | None = None,
+        cache: bool = True,
     ) -> None:
         """Binds a source to the container."""
         _ = self.provider.provide(
             source=source,
             scope=scope,
             provides=interface,
+            cache=cache,
+            when=when,
         )
 
+    def scoped(
+        self,
+        source: type | Callable[..., Any],
+        *,
+        interface: type | None = None,
+        when: BaseMarker | None = None,
+    ) -> Self:
+        """Binds the source to the container.
+
+        Scope is REQUEST by default but a custom scope be provided.
+        Dependency declared with this are cached no matter what.
+
+        Returns:
+            the provider itself for chaining purposes
+        """
+        self.bind(source, interface=interface, scope=Scope.REQUEST, when=when)
+        return self
+
+    def transient(
+        self,
+        source: type | Callable[..., Any],
+        *,
+        interface: type | None = None,
+        when: BaseMarker | None = None,
+    ) -> Self:
+        """Binds the source to the container as a transient dependency.
+
+        Dependencies declared this way have global scope and are never
+        cached.
+
+        Returns:
+            the provider itself for chaining purposes
+        """
+        self.bind(source, interface=interface, when=when, cache=False)
+        return self
+
+    def extend(
+        self,
+        source: Callable[..., Any],
+        *,
+        interface: type | None = None,
+        scope: dishka.BaseScope | None = None,
+        when: BaseMarker | None = None,
+    ) -> Self:
+        """Extends a dependency declared by another provider.
+
+        This allows to 'extend' a dependency, maybe even override it entirely.
+        Particularly useful if you want to run some code on a dependency declared
+        by another provider / package.
+
+        You may also provide a scope for this.
+
+        Returns:
+            the provider itself for chaining purposes
+        """
+        _ = self.provider.decorate(source, provides=interface, scope=scope, when=when)
+        return self
+
     @abc.abstractmethod
     def register(self) -> Result[Self, str]:
         """Register services into the application container.

{python_neva-3.1.1 → 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.3.0/neva/events/dispatcher.py

@@ -0,0 +1,135 @@
+"""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 import contracts
+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."""
+
+    def __init__(
+        self,
+        app: Application,
+        db: DatabaseManager,
+        registry: EventRegistry,
+    ) -> None:
+        self._registry: EventRegistry = registry
+        self._app: Application = app
+        self._db: DatabaseManager = db
+        self._before_dispatch_hooks: list[BeforeDispatchHook] = []
+
+    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
+        persisting the event to an event store. The default implementation
+        is a no-op.
+
+        Args:
+            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)
+
+    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,
+        falling back to direct instantiation otherwise.
+
+        Args:
+            event: The event to dispatch.
+
+        Returns:
+            A list of results, one per listener invocation.
+        """
+        await self._apply_before_dispatch(event)
+        results: list[Result[None, str]] = []
+        listeners = self._registry.resolve_listeners(event)
+
+        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 deferred:
+                    _ = tx.on_commit(self._build_callback(event, listener_cls))
+            case Nothing():
+                immediate.extend(deferred)
+
+        for listener_cls in immediate:
+            listener = self._resolve_listener(listener_cls)
+            try:
+                results.append(await listener.handle(event))
+            except Exception as e:
+                results.append(Err(f"Listener raised: {e}"))
+
+        return results
+
+    @override
+    def listen[T: contracts.Event](
+        self,
+        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: 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,
+        falling back to direct instantiation otherwise.
+
+        Returns:
+            EventListener[Any]: The resolved listener.
+        """
+        result = self._app.make(listener_cls)
+        if result.is_ok:
+            return result.unwrap()
+        return listener_cls()
+
+    def _build_callback[T: contracts.Event](
+        self,
+        event: T,
+        listener_cls: type[contracts.EventListener[T]],
+    ) -> TransactionCallback:
+        async def callback() -> Result[None, str]:
+            listener = self._resolve_listener(listener_cls)
+            return await listener.handle(event)
+
+        return callback

{python_neva-3.1.1 → 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]())