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

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

@@ -1,17 +1,18 @@
 Metadata-Version: 2.4
 Name: python-neva
-Version: 1.0.5
+Version: 2.1.0
 Summary: Add your description here
 Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: asyncpg>=0.30.0
 Requires-Dist: cryptography>=46.0.3
 Requires-Dist: dishka>=1.7.2
 Requires-Dist: fastapi[all]>=0.129.0
 Requires-Dist: faststream>=0.6.6
-Requires-Dist: flexmock>=0.13.0
 Requires-Dist: pwdlib[argon2,bcrypt]>=0.3.0
 Requires-Dist: pyinstrument>=5.1.1
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0
 Requires-Dist: structlog>=25.5.0
-Requires-Dist: tortoise-orm[accel]>=1.1.4
 Requires-Dist: typer>=0.21.1
 Provides-Extra: testing
 Requires-Dist: pytest-asyncio>=0.25.3; extra == 'testing'

{python_neva-1.0.5 → 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-1.0.5 → python_neva-2.1.0}/neva/database/__init__.py

@@ -1,13 +1,15 @@
 """Database module."""
 
-from neva.database.config import DatabaseConfig
+from neva.database.config import ConnectionConfig, DatabaseConfig
 from neva.database.connection import TransactionContext
 from neva.database.manager import DatabaseManager
 from neva.database.provider import DatabaseServiceProvider
-from neva.database.transaction import Transaction
+from neva.database.transaction import BoundTransaction, Transaction
 
 
 __all__ = [
+    "BoundTransaction",
+    "ConnectionConfig",
     "DatabaseConfig",
     "DatabaseManager",
     "DatabaseServiceProvider",

python_neva-2.1.0/neva/database/config.py

@@ -0,0 +1,20 @@
+"""Database configs."""
+
+from typing import NotRequired, TypedDict
+
+
+class ConnectionConfig(TypedDict):
+    """Configuration for a single database connection."""
+
+    url: str
+    pool_size: NotRequired[int]
+    max_overflow: NotRequired[int]
+    pool_recycle: NotRequired[int]
+    pool_pre_ping: NotRequired[bool]
+    echo: NotRequired[bool]
+
+
+class DatabaseConfig(TypedDict):
+    """Database config."""
+
+    connections: dict[str, ConnectionConfig]

python_neva-2.1.0/neva/database/connection.py

@@ -0,0 +1,199 @@
+"""Connection manager."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import final
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from neva import Nothing, Option, Some, from_optional
+from neva.database.transaction import BoundTransaction, Transaction, TransactionState
+from neva.obs import LogManager
+
+
+@dataclass
+class TransactionRegistry:
+    """A registry of ongoing transactions."""
+
+    by_connection: dict[str, Transaction] = field(default_factory=dict)
+    stack: list[Transaction] = field(default_factory=list)
+
+    def extend(self, transaction: Transaction) -> "TransactionRegistry":
+        """Adds a new transaction to the registry.
+
+        Returns:
+            A new registry with the new transaction added.
+        """
+        return TransactionRegistry(
+            by_connection={**self.by_connection, transaction.conn_name: transaction},
+            stack=[*self.stack, transaction],
+        )
+
+
+_tx_registry: ContextVar[TransactionRegistry | None] = ContextVar(
+    "_tx_registry",
+    default=None,
+)
+
+
+class TransactionContext:
+    """Transaction context."""
+
+    def __init__(self) -> None:
+        if _tx_registry.get() is None:
+            _ = _tx_registry.set(TransactionRegistry())
+
+    def current(self, connection: str | None = None) -> Option[Transaction]:
+        """Get the current transaction.
+
+        Returns:
+            The current transaction, if any.
+        """
+        registry = _tx_registry.get()
+        if registry is None:
+            return Nothing()
+
+        if connection is not None:
+            tx = registry.by_connection.get(connection)
+            return from_optional(tx)
+
+        if registry.stack:
+            return Some(registry.stack[-1])
+        return Nothing()
+
+
+@final
+class ConnectionManager:
+    """Connection manager."""
+
+    def __init__(
+        self,
+        name: str,
+        tx_context: TransactionContext,
+        logger: LogManager | None,
+        session_factory: async_sessionmaker[AsyncSession] | None = None,
+    ) -> None:
+        self.name = name
+        self.tx_context = tx_context
+        self.logger = logger
+        self.session_factory = session_factory
+
+    @asynccontextmanager
+    async def _scoped(self, tx: Transaction) -> AsyncIterator[None]:
+        """Manage registry, state transitions, and callbacks for a transaction.
+
+        Yields:
+            None
+        """
+        old_registry = _tx_registry.get()
+        token = (
+            _tx_registry.set(old_registry.extend(tx))
+            if old_registry is not None
+            else _tx_registry.set(TransactionRegistry())
+        )
+        try:
+            yield
+            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:
+                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,
+                        )
+            raise
+        finally:
+            _tx_registry.reset(token)
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[Transaction]:
+        """Open a new unbound transaction (no database session).
+
+        Intended for use in unit tests where transaction lifecycle, callbacks,
+        and context isolation need to be exercised without a real database.
+
+        Yields:
+            Transaction: An unbound transaction with no associated session.
+        """
+        parent = self.tx_context.current(self.name)
+        tx = Transaction(self.name)
+        tx.parent = parent
+        async with self._scoped(tx):
+            yield tx
+
+    @asynccontextmanager
+    async def begin(self) -> AsyncIterator[BoundTransaction]:
+        """Open a new bound transaction with an active database session.
+
+        For nested calls on the same connection, reuses the parent session
+        and begins a savepoint instead of a full transaction.
+
+        Raises:
+            RuntimeError: If no engine has been registered for this connection.
+
+        Yields:
+            BoundTransaction: A transaction with a guaranteed non-null session.
+        """
+        if self.session_factory is None:
+            raise RuntimeError(
+                f"No engine registered for connection '{self.name}'. "
+                + "Call register_engine() before calling begin()."
+            )
+
+        parent = self.tx_context.current(self.name)
+
+        match parent:
+            case Some(parent_tx) if isinstance(parent_tx, BoundTransaction):
+                tx = Transaction(self.name)
+                tx.parent = parent
+                bound = tx.begin(parent_tx.session)
+                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:
+                    bound = tx.begin(session)
+                    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.1.0/neva/database/manager.py

@@ -0,0 +1,111 @@
+"""Database manager."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import final
+
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
+
+from neva import Nothing, Option, Some
+from neva.database.connection import ConnectionManager, TransactionContext
+from neva.database.transaction import BoundTransaction, Transaction
+from neva.obs import LogManager
+
+
+@final
+class DatabaseManager:
+    """Database manager."""
+
+    def __init__(self, tx_context: TransactionContext, logger: LogManager) -> None:
+        self._tx_context = tx_context
+        self._logger = logger
+        self._connections: dict[str, ConnectionManager] = {}
+        self._engines: dict[str, AsyncEngine] = {}
+        self._session_factories: dict[str, async_sessionmaker[AsyncSession]] = {}
+
+    def register_engine(self, name: str, engine: AsyncEngine) -> None:
+        """Register an engine and create a session factory for a connection.
+
+        Args:
+            name: The connection name.
+            engine: The async engine.
+        """
+        self._engines[name] = engine
+        self._session_factories[name] = async_sessionmaker(
+            bind=engine,
+            expire_on_commit=False,
+        )
+        _ = self._connections.pop(name, None)
+
+    def connection(self, name: str) -> ConnectionManager:
+        """Returns a connection manager for the given name."""
+        return self._connections.setdefault(
+            name,
+            ConnectionManager(
+                name,
+                self._tx_context,
+                self._logger,
+                self._session_factories.get(name),
+            ),
+        )
+
+    def current(self, connection: str | None = None) -> Option[Transaction]:
+        """Returns the current transaction.
+
+        If no connection is specified, this will return the most recent transaction on
+        any connection. This is something to keep in mind.
+        """
+        return self._tx_context.current(connection)
+
+    def session(self, connection: str | None = None) -> Option[AsyncSession]:
+        """Returns the current session for a connection.
+
+        Args:
+            connection: The connection name. Defaults to "default".
+
+        Returns:
+            The current session, if any. Returns Nothing if there is no active
+            bound transaction on the given connection.
+        """
+        match self.current(connection):
+            case Some(tx) if isinstance(tx, BoundTransaction):
+                return Some(tx.session)
+            case _:
+                return Nothing()
+
+    @asynccontextmanager
+    async def transaction(self, name: str = "default") -> AsyncIterator[Transaction]:
+        """Open an unbound transaction on the named connection.
+
+        Intended for unit tests that exercise transaction lifecycle and callbacks
+        without a real database engine.
+
+        Yields:
+            Transaction: An unbound transaction with no associated session.
+        """
+        async with self.connection(name).transaction() as tx:
+            yield tx
+
+    @asynccontextmanager
+    async def begin(self, name: str = "default") -> AsyncIterator[BoundTransaction]:
+        """Open a bound transaction on the named connection.
+
+        Args:
+            name: The connection name.
+
+        Raises:
+            RuntimeError: If no engine has been registered for the connection.
+
+        Yields:
+            BoundTransaction: A transaction with a guaranteed non-null session.
+        """  # noqa: DOC502 explicit documentation of the possible exception raised by 'begin'
+        async with self.connection(name).begin() as tx:
+            yield tx
+
+    async def close(self) -> None:
+        """Dispose all engines and clear caches."""
+        for engine in self._engines.values():
+            await engine.dispose()
+        self._engines.clear()
+        self._session_factories.clear()
+        self._connections.clear()

{python_neva-1.0.5 → python_neva-2.1.0}/neva/database/provider.py

@@ -4,7 +4,7 @@ from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from typing import Self, override
 
-from tortoise import Tortoise
+from sqlalchemy.ext.asyncio import create_async_engine
 
 from neva import Err, Ok, Result
 from neva.arch import ServiceProvider
@@ -27,18 +27,19 @@ class DatabaseServiceProvider(ServiceProvider):
     async def lifespan(self) -> AsyncIterator[None]:
         """Initialize and cleanup database connections."""
         logger: LogManager = self.app.make(LogManager).unwrap()
-        logger.info("Beginning Tortoise initialization...")
+        db: DatabaseManager = self.app.make(DatabaseManager).unwrap()
+        logger.info("Beginning SQLAlchemy initialization...")
         match self.app.make(ConfigRepository).unwrap().get("database"):
             case Ok(config):
-                create_db = config.pop("create_db", False)
-                _ = await Tortoise.init(
-                    config=config,
-                    _create_db=create_db,
-                    _enable_global_fallback=True,
-                )
-                logger.info("Tortoise initialization complete.")
+                connections: dict = config.get("connections", {})
+                for name, conn_config in connections.items():
+                    url = conn_config.pop("url")
+                    engine = create_async_engine(url, **conn_config)
+                    db.register_engine(name, engine)
+                    logger.info(f"Registered engine for connection '{name}'.")
+                logger.info("SQLAlchemy initialization complete.")
                 yield
-                await Tortoise.close_connections()
+                await db.close()
             case Err(err):
                 logger.error(f"Failed to load database configuration: {err}")
                 yield

{python_neva-1.0.5 → python_neva-2.1.0}/neva/database/transaction.py

@@ -5,6 +5,8 @@ from dataclasses import dataclass, field
 from enum import Enum, auto
 from typing import Callable, Self
 
+from sqlalchemy.ext.asyncio import AsyncSession
+
 from neva import Err, Nothing, Option, Result, Some
 
 
@@ -25,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)
@@ -94,3 +97,34 @@ class Transaction:
                 results.append(Err(f"Callback raised: {e}"))
         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.
+
+        Transfers the parent relationship and all pending callbacks to the
+        returned BoundTransaction. The original transaction should not be
+        used after calling this method.
+
+        Args:
+            session: The SQLAlchemy async session to bind to.
+
+        Returns:
+            BoundTransaction: A new transaction with the session attached and
+                all state transferred from this transaction.
+        """
+        bound = BoundTransaction(self.conn_name, session=session)
+        bound.parent = self.parent
+        bound._on_commit = self._on_commit
+        bound._on_rollback = self._on_rollback
+        return bound
+
+
+@dataclass
+class BoundTransaction(Transaction):
+    """Transaction bound to an SQLAlchemy session."""
+
+    session: AsyncSession

{python_neva-1.0.5 → 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/db.pyi

@@ -0,0 +1,69 @@
+"""Type stub for DB facade."""
+
+from contextlib import AbstractAsyncContextManager
+from typing import override
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from neva import Option
+from neva.arch import Facade
+from neva.database import BoundTransaction, Transaction
+from neva.database.connection import ConnectionManager
+
+class DB(Facade):
+    @classmethod
+    @override
+    def get_facade_accessor(cls) -> type: ...
+    @classmethod
+    def connection(cls, name: str) -> ConnectionManager:
+        """Returns a connection manager for the given connection name."""
+
+    @classmethod
+    def current(cls, connection: str | None = None) -> Option[Transaction]:
+        """Returns the current transaction.
+
+        Args:
+            connection: If provided, returns the transaction for that specific
+                connection. If None, returns the innermost transaction.
+        """
+
+    @classmethod
+    def transaction(
+        cls, name: str = "default"
+    ) -> AbstractAsyncContextManager[Transaction]:
+        """Open an unbound transaction on the specified connection.
+
+        Intended for unit tests that exercise transaction lifecycle and callbacks
+        without a real database engine.
+
+        Args:
+            name: The connection name.
+
+        Yields:
+            Transaction: An unbound transaction with no associated session.
+        """
+
+    @classmethod
+    def begin(
+        cls, name: str = "default"
+    ) -> AbstractAsyncContextManager[BoundTransaction]:
+        """Open a bound transaction on the specified connection.
+
+        Args:
+            name: The connection name.
+
+        Yields:
+            BoundTransaction: A transaction with a guaranteed non-null session.
+        """
+
+    @classmethod
+    def session(cls, connection: str | None = None) -> Option[AsyncSession]:
+        """Returns the current session for a connection.
+
+        Args:
+            connection: The connection name. Defaults to "default".
+        """
+
+    @classmethod
+    async def close(cls) -> None:
+        """Dispose all engines and clear caches."""