sqla-fancy-core 1.1.2__tar.gz → 1.2.0__tar.gz

{sqla_fancy_core-1.1.2 → sqla_fancy_core-1.2.0}/.gitignore

@@ -158,3 +158,4 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+.vscode/

{sqla_fancy_core-1.1.2 → sqla_fancy_core-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqla-fancy-core
-Version: 1.1.2
+Version: 1.2.0
 Summary: SQLAlchemy core, but fancier
 Project-URL: Homepage, https://github.com/sayanarijit/sqla-fancy-core
 Author-email: Arijit Basu <sayanarijit@gmail.com>
@@ -158,13 +158,18 @@ async with engine.begin() as txn:
 
 ## Fancy Engine Wrappers
 
-`sqla-fancy-core` provides `fancy` engine wrappers that simplify database interactions by automatically managing connections and transactions. The `fancy` function wraps a SQLAlchemy `Engine` or `AsyncEngine` and returns a wrapper object with two primary methods:
+`sqla-fancy-core` provides `fancy` engine wrappers that simplify database interactions by automatically managing connections and transactions. The `fancy` function wraps a SQLAlchemy `Engine` or `AsyncEngine` and returns a wrapper object with the following methods:
 
 - `x(conn, query)`: Executes a query. It uses the provided `conn` if available, otherwise it creates a new connection.
-- `tx(conn, query)`: Executes a query within a transaction. It uses the provided `conn` if available, otherwise it creates a new connection and begins a transaction.
+- `tx(conn, query)`: Executes a query within a transaction. It uses the provided `conn` if available, otherwise it tries to use the atomic context if within one, else creates a new connection and begins a transaction.
+- `atomic()`: A context manager for grouping multiple operations in a single transaction scope.
+- `ax(query)`: Executes a query using the connection from the active `atomic()` context. Raises `AtomicContextError` if called outside an `atomic()` block.
+- `atx(query)`: Executes a query inside a transaction automatically. If already inside `atomic()`, it reuses the same connection and transaction; otherwise it opens a new transaction just for this call.
 
 This is particularly useful for writing connection-agnostic query functions.
 
+### Basic Examples
+
 **Sync Example:**
 
 ```python
@@ -208,6 +213,78 @@ async def main():
         assert await get_data(conn) == 1
 ```
 
+### Using the atomic() Context Manager
+
+The `atomic()` context manager lets you group several database operations within one transactional scope. Queries executed with `ax()` inside this context all use the same connection. Nested `atomic()` contexts reuse the outer connection automatically.
+
+**Sync Example:**
+
+```python
+import sqlalchemy as sa
+from sqla_fancy_core import fancy, TableFactory
+
+tf = TableFactory()
+
+class User:
+    id = tf.auto_id()
+    name = tf.string("name")
+    Table = tf("users")
+
+engine = sa.create_engine("sqlite:///:memory:")
+tf.metadata.create_all(engine)
+fancy_engine = fancy(engine)
+
+# Group operations in one transaction
+with fancy_engine.atomic():
+    fancy_engine.ax(sa.insert(User.Table).values(name="Alice"))
+    fancy_engine.ax(sa.insert(User.Table).values(name="Bob"))
+    result = fancy_engine.ax(sa.select(sa.func.count()).select_from(User.Table))
+    count = result.scalar_one()
+    assert count == 2
+```
+
+**Async Example:**
+
+```python
+import sqlalchemy as sa
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqla_fancy_core import fancy, TableFactory
+
+tf = TableFactory()
+
+class User:
+    id = tf.auto_id()
+    name = tf.string("name")
+    Table = tf("users")
+
+async def run_example():
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(tf.metadata.create_all)
+
+    fancy_engine = fancy(engine)
+
+    async with fancy_engine.atomic():
+        await fancy_engine.ax(sa.insert(User.Table).values(name="Alice"))
+        await fancy_engine.ax(sa.insert(User.Table).values(name="Bob"))
+        result = await fancy_engine.ax(sa.select(sa.func.count()).select_from(User.Table))
+        count = result.scalar_one()
+        assert count == 2
+```
+
+**Key Points:**
+
+- `ax()` must be called inside an `atomic()` context. Calling it elsewhere raises `AtomicContextError`.
+- `atx()` is a safe/ergonomic helper: it will run inside the current `atomic()` transaction when present, or create a short-lived transaction otherwise.
+- Nesting `atomic()` contexts is safe. Inner contexts share the outer connection instead of creating a new transaction.
+- On normal exit, the transaction commits automatically. On exception, it rolls back.
+
+### ax vs atx vs tx
+
+- `ax(q)`: Only valid inside `atomic()`. Uses the ambient transactional connection. Great for batch operations grouped by an outer context.
+- `atx(q)`: Fire-and-forget in a transaction. Reuses the ambient `atomic()` connection if present; otherwise starts and commits its own transaction.
+- `tx(conn, q)`: Low-level primitive. If `conn` is provided, it executes within it, creating a transaction when needed; if `None`, it prefers the `atomic()` connection when active or opens a new transactional connection.
+
 ## Decorators: Inject, connect, transact
 
 When writing plain SQLAlchemy Core code, you often pass connections around and manage transactions manually. The decorators in `sqla-fancy-core` help you keep functions connection-agnostic and composable, while remaining explicit and safe.

{sqla_fancy_core-1.1.2 → sqla_fancy_core-1.2.0}/README.md

@@ -106,13 +106,18 @@ async with engine.begin() as txn:
 
 ## Fancy Engine Wrappers
 
-`sqla-fancy-core` provides `fancy` engine wrappers that simplify database interactions by automatically managing connections and transactions. The `fancy` function wraps a SQLAlchemy `Engine` or `AsyncEngine` and returns a wrapper object with two primary methods:
+`sqla-fancy-core` provides `fancy` engine wrappers that simplify database interactions by automatically managing connections and transactions. The `fancy` function wraps a SQLAlchemy `Engine` or `AsyncEngine` and returns a wrapper object with the following methods:
 
 - `x(conn, query)`: Executes a query. It uses the provided `conn` if available, otherwise it creates a new connection.
-- `tx(conn, query)`: Executes a query within a transaction. It uses the provided `conn` if available, otherwise it creates a new connection and begins a transaction.
+- `tx(conn, query)`: Executes a query within a transaction. It uses the provided `conn` if available, otherwise it tries to use the atomic context if within one, else creates a new connection and begins a transaction.
+- `atomic()`: A context manager for grouping multiple operations in a single transaction scope.
+- `ax(query)`: Executes a query using the connection from the active `atomic()` context. Raises `AtomicContextError` if called outside an `atomic()` block.
+- `atx(query)`: Executes a query inside a transaction automatically. If already inside `atomic()`, it reuses the same connection and transaction; otherwise it opens a new transaction just for this call.
 
 This is particularly useful for writing connection-agnostic query functions.
 
+### Basic Examples
+
 **Sync Example:**
 
 ```python
@@ -156,6 +161,78 @@ async def main():
         assert await get_data(conn) == 1
 ```
 
+### Using the atomic() Context Manager
+
+The `atomic()` context manager lets you group several database operations within one transactional scope. Queries executed with `ax()` inside this context all use the same connection. Nested `atomic()` contexts reuse the outer connection automatically.
+
+**Sync Example:**
+
+```python
+import sqlalchemy as sa
+from sqla_fancy_core import fancy, TableFactory
+
+tf = TableFactory()
+
+class User:
+    id = tf.auto_id()
+    name = tf.string("name")
+    Table = tf("users")
+
+engine = sa.create_engine("sqlite:///:memory:")
+tf.metadata.create_all(engine)
+fancy_engine = fancy(engine)
+
+# Group operations in one transaction
+with fancy_engine.atomic():
+    fancy_engine.ax(sa.insert(User.Table).values(name="Alice"))
+    fancy_engine.ax(sa.insert(User.Table).values(name="Bob"))
+    result = fancy_engine.ax(sa.select(sa.func.count()).select_from(User.Table))
+    count = result.scalar_one()
+    assert count == 2
+```
+
+**Async Example:**
+
+```python
+import sqlalchemy as sa
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqla_fancy_core import fancy, TableFactory
+
+tf = TableFactory()
+
+class User:
+    id = tf.auto_id()
+    name = tf.string("name")
+    Table = tf("users")
+
+async def run_example():
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(tf.metadata.create_all)
+
+    fancy_engine = fancy(engine)
+
+    async with fancy_engine.atomic():
+        await fancy_engine.ax(sa.insert(User.Table).values(name="Alice"))
+        await fancy_engine.ax(sa.insert(User.Table).values(name="Bob"))
+        result = await fancy_engine.ax(sa.select(sa.func.count()).select_from(User.Table))
+        count = result.scalar_one()
+        assert count == 2
+```
+
+**Key Points:**
+
+- `ax()` must be called inside an `atomic()` context. Calling it elsewhere raises `AtomicContextError`.
+- `atx()` is a safe/ergonomic helper: it will run inside the current `atomic()` transaction when present, or create a short-lived transaction otherwise.
+- Nesting `atomic()` contexts is safe. Inner contexts share the outer connection instead of creating a new transaction.
+- On normal exit, the transaction commits automatically. On exception, it rolls back.
+
+### ax vs atx vs tx
+
+- `ax(q)`: Only valid inside `atomic()`. Uses the ambient transactional connection. Great for batch operations grouped by an outer context.
+- `atx(q)`: Fire-and-forget in a transaction. Reuses the ambient `atomic()` connection if present; otherwise starts and commits its own transaction.
+- `tx(conn, q)`: Low-level primitive. If `conn` is provided, it executes within it, creating a transaction when needed; if `None`, it prefers the `atomic()` connection when active or opens a new transactional connection.
+
 ## Decorators: Inject, connect, transact
 
 When writing plain SQLAlchemy Core code, you often pass connections around and manage transactions manually. The decorators in `sqla-fancy-core` help you keep functions connection-agnostic and composable, while remaining explicit and safe.

{sqla_fancy_core-1.1.2 → sqla_fancy_core-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = 'sqla-fancy-core'
-version = '1.1.2'
+version = '1.2.0'
 description = 'SQLAlchemy core, but fancier'
 readme = 'README.md'
 requires-python = ">=3.7"

{sqla_fancy_core-1.1.2 → sqla_fancy_core-1.2.0}/sqla_fancy_core/__init__.py

@@ -1,5 +1,11 @@
 """SQLAlchemy core, but fancier."""
 
 from sqla_fancy_core.factories import TableFactory  # noqa
-from sqla_fancy_core.wrappers import FancyEngineWrapper, AsyncFancyEngineWrapper, fancy  # noqa
+from sqla_fancy_core.wrappers import (  # noqa
+    FancyEngineWrapper,
+    AsyncFancyEngineWrapper,
+    fancy,
+    FancyError,
+    AtomicContextError,
+)
 from sqla_fancy_core.decorators import transact, Inject  # noqa

{sqla_fancy_core-1.1.2 → sqla_fancy_core-1.2.0}/sqla_fancy_core/wrappers.py

@@ -1,5 +1,7 @@
 """Some wrappers for fun times with SQLAlchemy core."""
 
+from contextlib import asynccontextmanager, contextmanager
+from contextvars import ContextVar
 from typing import Any, Optional, TypeVar, overload
 
 from sqlalchemy import Connection, CursorResult, Engine, Executable
@@ -16,12 +18,80 @@ from sqlalchemy.sql.selectable import TypedReturnsRows
 _T = TypeVar("_T", bound=Any)
 
 
+class FancyError(Exception):
+    """Custom error for FancyEngineWrapper."""
+
+    pass
+
+
+class AtomicContextError(FancyError):
+    """Error raised when ax() is called outside of an atomic context."""
+
+    def __init__(self) -> None:
+        super().__init__("ax() must be called within the atomic() context manager")
+
+
 class FancyEngineWrapper:
     """A wrapper around SQLAlchemy Engine with additional features."""
 
+    _ATOMIC_TX_CONN: ContextVar[Optional[Connection]] = ContextVar(  # type: ignore
+        "fancy_global_transaction", default=None
+    )
+
     def __init__(self, engine: Engine) -> None:
         self.engine = engine
 
+    @contextmanager
+    def atomic(self):
+        """A context manager that provides a transactional connection."""
+        global_txn_conn = self._ATOMIC_TX_CONN.get()
+        if global_txn_conn is not None:
+            # Reuse existing transaction connection
+            yield global_txn_conn
+        else:
+            with self.engine.begin() as connection:
+                token = self._ATOMIC_TX_CONN.set(connection)
+                try:
+                    yield connection
+                finally:
+                    # Restore previous ContextVar state
+                    self._ATOMIC_TX_CONN.reset(token)
+
+    @overload
+    def ax(
+        self,
+        statement: TypedReturnsRows[_T],
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[_T]: ...
+    @overload
+    def ax(
+        self,
+        statement: Executable,
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[Any]: ...
+    def ax(
+        self,
+        statement: Executable,
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[Any]:
+        """Execute the query within the atomic context and return the result.
+
+        It must be called within the `atomic` context manager. Else an error is raised.
+        """
+        connection = self._ATOMIC_TX_CONN.get()
+        if connection:
+            return connection.execute(
+                statement, parameters, execution_options=execution_options
+            )
+        else:
+            raise AtomicContextError()
+
     @overload
     def x(
         self,
@@ -52,6 +122,7 @@ class FancyEngineWrapper:
 
         If a connection is provided, use it; otherwise, create a new one.
         """
+        connection = connection
         if connection:
             return connection.execute(
                 statement, parameters, execution_options=execution_options
@@ -90,8 +161,10 @@ class FancyEngineWrapper:
     ) -> CursorResult[Any]:
         """Begin a transaction, execute the query, and return the result.
 
-        If a connection is provided, use it; otherwise, create a new one.
+        If a connection is provided, use it; otherwise, use the global atomic
+        context or create a new one.
         """
+        connection = connection or self._ATOMIC_TX_CONN.get()
         if connection:
             if connection.in_transaction():
                 # Transaction is already active
@@ -109,13 +182,95 @@ class FancyEngineWrapper:
                     statement, parameters, execution_options=execution_options
                 )
 
+    @overload
+    def atx(
+        self,
+        statement: TypedReturnsRows[_T],
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[_T]: ...
+    @overload
+    def atx(
+        self,
+        statement: Executable,
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[Any]: ...
+    def atx(
+        self,
+        statement: Executable,
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[Any]:
+        """If within an atomic context, execute the query there; else, create a new transaction."""
+        with self.atomic() as connection:
+            return connection.execute(
+                statement, parameters, execution_options=execution_options
+            )
+
 
 class AsyncFancyEngineWrapper:
     """A wrapper around SQLAlchemy AsyncEngine with additional features."""
 
+    _ATOMIC_TX_CONN: ContextVar[Optional[AsyncConnection]] = ContextVar(  # type: ignore
+        "fancy_global_transaction", default=None
+    )
+
     def __init__(self, engine: AsyncEngine) -> None:
         self.engine = engine
 
+    @asynccontextmanager
+    async def atomic(self):
+        """An async context manager that provides a transactional connection."""
+        global_txn_conn = self._ATOMIC_TX_CONN.get()
+        if global_txn_conn is not None:
+            yield global_txn_conn
+        else:
+            async with self.engine.begin() as connection:
+                token = self._ATOMIC_TX_CONN.set(connection)
+                try:
+                    yield connection
+                finally:
+                    self._ATOMIC_TX_CONN.reset(token)
+
+    @overload
+    async def ax(
+        self,
+        statement: TypedReturnsRows[_T],
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[_T]: ...
+    @overload
+    async def ax(
+        self,
+        statement: Executable,
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[Any]: ...
+    async def ax(
+        self,
+        statement: Executable,
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[Any]:
+        """Execute the query within the atomic context and return the result.
+
+        It must be called within the `atomic` context manager. Else an error is raised.
+        """
+        connection = self._ATOMIC_TX_CONN.get()
+        if connection:
+            return await connection.execute(
+                statement, parameters, execution_options=execution_options
+            )
+        else:
+            raise AtomicContextError()
+
     @overload
     async def x(
         self,
@@ -184,8 +339,10 @@ class AsyncFancyEngineWrapper:
     ) -> CursorResult[Any]:
         """Execute the query within a transaction and return the result.
 
-        If a connection is provided, use it; otherwise, create a new one.
+        If a connection is provided, use it; otherwise, use the global atomic
+        context or create a new one.
         """
+        connection = connection or self._ATOMIC_TX_CONN.get()
         if connection:
             if connection.in_transaction():
                 return await connection.execute(
@@ -202,6 +359,35 @@ class AsyncFancyEngineWrapper:
                     statement, parameters, execution_options=execution_options
                 )
 
+    @overload
+    async def atx(
+        self,
+        statement: TypedReturnsRows[_T],
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[_T]: ...
+    @overload
+    async def atx(
+        self,
+        statement: Executable,
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[Any]: ...
+    async def atx(
+        self,
+        statement: Executable,
+        parameters: Optional[_CoreAnyExecuteParams] = None,
+        *,
+        execution_options: Optional[CoreExecuteOptionsParameter] = None,
+    ) -> CursorResult[Any]:
+        """If within an atomic context, execute the query there; else, create a new transaction."""
+        async with self.atomic() as connection:
+            return await connection.execute(
+                statement, parameters, execution_options=execution_options
+            )
+
 
 @overload
 def fancy(obj: Engine, /) -> FancyEngineWrapper: ...

sqla_fancy_core-1.2.0/tests/test_async_atomic.py

@@ -0,0 +1,96 @@
+import pytest
+import pytest_asyncio
+import sqlalchemy as sa
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from sqla_fancy_core import TableFactory, fancy
+from sqla_fancy_core.wrappers import AtomicContextError
+
+
+tf = TableFactory()
+
+
+class Counter:
+    id = tf.auto_id()
+    Table = tf("counter")
+
+
+q_insert = sa.insert(Counter.Table)
+q_count = sa.select(sa.func.count()).select_from(Counter.Table)
+
+
+@pytest_asyncio.fixture
+async def fancy_engine():
+    eng = fancy(create_async_engine("sqlite+aiosqlite:///:memory:"))
+    async with eng.engine.begin() as conn:
+        await conn.run_sync(tf.metadata.create_all)
+    try:
+        yield eng
+    finally:
+        async with eng.engine.begin() as conn:
+            await conn.run_sync(tf.metadata.drop_all)
+        await eng.engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_ax_raises_outside_atomic(fancy_engine):
+    with pytest.raises(AtomicContextError):
+        await fancy_engine.ax(q_count)
+
+
+@pytest.mark.asyncio
+async def test_ax_inside_atomic_commits_on_exit(fancy_engine):
+    assert (await fancy_engine.x(None, q_count)).scalar_one() == 0
+    async with fancy_engine.atomic() as conn:
+        await fancy_engine.ax(q_insert)
+        await fancy_engine.ax(q_insert)
+        assert (await fancy_engine.ax(q_count)).scalar_one() == 2
+        assert conn.in_transaction() is True
+    assert (await fancy_engine.x(None, q_count)).scalar_one() == 2
+
+
+@pytest.mark.asyncio
+async def test_nested_atomic_reuses_same_connection(fancy_engine):
+    async with fancy_engine.atomic() as conn1:
+        async with fancy_engine.atomic() as conn2:
+            assert conn1 is conn2
+            await fancy_engine.ax(q_insert)
+            assert (await fancy_engine.ax(q_count)).scalar_one() == 1
+    assert (await fancy_engine.x(None, q_count)).scalar_one() == 1
+
+
+@pytest.mark.asyncio
+async def test_tx_uses_atomic_connection_when_inside(fancy_engine):
+    assert (await fancy_engine.x(None, q_count)).scalar_one() == 0
+    async with fancy_engine.atomic() as conn:
+        await fancy_engine.tx(None, q_insert)
+        assert (await fancy_engine.tx(conn, q_count)).scalar_one() == 1
+        assert conn.in_transaction() is True
+    assert (await fancy_engine.x(None, q_count)).scalar_one() == 1
+
+
+@pytest.mark.asyncio
+async def test_atomic_rollback_on_exception(fancy_engine):
+    assert (await fancy_engine.x(None, q_count)).scalar_one() == 0
+    with pytest.raises(RuntimeError):
+        async with fancy_engine.atomic():
+            await fancy_engine.ax(q_insert)
+            assert (await fancy_engine.ax(q_count)).scalar_one() == 1
+            raise RuntimeError("boom")
+    assert (await fancy_engine.x(None, q_count)).scalar_one() == 0
+
+
+@pytest.mark.asyncio
+async def test_atx_outside_atomic_commits(fancy_engine):
+    assert (await fancy_engine.x(None, q_count)).scalar_one() == 0
+    await fancy_engine.atx(q_insert)
+    assert (await fancy_engine.x(None, q_count)).scalar_one() == 1
+
+
+@pytest.mark.asyncio
+async def test_atx_inside_atomic_reuses_same_connection(fancy_engine):
+    async with fancy_engine.atomic() as conn:
+        await fancy_engine.atx(q_insert)
+        assert (await fancy_engine.ax(q_count)).scalar_one() == 1
+        assert conn.in_transaction() is True
+    assert (await fancy_engine.x(None, q_count)).scalar_one() == 1

sqla_fancy_core-1.2.0/tests/test_atomic.py

@@ -0,0 +1,92 @@
+import pytest
+import sqlalchemy as sa
+
+from sqla_fancy_core import TableFactory, fancy
+from sqla_fancy_core.wrappers import AtomicContextError
+
+tf = TableFactory()
+
+
+class Counter:
+    id = tf.auto_id()
+    Table = tf("counter")
+
+
+q_insert = sa.insert(Counter.Table)
+q_count = sa.select(sa.func.count()).select_from(Counter.Table)
+
+
+@pytest.fixture
+def fancy_engine():
+    eng = fancy(sa.create_engine("sqlite:///:memory:"))
+    tf.metadata.create_all(eng.engine)
+    try:
+        yield eng
+    finally:
+        tf.metadata.drop_all(eng.engine)
+        eng.engine.dispose()
+
+
+def test_ax_raises_outside_atomic(fancy_engine):
+    with pytest.raises(AtomicContextError):
+        fancy_engine.ax(q_count)
+
+
+def test_ax_inside_atomic_commits_on_exit(fancy_engine):
+    assert fancy_engine.x(None, q_count).scalar_one() == 0
+    with fancy_engine.atomic() as conn:
+        # multiple ax() calls share the same connection
+        fancy_engine.ax(q_insert)
+        fancy_engine.ax(q_insert)
+        # visibility within the same transaction
+        assert fancy_engine.ax(q_count).scalar_one() == 2
+        assert conn.in_transaction() is True
+    # committed after context exit
+    assert fancy_engine.x(None, q_count).scalar_one() == 2
+
+
+def test_nested_atomic_reuses_same_connection(fancy_engine):
+    with fancy_engine.atomic() as conn1:
+        with fancy_engine.atomic() as conn2:
+            assert conn1 is conn2
+            fancy_engine.ax(q_insert)
+            assert fancy_engine.ax(q_count).scalar_one() == 1
+    assert fancy_engine.x(None, q_count).scalar_one() == 1
+
+
+def test_tx_uses_atomic_connection_when_inside(fancy_engine):
+    assert fancy_engine.x(None, q_count).scalar_one() == 0
+    with fancy_engine.atomic() as conn:
+        # tx(None, ...) should reuse the atomic connection/transaction
+        fancy_engine.tx(None, q_insert)
+        # The outer connection should see the uncommitted row
+        assert fancy_engine.tx(conn, q_count).scalar_one() == 1
+        assert conn.in_transaction() is True
+    # committed at outer context exit
+    assert fancy_engine.x(None, q_count).scalar_one() == 1
+
+
+def test_atomic_rollback_on_exception(fancy_engine):
+    assert fancy_engine.x(None, q_count).scalar_one() == 0
+    with pytest.raises(RuntimeError):
+        with fancy_engine.atomic():
+            fancy_engine.ax(q_insert)
+            assert fancy_engine.ax(q_count).scalar_one() == 1
+            raise RuntimeError("boom")
+    # rolled back
+    assert fancy_engine.x(None, q_count).scalar_one() == 0
+
+
+def test_atx_outside_atomic_commits(fancy_engine):
+    assert fancy_engine.x(None, q_count).scalar_one() == 0
+    fancy_engine.atx(q_insert)
+    assert fancy_engine.x(None, q_count).scalar_one() == 1
+
+
+def test_atx_inside_atomic_reuses_same_connection(fancy_engine):
+    with fancy_engine.atomic() as conn:
+        fancy_engine.atx(q_insert)
+        # Same transactional visibility within the atomic connection
+        assert fancy_engine.ax(q_count).scalar_one() == 1
+        assert conn.in_transaction() is True
+    assert fancy_engine.x(None, q_count).scalar_one() == 1

{sqla_fancy_core-1.1.2 → sqla_fancy_core-1.2.0}/uv.lock

@@ -2968,7 +2968,7 @@ wheels = [
 
 [[package]]
 name = "sqla-fancy-core"
-version = "1.1.2"
+version = "1.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "sqlalchemy" },