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

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)
 

neva/arch/markers.py

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

neva/arch/scopes.py

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

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.

neva/events/dispatcher.py

@@ -1,7 +1,5 @@
 """Base implementation of the event dispatcher."""
 
-from typing import final
-
 from neva.arch.application import Application
 from neva.database.manager import DatabaseManager
 from neva.database.transaction import TransactionCallback
@@ -11,15 +9,30 @@ from neva.events.listener import EventListener
 from neva.support import Err, Nothing, Result, Some
 
 
-@final
 class EventDispatcher:
     """Event dispatcher implementation."""
 
-    def __init__(self, app: Application, db: DatabaseManager) -> None:
-        self._registry = EventRegistry()
+    def __init__(
+        self,
+        app: Application,
+        db: DatabaseManager,
+        registry: EventRegistry,
+    ) -> None:
+        self._registry = registry
         self._app = app
         self._db = db
 
+    async def _before_dispatch(self, event: 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.
+        """
+
     async def dispatch(self, event: Event) -> list[Result[None, str]]:
         """Dispatch an event to all registered listeners.
 
@@ -32,6 +45,7 @@ class EventDispatcher:
         Returns:
             A list of results, one per listener invocation.
         """
+        await self._before_dispatch(event)
         results: list[Result[None, str]] = []
         listeners = self._registry.get_listeners(event)
 

neva/events/provider.py

@@ -3,6 +3,7 @@
 from typing import Self, override
 
 from neva.arch.service_provider import ServiceProvider
+from neva.events.event_registry import EventRegistry
 from neva.support import Ok, Result
 
 
@@ -23,5 +24,6 @@ class EventServiceProvider(ServiceProvider):
         """
         from neva.events.dispatcher import EventDispatcher
 
+        self.bind(EventRegistry)
         self.bind(EventDispatcher)
         return Ok(self)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-neva
-Version: 3.1.0
+Version: 3.2.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0
@@ -16,7 +16,7 @@ Requires-Dist: sqlalchemy[asyncio]>=2.0.0
 Requires-Dist: structlog>=25.5.0
 Requires-Dist: typer>=0.21.1
 Provides-Extra: fastapi
-Requires-Dist: neva-fastapi>=0.1.0; extra == 'fastapi'
+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'

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

@@ -1,9 +1,11 @@
 neva/arch/__init__.py,sha256=1ukTl5Ynz5PrGa5e-tFSMaNgVkfhQRrYQGPUqUeXMMg,429
-neva/arch/application.py,sha256=9qvg_MeSjhgQZnX6RSuWaJQfmC5GqEd2XtHR6FGGfpc,7142
+neva/arch/application.py,sha256=DH1CXVEsiOCDQIigOXfXI2jYGVZr-TwMgilTQu6qPq0,7258
 neva/arch/config.py,sha256=R8_wMKTwX8vTFqfQhgglDQ9PfB6Yo6mx6OnKg8bnIWw,1042
 neva/arch/facade.py,sha256=1kYVhyYto8zSyOZV6sAYJ3xWzQDJRzoVV-e_EarTp0Q,7927
+neva/arch/markers.py,sha256=STdhmW88qV8uogIa9kSD9gs-uMRaglZI8HOw3PrhX1Q,103
 neva/arch/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-neva/arch/service_provider.py,sha256=iXOicvbkZ-c455NElEeWD9tzZyLVIXkje-C3PQWiE6k,3165
+neva/arch/scopes.py,sha256=Gu0kJk39Yv8LCCzxjdu0lIE0FXtnsG36LGKDuNin2CE,87
+neva/arch/service_provider.py,sha256=zEFwix2cL6l1Frv9w1OMtnL_zjkl_BVpGBhRaNK6bb0,5636
 neva/arch/integrations/__init__.py,sha256=cXuqC4JfZdGYLlh6POgYUVXUT2NQ84276eC-RYTyFxk,75
 neva/arch/integrations/faststream.py,sha256=AOwfpfdL3O5HLAx80SwUGQb_hKEeAkFOUyIXtjODaHM,1696
 neva/config/__init__.py,sha256=Ygfnh-MRRKYDdf54_LeMSHwmck5VpNHTdnnMtGEFLtU,121
@@ -19,11 +21,11 @@ neva/database/provider.py,sha256=l2be4Ri53RtQq1-qzohy3cqzJQpTaNzqXGVhXPKUCXc,167
 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=i7PYbesKnX6PkbRZomBfUOG2oNQ__eXPrKnglzwJFo0,2858
+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=L-yYJMM1KelWItUKCrESrmrF6On8SFg-OxpXF1--SVE,771
+neva/events/provider.py,sha256=HE7k915m8lQiqBC6kaGtb3ZfoxrgsuXXZmxkaaSnlmM,857
 neva/events/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neva/obs/__init__.py,sha256=dVzgljk9Hvo44LI34RcwbDyT42_z4nSnFVmL4GLbKD0,331
 neva/obs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -83,6 +85,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.1.0.dist-info/METADATA,sha256=d-vn_HcJkLsHsKTjd9t0h64E32BnM5IUCE7wCab6BEU,771
-python_neva-3.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_neva-3.1.0.dist-info/RECORD,,
+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.1.0.dist-info → python_neva-3.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.29.0
+Generator: hatchling 1.30.1
 Root-Is-Purelib: true
 Tag: py3-none-any