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

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

@@ -46,3 +46,35 @@
 
 - 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.2.0}/PKG-INFO

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

{python_neva-3.1.1 → python_neva-3.2.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.2.0/neva/arch/markers.py

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

python_neva-3.2.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.2.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.2.0}/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)
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "python-neva"
-dynamic = ["version"]
+version = "3.2.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -39,32 +39,24 @@ dev = [
 testing = ["pytest>=9.0.2", "pytest-asyncio>=0.25.3"]
 fastapi = ["neva-fastapi>=1.0.0"]
 
-[tool.uv.sources]
-neva-fastapi = { path = "../neva-fastapi", editable = true }
-
 [build-system]
-requires = ["hatchling", "versioningit"]
+requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["neva"]
 
-[tool.hatch.version]
-source = "versioningit"
-
-[tool.hatch.version.format]
-distance = "{base_version}.dev{distance}+{vcs}{rev}"
-dirty = "{version}+dirty"
-distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.dirty"
-
 [tool.commitizen]
 name = "cz_gitmoji"
-version_provider = "scm"
-tag_format = "$version"
+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.1.1 → python_neva-3.2.0}/scripts/retag-with-changelog.sh

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

python_neva-3.2.0/tests/arch/test_cache.py

@@ -0,0 +1,52 @@
+import asyncio
+from datetime import datetime
+from pathlib import Path
+from typing import Self, override
+
+from neva.arch import ServiceProvider
+from neva.support import Ok, Result
+from neva.support.time import utcnow
+from neva.testing import TestCase
+
+
+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_cache import CacheServiceProvider
+
+config = {"providers": [CacheServiceProvider]}
+"""
+    )
+
+    return config_dir
+
+
+class CacheProvider:
+    def __init__(self) -> None:
+        self.ts: datetime = utcnow()
+
+
+class CacheServiceProvider(ServiceProvider):
+    @override
+    def register(self) -> Result[Self, str]:
+        self.bind(CacheProvider, cache=False)
+        return Ok(self)
+
+
+class TestCache(TestCase):
+    @override
+    def create_config(self, tmp_path: Path) -> Path:
+        return _make_config_dir(tmp_path)
+
+    async def test_transient_dependency(self) -> None:
+        provider1 = self.app.make(CacheProvider).unwrap()
+        await asyncio.sleep(0.1)
+        provider2 = self.app.make(CacheProvider).unwrap()
+        assert provider1 is not provider2
+        assert provider1.ts != provider2.ts

python_neva-3.2.0/tests/arch/test_extends.py

@@ -0,0 +1,98 @@
+from dataclasses import dataclass
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Protocol, Self, override
+
+from neva.arch import ServiceProvider
+from neva.support import Ok, Result
+from neva.support.time import utcnow
+from neva.testing import TestCase
+
+
+def _base_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}'
+    )
+    return config_dir
+
+
+def _make_config_dir(tmp_path: Path) -> Path:
+    config_dir = _base_config_dir(tmp_path)
+
+    _ = (config_dir / "providers.py").write_text(
+        """
+from tests.arch.test_extends import CacheServiceProvider, ExtendsServiceProvider
+
+config = {"providers": [CacheServiceProvider, ExtendsServiceProvider]}
+"""
+    )
+
+    return config_dir
+
+
+class CacheProtocol(Protocol):
+    def add(self, key: str, value: str) -> Self: ...
+    def get(self, key: str) -> str: ...
+
+
+class Cache:
+    def __init__(self) -> None:
+        self.ts: datetime = utcnow()
+        self._inner: dict[str, str] = {}
+
+    def add(self, key: str, value: str) -> Self:
+        self._inner[key] = value
+        return self
+
+    def get(self, key: str) -> str:
+        return self._inner[key]
+
+
+class TransientCache(Cache):
+    pass
+
+
+class CacheServiceProvider(ServiceProvider):
+    @override
+    def register(self) -> Result[Self, str]:
+        self.bind(Cache)
+        self.bind(TransientCache, cache=False)
+        return Ok(self)
+
+
+class ExtendsServiceProvider(ServiceProvider):
+    def override_cache(self, cache: Cache) -> Cache:
+        return cache.add("override", uuid.uuid4().hex)
+
+    def override_transient_cache(self, cache: TransientCache) -> TransientCache:
+        return cache.add("override", uuid.uuid4().hex)
+
+    @override
+    def register(self) -> Result[Self, str]:
+        _ = self.extend(self.override_cache)
+        _ = self.extend(self.override_transient_cache)
+        return Ok(self)
+
+
+class TestExtends(TestCase):
+    @override
+    def create_config(self, tmp_path: Path) -> Path:
+        return _make_config_dir(tmp_path)
+
+    async def test_extends_works(self) -> None:
+        cache = self.app.make(Cache).unwrap()
+        assert cache.get("override") is not None
+
+    async def test_extends_respects_cache(self) -> None:
+        cache = self.app.make(Cache).unwrap()
+        assert cache.get("override") is not None
+        cache2 = self.app.make(Cache).unwrap()
+        assert cache.get("override") == cache2.get("override")
+
+        cache3 = self.app.make(TransientCache).unwrap()
+        cache4 = self.app.make(TransientCache).unwrap()
+        assert cache3.get("override") != cache4.get("override")

{python_neva-3.1.1 → python_neva-3.2.0}/tests/events/conftest.py

@@ -8,6 +8,7 @@ import pytest
 from neva.arch import Application
 from neva.database.manager import DatabaseManager
 from neva.events import Event, EventDispatcher
+from neva.events.event_registry import EventRegistry
 
 
 class OrderPlaced(Event[int]):
@@ -25,4 +26,4 @@ class UserCreated(Event[int]):
 
 @pytest.fixture
 def dispatcher(application: Application, db: DatabaseManager) -> EventDispatcher:
-    return EventDispatcher(app=application, db=db)
+    return EventDispatcher(app=application, db=db, registry=EventRegistry())

{python_neva-3.1.1 → python_neva-3.2.0}/tests/events/test_dispatch.py

@@ -7,6 +7,7 @@ import dishka
 from neva.arch import Application
 from neva.database.manager import DatabaseManager
 from neva.events import EventDispatcher, EventListener
+from neva.events.event_registry import EventRegistry
 from neva.support import Err, Ok, Result
 from tests.events.conftest import OrderPlaced
 
@@ -134,7 +135,7 @@ class TestDIResolution:
 
         di_instance_id = id((await application.make_async(TrackedListener)).unwrap())
 
-        dispatcher = EventDispatcher(app=application, db=db)
+        dispatcher = EventDispatcher(app=application, db=db, registry=EventRegistry())
         dispatcher.listen(OrderPlaced, TrackedListener)
         _ = await dispatcher.dispatch(OrderPlaced(event_id=1, order_id=1))
 
@@ -153,7 +154,7 @@ class TestDIResolution:
             async def handle(self, event: OrderPlaced) -> Result[None, str]:
                 return Ok(None)
 
-        dispatcher = EventDispatcher(app=application, db=db)
+        dispatcher = EventDispatcher(app=application, db=db, registry=EventRegistry())
         dispatcher.listen(OrderPlaced, UnboundListener)
         _ = await dispatcher.dispatch(OrderPlaced(event_id=1, order_id=1))
 

python_neva-3.1.1/.envrc

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