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

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

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

{python_neva-2.0.0 → python_neva-2.1.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 collections.abc import Iterator
+from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, ClassVar
+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,65 @@ 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.
+
+        """
+        app = cls._get_app().ok_or(f"Cannot spy on {cls.__name__}: no application set.")
+        real = app.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 +181,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 +192,8 @@ class FacadeMeta(ABCMeta):
             Result containing the resolved service or an error message.
 
         """
+        if cls in FacadeMeta._fake_instances:
+            return Ok(FacadeMeta._fake_instances[cls])
         return app.make(interface)
 
 
@@ -174,3 +242,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.1.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.1.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.1.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.1.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.1.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.1.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.1.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()

{python_neva-2.0.0 → python_neva-2.1.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["neva"]
 
 [project]
 name = "python-neva"
-version = "2.0.0"
+version = "2.1.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12"

python_neva-2.1.0/tests/testing/test_event_fake.py

@@ -0,0 +1,111 @@
+"""Tests for EventFake."""
+
+import pytest
+
+from neva.events.event import Event as BaseEvent
+from neva.support.facade.event import Event as EventFacade
+from neva.testing import EventFake, TestCase
+
+
+class UserCreated(BaseEvent[int]):
+    user_id: int
+
+
+class OrderPlaced(BaseEvent[int]):
+    order_id: int
+
+
+class TestEventFakeDispatch:
+    async def test_dispatch_records_event(self) -> None:
+        fake = EventFake()
+        event = UserCreated(event_id=1, user_id=42)
+
+        _ = await fake.dispatch(event)
+
+        assert fake.dispatched(UserCreated) == [event]
+
+    async def test_dispatch_does_not_invoke_listeners(self) -> None:
+        fake = EventFake()
+        called = False
+
+        async def listener(_: UserCreated) -> None:
+            nonlocal called
+            called = True
+
+        _ = await fake.dispatch(UserCreated(event_id=1, user_id=1))
+        assert not called
+
+    async def test_listen_is_noop(self) -> None:
+        fake = EventFake()
+        fake.listen(UserCreated, object)  # must not raise
+
+    async def test_dispatched_filters_by_type(self) -> None:
+        fake = EventFake()
+        user_event = UserCreated(event_id=1, user_id=1)
+        order_event = OrderPlaced(event_id=2, order_id=9)
+
+        _ = await fake.dispatch(user_event)
+        _ = await fake.dispatch(order_event)
+
+        assert fake.dispatched(UserCreated) == [user_event]
+        assert fake.dispatched(OrderPlaced) == [order_event]
+
+
+class TestEventFakeAssertions:
+    async def test_assert_dispatched_passes(self) -> None:
+        fake = EventFake()
+        await fake.dispatch(UserCreated(event_id=1, user_id=42))
+        fake.assert_dispatched(UserCreated)
+
+    async def test_assert_dispatched_fails_when_not_dispatched(self) -> None:
+        fake = EventFake()
+        with pytest.raises(AssertionError, match="was not dispatched"):
+            fake.assert_dispatched(UserCreated)
+
+    async def test_assert_dispatched_times_passes(self) -> None:
+        fake = EventFake()
+        await fake.dispatch(UserCreated(event_id=1, user_id=1))
+        await fake.dispatch(UserCreated(event_id=2, user_id=2))
+        fake.assert_dispatched(UserCreated, times=2)
+
+    async def test_assert_dispatched_times_fails_on_mismatch(self) -> None:
+        fake = EventFake()
+        await fake.dispatch(UserCreated(event_id=1, user_id=1))
+        with pytest.raises(AssertionError, match="Expected 3"):
+            fake.assert_dispatched(UserCreated, times=3)
+
+    async def test_assert_dispatched_with_match_passes(self) -> None:
+        fake = EventFake()
+        await fake.dispatch(UserCreated(event_id=1, user_id=42))
+        fake.assert_dispatched(UserCreated, match=lambda e: e.user_id == 42)
+
+    async def test_assert_dispatched_with_match_fails(self) -> None:
+        fake = EventFake()
+        await fake.dispatch(UserCreated(event_id=1, user_id=1))
+        with pytest.raises(AssertionError, match="predicate"):
+            fake.assert_dispatched(UserCreated, match=lambda e: e.user_id == 99)
+
+    async def test_assert_not_dispatched_passes(self) -> None:
+        fake = EventFake()
+        fake.assert_not_dispatched(UserCreated)
+
+    async def test_assert_not_dispatched_fails_when_dispatched(self) -> None:
+        fake = EventFake()
+        await fake.dispatch(UserCreated(event_id=1, user_id=1))
+        with pytest.raises(AssertionError, match="unexpectedly"):
+            fake.assert_not_dispatched(UserCreated)
+
+
+class TestEventFacadeFake(TestCase):
+    async def test_fake_returns_event_fake(self) -> None:
+        fake = EventFacade.fake()
+        assert isinstance(fake, EventFake)
+
+    async def test_faking_context_manager_returns_event_fake(self) -> None:
+        with EventFacade.faking() as fake:
+            assert isinstance(fake, EventFake)
+
+    async def test_faking_records_dispatches(self) -> None:
+        with EventFacade.faking() as fake:
+            await EventFacade.dispatch(UserCreated(event_id=1, user_id=7))
+            fake.assert_dispatched(UserCreated, match=lambda e: e.user_id == 7)

python_neva-2.1.0/tests/testing/test_facade_restore.py

@@ -0,0 +1,57 @@
+"""Tests for facade auto-restore in TestCase."""
+
+import pytest
+
+from neva.arch.facade import FacadeMeta
+from neva.support.facade.event import Event
+from neva.testing import TestCase
+
+
+class TestFacadeAutoRestore(TestCase):
+    """Verify fakes are cleared automatically between tests.
+
+    Tests are named with a/b prefix to enforce execution order.
+    """
+
+    async def test_a_fake_is_installed(self) -> None:
+        Event.fake()
+        assert Event in FacadeMeta._fake_instances
+
+    async def test_b_fake_is_cleared_after_previous_test(self) -> None:
+        assert Event not in FacadeMeta._fake_instances
+
+
+class TestRestoreAll:
+    def test_restore_all_clears_all_fakes(self) -> None:
+        from neva.arch import Facade
+        from neva.support.facade import DB
+
+        Event.fake()
+        DB.fake()
+        assert len(FacadeMeta._fake_instances) == 2
+
+        Facade.restore_all()
+        assert len(FacadeMeta._fake_instances) == 0
+
+    def test_restore_clears_single_facade(self) -> None:
+        from neva.support.facade import DB
+
+        Event.fake()
+        DB.fake()
+        Event.restore()
+
+        assert Event not in FacadeMeta._fake_instances
+        assert DB in FacadeMeta._fake_instances
+
+        DB.restore()
+
+    def test_faking_context_manager_restores_on_exit(self) -> None:
+        with Event.faking():
+            assert Event in FacadeMeta._fake_instances
+        assert Event not in FacadeMeta._fake_instances
+
+    def test_faking_context_manager_restores_on_exception(self) -> None:
+        with pytest.raises(RuntimeError), Event.faking():
+            raise RuntimeError
+
+        assert Event not in FacadeMeta._fake_instances

python_neva-2.1.0/tests/testing/test_refresh_database.py

@@ -0,0 +1,85 @@
+"""Tests for RefreshDatabase mixin."""
+
+from collections.abc import AsyncIterator
+from typing import final
+
+import pytest
+from sqlalchemy import Column, Integer, String, select
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+
+from neva.arch import Application
+from neva.database.manager import DatabaseManager
+from neva.testing import RefreshDatabase, TestCase
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+@final
+class Item(Base):
+    __tablename__ = "items"
+    id = Column(Integer, primary_key=True)
+    name = Column(String, nullable=False)
+
+
+class DatabaseTestCase(TestCase, RefreshDatabase):
+    """TestCase with a fresh in-memory SQLite engine registered per test."""
+
+    @pytest.fixture
+    async def _setup_database_engine(
+        self, _test_case_application: Application
+    ) -> AsyncIterator[None]:
+        engine: AsyncEngine = create_async_engine("sqlite+aiosqlite:///:memory:")
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+
+        db = _test_case_application.make(DatabaseManager).unwrap()
+        db.register_engine("default", engine)
+
+        yield
+
+        await engine.dispose()
+
+
+class TestRefreshDatabaseIsolation(DatabaseTestCase):
+    """Verify data written in one test is not visible in the next.
+
+    Tests are named with a/b prefix to enforce execution order.
+    """
+
+    async def test_a_insert_item(self) -> None:
+        db = self.app.make(DatabaseManager).unwrap()
+        session = db.session().unwrap()
+        session.add(Item(id=1, name="Alice"))
+        await session.flush()
+
+        result = await session.execute(select(Item).where(Item.id == 1))
+        assert result.scalar_one().name == "Alice"
+
+    async def test_b_item_is_gone_after_rollback(self) -> None:
+        db = self.app.make(DatabaseManager).unwrap()
+        async with db.begin() as tx:
+            result = await tx.session.execute(select(Item).where(Item.id == 1))
+            assert result.scalar_one_or_none() is None
+
+
+class TestRefreshDatabaseMechanism(DatabaseTestCase):
+    async def test_nested_begin_shares_the_outer_session(self) -> None:
+        """Calls to db.begin() inside a test become savepoints."""
+        db = self.app.make(DatabaseManager).unwrap()
+        outer_session = db.session().unwrap()
+
+        async with db.begin() as inner:
+            assert inner.session is outer_session
+
+    async def test_data_visible_within_same_test(self) -> None:
+        db = self.app.make(DatabaseManager).unwrap()
+        session = db.session().unwrap()
+
+        session.add(Item(id=10, name="Visible"))
+        await session.flush()
+
+        result = await session.execute(select(Item).where(Item.id == 10))
+        assert result.scalar_one().name == "Visible"

{python_neva-2.0.0 → python_neva-2.1.0}/uv.lock

@@ -1327,7 +1327,7 @@ wheels = [
 
 [[package]]
 name = "python-neva"
-version = "2.0.0"
+version = "2.1.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },

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

@@ -1,15 +0,0 @@
-"""Event facade."""
-
-from typing import override
-
-from neva.arch import Facade
-from neva.events import EventDispatcher
-
-
-class Event(Facade):
-    """Event system facade."""
-
-    @classmethod
-    @override
-    def get_facade_accessor(cls) -> type:
-        return EventDispatcher

python_neva-2.0.0/neva/testing/__init__.py

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