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

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

@@ -1,17 +1,18 @@
 Metadata-Version: 2.4
 Name: python-neva
-Version: 1.0.4
+Version: 2.0.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.124.0
+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.4 → python_neva-2.0.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.0.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-1.0.4 → python_neva-2.0.0}/neva/database/connection.py

@@ -6,10 +6,10 @@ from contextvars import ContextVar
 from dataclasses import dataclass, field
 from typing import final
 
-from tortoise.transactions import in_transaction
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
 from neva import Nothing, Option, Some, from_optional
-from neva.database.transaction import Transaction, TransactionState
+from neva.database.transaction import BoundTransaction, Transaction, TransactionState
 from neva.obs import LogManager
 
 
@@ -73,33 +73,28 @@ class ConnectionManager:
         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 transaction(
-        self,
-    ) -> AsyncIterator[Transaction]:
-        """Open a new transaction.
+    async def _scoped(self, tx: Transaction) -> AsyncIterator[None]:
+        """Manage registry, state transitions, and callbacks for a transaction.
 
         Yields:
-            Transaction: The new transaction.
+            None
         """
-        parent = self.tx_context.current(self.name)
-        tx = Transaction(self.name)
-        tx.parent = parent
         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:
-            async with in_transaction(self.name):
-                yield tx
+            yield
             tx.state = TransactionState.COMMITTED
             if tx.is_root:
                 for result in await tx.execute_on_commit_callbacks():
@@ -122,3 +117,55 @@ class ConnectionManager:
             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)
+                async with self._scoped(bound), parent_tx.session.begin_nested():
+                    yield bound
+            case _:
+                tx = Transaction(self.name)
+                tx.parent = Nothing()
+                async with self.session_factory() as session, session.begin():
+                    bound = tx.begin(session)
+                    async with self._scoped(bound):
+                        yield bound

python_neva-2.0.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.4 → python_neva-2.0.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, exceptions
+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):
-                try:
-                    _ = await Tortoise.init(
-                        config=config, _create_db=True, _enable_global_fallback=True
-                    )
-                except exceptions.OperationalError:
-                    _ = await Tortoise.init(config=config, _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.4 → python_neva-2.0.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
 
 
@@ -94,3 +96,30 @@ class Transaction:
                 results.append(Err(f"Callback raised: {e}"))
         self._on_rollback.clear()
         return results
+
+    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-2.0.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."""

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

@@ -7,20 +7,21 @@ packages = ["neva"]
 
 [project]
 name = "python-neva"
-version = "1.0.4"
+version = "2.0.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
   "cryptography>=46.0.3",
   "dishka>=1.7.2",
-  "fastapi[all]>=0.124.0",
+  "fastapi[all]>=0.129.0",
   "faststream>=0.6.6",
-  "flexmock>=0.13.0",
   "pwdlib[argon2,bcrypt]>=0.3.0",
   "pyinstrument>=5.1.1",
   "structlog>=25.5.0",
-  "tortoise-orm[accel]>=1.1.4",
+  "sqlalchemy[asyncio]>=2.0.0",
+  "asyncpg>=0.30.0",
+  "aiosqlite>=0.20.0",
   "typer>=0.21.1",
 ]
 

python_neva-2.0.0/tests/database/conftest.py

@@ -0,0 +1,10 @@
+"""Shared fixtures for database tests."""
+
+import pytest
+
+from neva.database.connection import TransactionContext
+
+
+@pytest.fixture
+def tx_context() -> TransactionContext:
+    return TransactionContext()

{python_neva-1.0.4 → python_neva-2.0.0}/tests/database/test_connection_manager.py

@@ -3,7 +3,7 @@
 import pytest
 
 from neva.database.connection import ConnectionManager, TransactionContext
-from neva.database.transaction import TransactionState
+from neva.database.transaction import BoundTransaction, TransactionState
 from neva.obs import LogManager
 
 
@@ -82,3 +82,16 @@ class TestConnectionManager:
                 raise RuntimeError(msg)
 
         assert tx_context.current().is_nothing
+
+    async def test_transaction_yields_unbound_transaction(
+        self, manager: ConnectionManager
+    ) -> None:
+        async with manager.transaction() as tx:
+            assert not isinstance(tx, BoundTransaction)
+
+    async def test_begin_raises_without_engine(
+        self, manager: ConnectionManager
+    ) -> None:
+        with pytest.raises(RuntimeError, match="No engine registered"):
+            async with manager.begin():
+                pass

{python_neva-1.0.4 → python_neva-2.0.0}/tests/database/test_database_manager.py

@@ -1,6 +1,7 @@
 """Database manager tests."""
 
 import pytest
+from sqlalchemy.ext.asyncio import create_async_engine
 
 from neva.database.connection import ConnectionManager, TransactionContext
 from neva.database.manager import DatabaseManager
@@ -57,3 +58,41 @@ class TestDatabaseManager:
         assert default is not analytics
         assert isinstance(default, ConnectionManager)
         assert isinstance(analytics, ConnectionManager)
+
+    async def test_session_returns_nothing_outside_transaction(
+        self, db: DatabaseManager
+    ) -> None:
+        assert db.session().is_nothing
+
+    async def test_session_returns_nothing_in_unbound_transaction(
+        self, db: DatabaseManager
+    ) -> None:
+        async with db.transaction():
+            assert db.session().is_nothing
+
+    async def test_session_with_connection_name_returns_nothing_when_no_match(
+        self, db: DatabaseManager
+    ) -> None:
+        async with db.transaction("default"):
+            assert db.session("other").is_nothing
+
+    async def test_begin_raises_without_engine(self, db: DatabaseManager) -> None:
+        with pytest.raises(RuntimeError, match="No engine registered"):
+            async with db.begin():
+                pass
+
+
+class TestRegisterEngineCache:
+    def test_register_engine_invalidates_stale_connection_manager(self) -> None:
+        engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+        tx_context = TransactionContext()
+        db = DatabaseManager(tx_context, LogManager())
+
+        stale = db.connection("default")
+        assert stale.session_factory is None
+
+        db.register_engine("default", engine)
+
+        fresh = db.connection("default")
+        assert fresh is not stale
+        assert fresh.session_factory is not None

{python_neva-1.0.4 → python_neva-2.0.0}/tests/database/test_edge_cases.py

@@ -1,16 +1,7 @@
 """Transaction edge case tests."""
 
-import pytest
-
 from neva import Err, Ok, Result, Some
-from neva.database.connection import ConnectionManager, TransactionContext
-from neva.database.transaction import Transaction, TransactionState
-from neva.obs import LogManager
-
-
-@pytest.fixture
-def manager(tx_context: TransactionContext) -> ConnectionManager:
-    return ConnectionManager("default", tx_context, LogManager())
+from neva.database.transaction import Transaction
 
 
 class TestTransactionEdgeCases:
@@ -34,21 +25,26 @@ class TestTransactionEdgeCases:
         assert callback_results[0].is_err
         assert callback_results[1].is_ok
 
-    async def test_registering_callback_on_committed_transaction(self) -> None:
-        tx = Transaction("default")
-        tx.state = TransactionState.COMMITTED
-        called = False
+    async def test_deeply_nested_same_connection_callbacks_reach_root(self) -> None:
+        root = Transaction("default")
+        child = Transaction("default")
+        child.parent = Some(root)
+        grandchild = Transaction("default")
+        grandchild.parent = Some(child)
+
+        results: list[str] = []
 
         async def callback() -> Result[None, str]:
-            nonlocal called
-            called = True
+            results.append("reached_root")
             return Ok(None)
 
-        tx.on_commit(callback)
+        grandchild.on_commit(callback)
 
-        assert not called
+        assert callback in root._on_commit
+        await root.execute_on_commit_callbacks()
+        assert results == ["reached_root"]
 
-    async def test_deeply_nested_same_connection_callbacks_reach_root(self) -> None:
+    async def test_deeply_nested_rollback_callbacks_reach_root(self) -> None:
         root = Transaction("default")
         child = Transaction("default")
         child.parent = Some(root)
@@ -61,10 +57,10 @@ class TestTransactionEdgeCases:
             results.append("reached_root")
             return Ok(None)
 
-        grandchild.on_commit(callback)
+        grandchild.on_rollback(callback)
 
-        assert callback in root._on_commit
-        await root.execute_on_commit_callbacks()
+        assert callback in root._on_rollback
+        await root.execute_on_rollback_callbacks()
         assert results == ["reached_root"]
 
     async def test_empty_transaction_no_callbacks(self) -> None:
@@ -76,34 +72,6 @@ class TestTransactionEdgeCases:
         assert commit_results == []
         assert rollback_results == []
 
-    async def test_current_after_all_transactions_closed(
-        self, manager: ConnectionManager, tx_context: TransactionContext
-    ) -> None:
-        async with manager.transaction():
-            pass
-
-        async with manager.transaction():
-            pass
-
-        assert tx_context.current().is_nothing
-
-    async def test_multiple_callbacks_same_transaction(self) -> None:
-        tx = Transaction("default")
-        results: list[int] = []
-
-        for i in range(5):
-
-            async def callback(n: int = i) -> Result[None, str]:
-                results.append(n)
-                return Ok(None)
-
-            tx.on_commit(callback)
-
-        callback_results = await tx.execute_on_commit_callbacks()
-
-        assert results == [0, 1, 2, 3, 4]
-        assert all(r.is_ok for r in callback_results)
-
     async def test_callback_registered_during_callback_execution(self) -> None:
         tx = Transaction("default")
         results: list[str] = []