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

{sqla_fancy_core-1.1.1 → 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.1 → sqla_fancy_core-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqla-fancy-core
-Version: 1.1.1
+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.
@@ -242,27 +319,24 @@ users = sa.Table(
 )
 metadata.create_all(engine)
 
-# 1) Ensure a connection is available (no implicit transaction)
 @connect
 def get_user_count(conn=Inject(engine)):
     return conn.execute(sa.select(sa.func.count()).select_from(users)).scalar_one()
 
 assert get_user_count() == 0
 
-# 2) Wrap in a transaction automatically
 @transact
 def create_user(name: str, conn=Inject(engine)):
     conn.execute(sa.insert(users).values(name=name))
 
+# Without an explicit transaction
 create_user("alice")
 assert get_user_count() == 1
 
-# 3) Reuse an explicit connection or transaction
+# With an explicit transaction
 with engine.begin() as txn:
     create_user("bob", conn=txn)
     assert get_user_count(conn=txn) == 2
-
-assert get_user_count() == 2
 ```
 
 ### Async examples
@@ -293,10 +367,12 @@ async def get_user_count(conn=Inject(engine)):
 async def create_user(name: str, conn=Inject(engine)):
     await conn.execute(sa.insert(users).values(name=name))
 
+# Without an explicit transaction
 assert await get_user_count() == 0
 await create_user("carol")
 assert await get_user_count() == 1
 
+# With an explicit transaction
 async with engine.connect() as conn:
     await create_user("dave", conn=conn)
     assert await get_user_count(conn=conn) == 2

{sqla_fancy_core-1.1.1 → 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.
@@ -190,27 +267,24 @@ users = sa.Table(
 )
 metadata.create_all(engine)
 
-# 1) Ensure a connection is available (no implicit transaction)
 @connect
 def get_user_count(conn=Inject(engine)):
     return conn.execute(sa.select(sa.func.count()).select_from(users)).scalar_one()
 
 assert get_user_count() == 0
 
-# 2) Wrap in a transaction automatically
 @transact
 def create_user(name: str, conn=Inject(engine)):
     conn.execute(sa.insert(users).values(name=name))
 
+# Without an explicit transaction
 create_user("alice")
 assert get_user_count() == 1
 
-# 3) Reuse an explicit connection or transaction
+# With an explicit transaction
 with engine.begin() as txn:
     create_user("bob", conn=txn)
     assert get_user_count(conn=txn) == 2
-
-assert get_user_count() == 2
 ```
 
 ### Async examples
@@ -241,10 +315,12 @@ async def get_user_count(conn=Inject(engine)):
 async def create_user(name: str, conn=Inject(engine)):
     await conn.execute(sa.insert(users).values(name=name))
 
+# Without an explicit transaction
 assert await get_user_count() == 0
 await create_user("carol")
 assert await get_user_count() == 1
 
+# With an explicit transaction
 async with engine.connect() as conn:
     await create_user("dave", conn=conn)
     assert await get_user_count(conn=conn) == 2

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

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

{sqla_fancy_core-1.1.1 → 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.1 → sqla_fancy_core-1.2.0}/sqla_fancy_core/decorators.py

@@ -7,7 +7,9 @@ from typing import Union, overload
 import sqlalchemy as sa
 from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine
 
-EngineType = Union[sa.Engine, AsyncEngine]
+from sqla_fancy_core.wrappers import AsyncFancyEngineWrapper, FancyEngineWrapper
+
+EngineType = Union[sa.Engine, AsyncEngine, FancyEngineWrapper, AsyncFancyEngineWrapper]
 
 
 class _Injectable:
@@ -16,9 +18,9 @@ class _Injectable:
 
 
 @overload
-def Inject(engine: sa.Engine) -> sa.Connection: ...
+def Inject(engine: Union[sa.Engine, FancyEngineWrapper]) -> sa.Connection: ...
 @overload
-def Inject(engine: AsyncEngine) -> AsyncConnection: ...
+def Inject(engine: Union[AsyncEngine, AsyncFancyEngineWrapper]) -> AsyncConnection: ...
 def Inject(engine: EngineType):  # type: ignore
     """A marker class for dependency injection."""
     return _Injectable(engine)
@@ -44,7 +46,6 @@ def transact(func):
             create_user(name="existing", conn=conn)
     """
 
-    # Find the parameter with value Inject
     sig = inspect.signature(func)
     inject_param_name = None
     for name, param in sig.parameters.items():
@@ -56,8 +57,21 @@ def transact(func):
     if inject_param_name is None:
         return func  # No injection needed
 
-    engine = sig.parameters[inject_param_name].default.engine
-    is_async = isinstance(engine, AsyncEngine)
+    engine_arg = sig.parameters[inject_param_name].default.engine
+    if isinstance(engine_arg, sa.Engine):
+        is_async = False
+        engine = engine_arg
+    elif isinstance(engine_arg, FancyEngineWrapper):
+        is_async = False
+        engine = engine_arg.engine
+    elif isinstance(engine_arg, AsyncEngine):
+        is_async = True
+        engine = engine_arg
+    elif isinstance(engine_arg, AsyncFancyEngineWrapper):
+        is_async = True
+        engine = engine_arg.engine
+    else:
+        raise TypeError("Unsupported engine type")
 
     if is_async:
 
@@ -70,8 +84,14 @@ def transact(func):
                 else:
                     async with conn.begin():
                         return await func(*args, **kwargs)
+            elif isinstance(conn, sa.Connection):
+                if conn.in_transaction():
+                    return await func(*args, **kwargs)
+                else:
+                    with conn.begin():
+                        return await func(*args, **kwargs)
             else:
-                async with engine.begin() as conn:
+                async with engine.begin() as conn:  # type: ignore
                     kwargs[inject_param_name] = conn
                     return await func(*args, **kwargs)
 
@@ -88,8 +108,10 @@ def transact(func):
                 else:
                     with conn.begin():
                         return func(*args, **kwargs)
+            elif isinstance(conn, AsyncConnection):
+                raise TypeError("AsyncConnection cannot be used in sync function")
             else:
-                with engine.begin() as conn:
+                with engine.begin() as conn:  # type: ignore
                     kwargs[inject_param_name] = conn
                     return func(*args, **kwargs)
 
@@ -116,7 +138,6 @@ def connect(func):
             count = get_user_count(conn)
     """
 
-    # Find the parameter with value Inject
     sig = inspect.signature(func)
     inject_param_name = None
     for name, param in sig.parameters.items():
@@ -128,18 +149,31 @@ def connect(func):
     if inject_param_name is None:
         return func  # No injection needed
 
-    engine = sig.parameters[inject_param_name].default.engine
-    is_async = isinstance(engine, AsyncEngine)
+    engine_arg = sig.parameters[inject_param_name].default.engine
+    if isinstance(engine_arg, sa.Engine):
+        is_async = False
+        engine = engine_arg
+    elif isinstance(engine_arg, FancyEngineWrapper):
+        is_async = False
+        engine = engine_arg.engine
+    elif isinstance(engine_arg, AsyncEngine):
+        is_async = True
+        engine = engine_arg
+    elif isinstance(engine_arg, AsyncFancyEngineWrapper):
+        is_async = True
+        engine = engine_arg.engine
+    else:
+        raise TypeError("Unsupported engine type")
 
     if is_async:
 
         @functools.wraps(func)
         async def async_wrapper(*args, **kwargs):
             conn = kwargs.get(inject_param_name)
-            if isinstance(conn, AsyncConnection):
+            if isinstance(conn, (AsyncConnection, sa.Connection)):
                 return await func(*args, **kwargs)
             else:
-                async with engine.connect() as conn:
+                async with engine.connect() as conn:  # type: ignore
                     kwargs[inject_param_name] = conn
                     return await func(*args, **kwargs)
 
@@ -152,8 +186,10 @@ def connect(func):
             conn = kwargs.get(inject_param_name)
             if isinstance(conn, sa.Connection):
                 return func(*args, **kwargs)
+            elif isinstance(conn, AsyncConnection):
+                raise TypeError("AsyncConnection cannot be used in sync function")
             else:
-                with engine.connect() as conn:
+                with engine.connect() as conn:  # type: ignore
                     kwargs[inject_param_name] = conn
                     return func(*args, **kwargs)