python-neva 2.0.0__tar.gz → 2.2.0__tar.gz

{python_neva-2.0.0 → python_neva-2.2.0}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.24.2
+    rev: v8.30.1
     hooks:
       - id: gitleaks
 
@@ -16,16 +16,13 @@ repos:
       - id: debug-statements
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.13.3
+    rev: v0.15.6
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
 
-  - repo: local
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
     hooks:
-      - id: ty
-        name: ty check
-        entry: ty check . --project neva
-        files: ^neva/
-        language: system
+      - id: mypy

{python_neva-2.0.0 → python_neva-2.2.0}/PKG-INFO

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

{python_neva-2.0.0 → python_neva-2.2.0}/neva/arch/app.py

@@ -13,6 +13,7 @@ from typing import Any, Callable
 import dishka
 import fastapi
 from dishka.integrations.fastapi import setup_dishka
+from starlette.middleware import Middleware
 from starlette.routing import BaseRoute
 from starlette.types import StatefulLifespan, StatelessLifespan
 
@@ -28,7 +29,7 @@ class App(fastapi.FastAPI):
         self,
         *,
         routes: list[BaseRoute] | None = None,
-        middlewares: Sequence[type] | None = None,
+        middlewares: Sequence[Middleware] | None = None,
         lifespan: StatelessLifespan["App"] | StatefulLifespan["App"] | None = None,
         config_path: str | Path | None = None,
     ) -> None:
@@ -58,9 +59,8 @@ class App(fastapi.FastAPI):
             docs_url=config.get("app.docs_url", default="/docs").unwrap(),
             redoc_url=config.get("app.redoc_url", default="/redoc").unwrap(),
             lifespan=self._create_lifespan(),
+            middleware=middlewares,
         )
-        for middleware in middlewares or []:
-            self.add_middleware(middleware)
 
         setup_dishka(self.application.container, app=self)
 

{python_neva-2.0.0 → python_neva-2.2.0}/neva/arch/application.py

@@ -12,6 +12,7 @@ from dishka.integrations.fastapi import FastapiProvider
 from neva import Err, Ok, Result
 from neva.arch.facade import Facade
 from neva.arch.service_provider import Bootable, ServiceProvider
+from neva.config.loader import ConfigLoader
 
 
 class Application:
@@ -28,45 +29,38 @@ class Application:
             RuntimeError: If the application fails to initialize.
         """
         from neva.config.base_providers import base_providers
-        from neva.config.provider import ConfigServiceProvider
         from neva.config.repository import ConfigRepository
 
+        self.config: ConfigRepository = ConfigRepository()
         self.providers: dict[type, ServiceProvider] = {}
         self.di_provider: dishka.Provider = dishka.Provider(scope=dishka.Scope.APP)
 
-        configuration_path = config_path or os.getenv("NEVA_CONFIG_PATH", default=None)
-        config_provider = ConfigServiceProvider(
-            app=self,
-            config_path=configuration_path,
-        ).register()
-        if config_provider.is_err:
-            raise RuntimeError(
-                f"Failed to register config provider: {config_provider.unwrap_err()}"
-            )
-        self.providers[ConfigServiceProvider] = config_provider.unwrap()
-
-        self.register_providers(base_providers())
-        _ = self.di_provider.provide(source=lambda: self, provides=Application)
-
-        self.container: dishka.Container = dishka.make_container(self.di_provider)
-
-        config_result: Result[ConfigRepository, str] = self.make(
-            interface=ConfigRepository
+        configuration_path = (
+            config_path
+            if config_path is not None
+            else os.getenv("NEVA_CONFIG_PATH", default=Path.cwd())
         )
-        match config_result:
-            case Ok(config):
-                self.config: ConfigRepository = config
-                providers_from_file = config.get("providers.providers").unwrap_or([])
-                providers_from_app = config.get("app.providers").unwrap_or([])
-                providers: set[type[ServiceProvider]] = set(providers_from_file).union(
-                    set(providers_from_app)
-                )
-                _ = self.register_providers(providers)
+        match ConfigLoader(configuration_path).load_all():
             case Err(e):
-                raise RuntimeError(f"Failed to load configuration during boot: {e}")
-
+                raise RuntimeError(f"Failed to register config: {e}")
+            case Ok(configs):
+                if any(
+                    self.config.merge(namespace, config).is_err
+                    for namespace, config in configs.items()
+                ):
+                    raise RuntimeError("Failed to register config")
+
+                self.bind(lambda: self.config, interface=ConfigRepository)
+
+        providers_from_file = self.config.get("providers.providers").unwrap_or([])
+        providers_from_app = self.config.get("app.providers").unwrap_or([])
+        providers: set[type[ServiceProvider]] = set(providers_from_file).union(
+            set(providers_from_app)
+        )
+        self.register_providers(base_providers().union(providers))
+        self.bind(source=lambda: self, interface=Application)
         self._bind_event_listeners()
-        self.container = dishka.make_container(self.di_provider)
+        self.container: dishka.Container = dishka.make_container(self.di_provider)
 
     def bind_to_fastapi(self) -> None:
         """Setup the FastapiProvider for FastAPI integration."""

{python_neva-2.0.0 → python_neva-2.2.0}/neva/arch/facade.py

@@ -6,9 +6,12 @@ injection container, enabling convenient access without explicit dependency inje
 """
 
 from abc import ABC, ABCMeta, abstractmethod
-from typing import TYPE_CHECKING, Any, ClassVar
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+from unittest.mock import AsyncMock, MagicMock
 
-from neva import Option, Result, from_optional
+from neva import Ok, Option, Result, from_optional
 from neva.support.accessors import get_attr
 
 
@@ -25,6 +28,7 @@ class FacadeMeta(ABCMeta):
     """
 
     _app: ClassVar["Application | None"] = None
+    _fake_instances: ClassVar[dict[type, object]] = {}
 
     def __getattr__(cls, name: str) -> object:
         """Intercept attribute access and forward to the resolved service.
@@ -111,6 +115,69 @@ class FacadeMeta(ABCMeta):
         """
         return from_optional(cls._app)
 
+    def swap(cls, instance: object) -> None:
+        """Replace the resolved instance with a specific object for testing.
+
+        Args:
+            instance: The object to use in place of the real service.
+
+        """
+        FacadeMeta._fake_instances[cls] = instance
+
+    def fake(cls) -> AsyncMock:
+        """Replace the resolved instance with an AsyncMock for testing.
+
+        The mock is spec'd against the real service class so only valid
+        attributes are accessible. Returns the mock for setting up
+        expectations or assertions.
+
+        Returns:
+            The AsyncMock instance installed as the facade root.
+
+        """
+        mock = AsyncMock(spec=cls.get_facade_accessor())
+        cls.swap(mock)
+        return mock
+
+    def spy(cls) -> MagicMock:
+        """Wrap the real service instance in a spy for testing.
+
+        The spy records all calls while delegating to the real implementation.
+        Async methods on the real service are automatically wrapped with
+        AsyncMock semantics.
+
+        Returns:
+            The MagicMock spy installed as the facade root.
+
+        """
+        real: object = (
+            cls._get_app()
+            .ok_or(f"Cannot spy on {cls.__name__}: no application set.")
+            .and_then(lambda a: a.make(cls.get_facade_accessor()))
+            .unwrap()
+        )
+        spy_obj = MagicMock(spec=type(real), wraps=real)
+        cls.swap(spy_obj)
+        return spy_obj
+
+    def restore(cls) -> None:
+        """Restore the facade to its real service, removing any fake or spy."""
+        FacadeMeta._fake_instances.pop(cls, None)
+
+    @contextmanager
+    def faking(cls) -> Iterator[AsyncMock]:
+        """Context manager that fakes the facade and restores it on exit.
+
+        Yields:
+            The AsyncMock installed as the facade root.
+
+        """
+        mock = cls.fake()
+        try:
+            yield mock
+        finally:
+            cls.restore()
+
     def _resolve_facade_instance[T](
         cls,
         app: "Application",
@@ -118,6 +185,9 @@ class FacadeMeta(ABCMeta):
     ) -> Result[T, str]:
         """Resolve the service instance from the container.
 
+        If a fake or swap has been registered for this facade, it is returned
+        directly without touching the container.
+
         Args:
             app: The application instance.
             interface: The interface being facaded.
@@ -126,6 +196,8 @@ class FacadeMeta(ABCMeta):
             Result containing the resolved service or an error message.
 
         """
+        if cls in FacadeMeta._fake_instances:
+            return Ok(cast(T, FacadeMeta._fake_instances[cls]))
         return app.make(interface)
 
 
@@ -174,3 +246,17 @@ class Facade(ABC, metaclass=FacadeMeta):
         rarely need to be called manually.
         """
         cls._app = None
+
+    @classmethod
+    def restore_all(cls) -> None:
+        """Restore all faked or swapped facades to their real services.
+
+        Intended for test teardown. Typical usage is an autouse fixture::
+
+            @pytest.fixture(autouse=True)
+            def restore_facades():
+                yield
+                Facade.restore_all()
+
+        """
+        FacadeMeta._fake_instances.clear()

{python_neva-2.0.0 → python_neva-2.2.0}/neva/config/__init__.py

@@ -1,10 +1,8 @@
 """Configuration system."""
 
-from neva.config.provider import ConfigServiceProvider
 from neva.config.repository import ConfigRepository
 
 
 __all__ = [
     "ConfigRepository",
-    "ConfigServiceProvider",
 ]

{python_neva-2.0.0 → python_neva-2.2.0}/neva/database/connection.py

@@ -95,15 +95,26 @@ class ConnectionManager:
         )
         try:
             yield
-            tx.state = TransactionState.COMMITTED
-            if tx.is_root:
-                for result in await tx.execute_on_commit_callbacks():
-                    if result.is_err and self.logger is not None:
-                        self.logger.error(
-                            "commit callback failed",
-                            error=result.err().unwrap(),
-                            connection=self.name,
-                        )
+            if tx.rollback_requested:
+                tx.state = TransactionState.ROLLED_BACK
+                if tx.is_root:
+                    for result in await tx.execute_on_rollback_callbacks():
+                        if result.is_err and self.logger is not None:
+                            self.logger.error(
+                                "rollback callback failed",
+                                error=result.err().unwrap(),
+                                connection=self.name,
+                            )
+            else:
+                tx.state = TransactionState.COMMITTED
+                if tx.is_root:
+                    for result in await tx.execute_on_commit_callbacks():
+                        if result.is_err and self.logger is not None:
+                            self.logger.error(
+                                "commit callback failed",
+                                error=result.err().unwrap(),
+                                connection=self.name,
+                            )
         except BaseException:
             tx.state = TransactionState.ROLLED_BACK
             if tx.is_root:
@@ -160,12 +171,29 @@ class ConnectionManager:
                 tx = Transaction(self.name)
                 tx.parent = parent
                 bound = tx.begin(parent_tx.session)
-                async with self._scoped(bound), parent_tx.session.begin_nested():
-                    yield bound
+                sp = await parent_tx.session.begin_nested()
+                try:
+                    async with self._scoped(bound):
+                        yield bound
+                    if bound.rollback_requested:
+                        await sp.rollback()
+                    else:
+                        await sp.commit()
+                except BaseException:
+                    await sp.rollback()
+                    raise
             case _:
                 tx = Transaction(self.name)
                 tx.parent = Nothing()
-                async with self.session_factory() as session, session.begin():
+                async with self.session_factory() as session:
                     bound = tx.begin(session)
-                    async with self._scoped(bound):
-                        yield bound
+                    try:
+                        async with self._scoped(bound):
+                            yield bound
+                        if bound.rollback_requested:
+                            await session.rollback()
+                        else:
+                            await session.commit()
+                    except BaseException:
+                        await session.rollback()
+                        raise

{python_neva-2.0.0 → python_neva-2.2.0}/neva/database/transaction.py

@@ -27,6 +27,7 @@ class Transaction:
 
     conn_name: str
     state: TransactionState = field(default=TransactionState.ACTIVE, init=False)
+    rollback_requested: bool = field(default=False, init=False)
     _on_commit: list[TransactionCallback] = field(default_factory=list, init=False)
     _on_rollback: list[TransactionCallback] = field(default_factory=list, init=False)
     parent: Option["Transaction"] = field(default_factory=Nothing, init=False)
@@ -97,6 +98,10 @@ class Transaction:
         self._on_rollback.clear()
         return results
 
+    async def rollback(self) -> None:
+        """Mark this transaction for rollback on exit."""
+        self.rollback_requested = True
+
     def begin(self, session: "AsyncSession") -> "BoundTransaction":
         """Bind this transaction to a session, returning a BoundTransaction.
 

{python_neva-2.0.0 → python_neva-2.2.0}/neva/security/encryption/encrypter.py

@@ -51,7 +51,9 @@ class AesEncrypter:
         Returns:
             Ok with base64-encoded encrypted payload, or Err with message.
         """
-        wrapper = {"__str__": value} if isinstance(value, str) else {"__json__": value}
+        wrapper: dict[str, JsonValue] = (
+            {"__str__": value} if isinstance(value, str) else {"__json__": value}
+        )
 
         try:
             payload = json.dumps(wrapper)

{python_neva-2.0.0 → python_neva-2.2.0}/neva/support/facade/__init__.py

@@ -4,6 +4,7 @@ from neva.support.facade.app import App
 from neva.support.facade.config import Config
 from neva.support.facade.crypt import Crypt
 from neva.support.facade.db import DB
+from neva.support.facade.event import Event
 from neva.support.facade.hash import Hash
 from neva.support.facade.log import Log
 
@@ -13,6 +14,7 @@ __all__ = [
     "App",
     "Config",
     "Crypt",
+    "Event",
     "Hash",
     "Log",
 ]

python_neva-2.2.0/neva/support/facade/event.py

@@ -0,0 +1,53 @@
+"""Event facade."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, override
+
+from neva.arch import Facade
+from neva.events import EventDispatcher
+
+
+if TYPE_CHECKING:
+    from neva.testing.fakes import EventFake
+
+
+class Event(Facade):
+    """Event system facade."""
+
+    @classmethod
+    @override
+    def get_facade_accessor(cls) -> type:
+        """Return the service class backed by this facade.
+
+        Returns:
+            EventDispatcher class.
+        """
+        return EventDispatcher
+
+    @classmethod
+    def fake(cls) -> "EventFake":
+        """Replace the dispatcher with an EventFake and return it.
+
+        Returns:
+            The installed EventFake instance.
+        """
+        from neva.testing.fakes import EventFake
+
+        instance = EventFake()
+        cls.swap(instance)
+        return instance
+
+    @classmethod
+    @contextmanager
+    def faking(cls) -> "Iterator[EventFake]":
+        """Context manager that installs an EventFake and restores on exit.
+
+        Yields:
+            The installed EventFake instance.
+        """
+        instance = cls.fake()
+        try:
+            yield instance
+        finally:
+            cls.restore()

{python_neva-2.0.0 → python_neva-2.2.0}/neva/support/results.py

@@ -246,7 +246,7 @@ class OptionProtocol[T](ABC):
 
 
 @dataclass(eq=True, frozen=True)
-class Some(OptionProtocol[T]):
+class Some[T](OptionProtocol[T]):
     """An Option containing a value.
 
     Represents the presence of a value in an Option type. All transformation
@@ -330,7 +330,7 @@ class Some(OptionProtocol[T]):
 
 
 @dataclass(eq=True, frozen=True)
-class Nothing(OptionProtocol[T]):
+class Nothing[T](OptionProtocol[T]):
     """An Option containing no value.
 
     Represents the absence of a value in an Option type. All transformation
@@ -594,7 +594,7 @@ class ResultProtocol[T, E](ABC):
 
 
 @dataclass(eq=True, frozen=True)
-class Ok(ResultProtocol[T, E]):
+class Ok[T, E](ResultProtocol[T, E]):
     """A Result containing a success value.
 
     Represents a successful operation in a Result type. All transformation
@@ -671,7 +671,7 @@ class Ok(ResultProtocol[T, E]):
 
 
 @dataclass(eq=True, frozen=True)
-class Err(ResultProtocol[T, E]):
+class Err[T, E](ResultProtocol[T, E]):
     """A Result containing an error value.
 
     Represents a failed operation in a Result type. All transformation methods

python_neva-2.2.0/neva/testing/__init__.py

@@ -0,0 +1,7 @@
+"""Testing utilities for Neva applications."""
+
+from neva.testing.fakes import EventFake
+from neva.testing.test_case import RefreshDatabase, TestCase
+
+
+__all__ = ["EventFake", "RefreshDatabase", "TestCase"]

python_neva-2.2.0/neva/testing/fakes.py

@@ -0,0 +1,78 @@
+"""Testing fakes for Neva facades."""
+
+from collections.abc import Callable
+from typing import Any
+
+from neva import Result
+from neva.events.event import Event as BaseEvent
+
+
+class EventFake:
+    """Recording fake for the Event facade. No listeners are dispatched."""
+
+    def __init__(self) -> None:
+        self._dispatched: list[BaseEvent[Any]] = []
+
+    async def dispatch(self, event: BaseEvent[Any]) -> list[Result[None, str]]:
+        """Record the event without invoking any listeners.
+
+        Returns:
+            An empty list — no listeners are fired.
+        """
+        self._dispatched.append(event)
+        return []
+
+    def listen[T: BaseEvent[Any]](self, event_cls: type[T], listener_cls: type) -> None:
+        """No-op."""
+
+    def dispatched[E: BaseEvent[Any]](self, event_cls: type[E]) -> list[E]:
+        """Return all recorded events of the given type.
+
+        Returns:
+            All dispatched events that are instances of event_cls.
+        """
+        return [e for e in self._dispatched if isinstance(e, event_cls)]
+
+    def assert_dispatched[E: BaseEvent[Any]](
+        self,
+        event_cls: type[E],
+        *,
+        times: int | None = None,
+        match: Callable[[E], bool] | None = None,
+    ) -> None:
+        """Assert that at least one event of the given type was dispatched.
+
+        Args:
+            event_cls: The event type to check.
+            times: If given, assert exactly this many were dispatched.
+            match: If given, assert at least one event satisfies the predicate.
+
+        Raises:
+            AssertionError: If the assertion fails.
+        """
+        matching = self.dispatched(event_cls)
+        if not matching:
+            raise AssertionError(f"{event_cls.__name__} was not dispatched")
+        if times is not None and len(matching) != times:
+            raise AssertionError(
+                f"Expected {times} dispatch(es) of {event_cls.__name__},"
+                + f" got {len(matching)}"
+            )
+        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:
+        """Assert that no event of the given type was dispatched.
+
+        Args:
+            event_cls: The event type to check.
+
+        Raises:
+            AssertionError: If the assertion fails.
+        """
+        matching = self.dispatched(event_cls)
+        if matching:
+            raise AssertionError(
+                f"{event_cls.__name__} was dispatched"
+                + f" {len(matching)} time(s) unexpectedly"
+            )

{python_neva-2.0.0 → python_neva-2.2.0}/neva/testing/fixtures.py

@@ -1,9 +1,8 @@
 """Fixtures for testing."""
 
 from collections.abc import AsyncIterator, Callable
-from contextlib import asynccontextmanager
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
 from pathlib import Path
-from typing import AsyncContextManager
 
 import pytest
 
@@ -45,7 +44,7 @@ def webapp(test_config: Path) -> App:
 
 
 @pytest.fixture
-def app_factory() -> Callable[[Path], AsyncContextManager[Application]]:
+def app_factory() -> Callable[[Path], AbstractAsyncContextManager[Application]]:
     """Factory fixture for creating applications with custom configs.
 
     Returns:

{python_neva-2.0.0 → python_neva-2.2.0}/neva/testing/test_case.py

@@ -1,15 +1,12 @@
 """Base test case class."""
 
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Iterator
 from pathlib import Path
-from typing import TypeVar
 
 import pytest
 
-from neva.arch import Application
-
-
-T = TypeVar("T")
+from neva.arch import Application, Facade
+from neva.database.manager import DatabaseManager
 
 
 class TestCase:
@@ -64,6 +61,41 @@ class TestCase:
             yield app
 
     @pytest.fixture(autouse=True)
-    async def _inject_app(self, _test_case_application: Application) -> None:
+    def _inject_app(self, _test_case_application: Application) -> None:
         """Auto-inject app fixture into self.app."""
         self.app = _test_case_application
+
+    @pytest.fixture(autouse=True)
+    def _restore_facades(self) -> Iterator[None]:
+        """Restore all faked facades after each test."""
+        yield
+        Facade.restore_all()
+
+
+class RefreshDatabase:
+    """Mixin for TestCase that wraps each test in a transaction and rolls it back.
+
+    Must be used alongside TestCase. If engines are registered outside of app
+    lifespan, override ``_setup_database_engine`` to ensure the engine is ready
+    before the rollback transaction opens.
+    """
+
+    @pytest.fixture
+    async def _setup_database_engine(self) -> AsyncIterator[None]:
+        """Hook for registering DB engines before the rollback transaction opens.
+
+        Override in subclasses when engines are not registered during app lifespan.
+        """
+        yield
+
+    @pytest.fixture(autouse=True)
+    async def _rollback_database(
+        self,
+        _test_case_application: Application,
+        _setup_database_engine: None,  # ordering dependency: runs after engine setup
+    ) -> AsyncIterator[None]:
+        """Wrap the test in a DB transaction and roll it back on completion."""
+        db = _test_case_application.make(DatabaseManager).unwrap()
+        async with db.begin() as tx:
+            yield
+            await tx.rollback()