tinkerfin-sqlalchemy 0.1.1__py3-none-any.whl

tinkerfin_sqlalchemy/__init__.py

@@ -0,0 +1,25 @@
+"""Asynchronous SQL transaction guarantees for storage integrations."""
+
+from .capabilities import (
+    DatabaseCapabilities,
+    SqlDialect,
+    database_capabilities,
+    engine_dialect,
+    mysql_error_code,
+    postgresql_error_code,
+    sqlite_lock_error,
+)
+from .errors import SqlTransactionError
+from .transaction import SqlTransaction
+
+__all__ = [
+    "DatabaseCapabilities",
+    "SqlDialect",
+    "SqlTransaction",
+    "SqlTransactionError",
+    "database_capabilities",
+    "engine_dialect",
+    "mysql_error_code",
+    "postgresql_error_code",
+    "sqlite_lock_error",
+]

tinkerfin_sqlalchemy/_settlement.py

@@ -0,0 +1,164 @@
+"""Wait for connection cleanup without losing cancellation or independent failures."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable
+from dataclasses import dataclass
+from typing import Generic, TypeGuard, TypeVar
+
+from .errors import SqlTransactionError
+
+ResultT = TypeVar("ResultT")
+
+
+def _is_group(error: BaseException) -> TypeGuard[BaseExceptionGroup[BaseException]]:
+    return isinstance(error, BaseExceptionGroup)
+
+
+def _contains(error: BaseException, target: BaseException) -> bool:
+    pending = [error]
+    seen: set[int] = set()
+    while pending:
+        current = pending.pop()
+        if current is target:
+            return True
+        if id(current) in seen:
+            continue
+        seen.add(id(current))
+        pending.extend(
+            item
+            for item in (current.__cause__, current.__context__)
+            if item is not None
+        )
+        if _is_group(current):
+            pending.extend(current.exceptions)
+        if isinstance(current, SqlTransactionError) and current.cause is not None:
+            pending.append(current.cause)
+    return False
+
+
+def retain_failure(primary: BaseException, secondary: BaseException) -> None:
+    """Keep independent causes without creating a back-reference to the primary."""
+
+    if _contains(primary, secondary):
+        return
+    retained: dict[int, BaseException | None] = {id(primary): None}
+
+    def detach(error: BaseException | None) -> BaseException | None:
+        if error is None:
+            return None
+        if id(error) in retained:
+            return retained[id(error)]
+        result: BaseException | None = error
+        if _is_group(error):
+            _, result = error.split(lambda item: item is primary)
+        retained[id(error)] = result
+        if result is None:
+            return None
+        result.__cause__ = detach(result.__cause__)
+        result.__context__ = detach(result.__context__)
+        if isinstance(result, SqlTransactionError):
+            result.cause = detach(result.cause)
+        if _is_group(result):
+            for item in result.exceptions:
+                detach(item)
+        return result
+
+    original = detach(primary.__cause__ or primary.__context__)
+    primary.__context__ = detach(primary.__context__)
+    additional = detach(secondary)
+    if additional is None:
+        return
+    primary.__cause__ = (
+        additional
+        if original is None
+        else original
+        if _contains(original, additional)
+        else BaseExceptionGroup("SQL transaction failures", [original, additional])
+    )
+    note = f"SQL cleanup also failed: {type(secondary).__name__}"
+    if note not in getattr(primary, "__notes__", ()):
+        primary.add_note(note)
+
+
+def select_failure(primary: BaseException, secondary: BaseException) -> BaseException:
+    """Keep process control ahead of cancellation and ordinary failures."""
+
+    def priority(error: BaseException) -> int:
+        if isinstance(error, asyncio.CancelledError):
+            return 1
+        return 0 if isinstance(error, Exception) else 2
+
+    if priority(secondary) > priority(primary):
+        retain_failure(secondary, primary)
+        return secondary
+    retain_failure(primary, secondary)
+    return primary
+
+
+def restore_caller_cancellation(
+    error: BaseException, previous_cancellations: int
+) -> BaseException:
+    """Preserve cancellation replaced by a driver's failing invalidation listener."""
+
+    caller = asyncio.current_task()
+    if caller is None or caller.cancelling() <= previous_cancellations:
+        return error
+    # SQLAlchemy Connection._handle_dbapi_exception may replace CancelledError
+    # while disposing the interrupted connection. Only a newly requested caller
+    # cancellation with matching exception evidence can change the scope outcome.
+    pending = [error]
+    seen: set[int] = set()
+    cancellations: list[asyncio.CancelledError] = []
+    while pending:
+        current = pending.pop()
+        if id(current) in seen:
+            continue
+        seen.add(id(current))
+        if isinstance(current, asyncio.CancelledError):
+            cancellations.append(current)
+        pending.extend(
+            item
+            for item in (current.__cause__, current.__context__)
+            if item is not None
+        )
+        if _is_group(current):
+            pending.extend(current.exceptions)
+        if isinstance(current, SqlTransactionError) and current.cause is not None:
+            pending.append(current.cause)
+    selected = error
+    for cancellation in cancellations:
+        selected = select_failure(selected, cancellation)
+    return selected
+
+
+@dataclass(frozen=True, slots=True)
+class _Result(Generic[ResultT]):
+    value: ResultT | None = None
+    error: BaseException | None = None
+
+
+async def settle(operation: Awaitable[ResultT]) -> ResultT | None:
+    """Join one owned I/O operation before delivering repeated caller cancellation."""
+
+    async def capture() -> _Result[ResultT]:
+        try:
+            return _Result(value=await operation)
+        except BaseException as error:  # noqa: BLE001 - transport process control to the owning caller
+            return _Result(error=error)
+
+    task = asyncio.create_task(capture(), name="tinkerfin-sql-connection-settlement")
+    cancellation: asyncio.CancelledError | None = None
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError as error:
+            cancellation = cancellation or error
+    result = task.result()
+    error = result.error
+    if cancellation is not None:
+        error = cancellation if error is None else select_failure(cancellation, error)
+    if error is not None:
+        raise error
+    return result.value

tinkerfin_sqlalchemy/capabilities.py

@@ -0,0 +1,109 @@
+"""Database capabilities and driver error facts without retry policy."""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from typing import Literal
+
+from sqlalchemy.exc import DBAPIError
+from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine
+
+SqlDialect = Literal["sqlite", "mysql", "postgresql"]
+
+
+def engine_dialect(engine: AsyncEngine) -> SqlDialect:
+    """Validate an async Engine and identify its SQL dialect without database I/O.
+
+    Args:
+        engine: Caller-owned asynchronous SQLAlchemy Engine.
+
+    Returns:
+        The supported SQL dialect; no driver or server connection is opened.
+
+    Raises:
+        TypeError: engine is not an AsyncEngine.
+        ValueError: The Engine uses an unsupported SQL dialect.
+    """
+
+    if not isinstance(engine, AsyncEngine):
+        raise TypeError("engine must be an AsyncEngine")
+    name = engine.dialect.name
+    if name == "sqlite" or name == "mysql" or name == "postgresql":
+        return name
+    raise ValueError("Supported SQL dialects are SQLite, MySQL, and PostgreSQL")
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseCapabilities:
+    """Locking capabilities of a connected database server.
+
+    Attributes:
+        dialect: Database family selected by the borrowed Engine.
+        server_version: Actual initialized SQLAlchemy server version.
+        row_locks: Whether SELECT FOR UPDATE acquires row locks.
+        skip_locked: Whether locked rows can be skipped when claiming work.
+    """
+
+    dialect: SqlDialect
+    server_version: tuple[int, ...]
+    row_locks: bool
+    skip_locked: bool
+
+
+def database_capabilities(connection: AsyncConnection) -> DatabaseCapabilities:
+    """Read initialized server features from an already opened connection.
+
+    Args:
+        connection: Live connection whose dialect completed server initialization.
+
+    Returns:
+        Verified locking features; SQLite never advertises row locking.
+
+    Raises:
+        ValueError: Server version or database family is unsupported.
+    """
+
+    dialect = connection.dialect
+    name = engine_dialect(connection.engine)
+    version = dialect.server_version_info
+    if not version or not all(isinstance(part, int) for part in version):
+        raise ValueError("The database server version is unavailable")
+    if name == "mysql" and bool(getattr(dialect, "is_mariadb", False)):
+        raise ValueError("MariaDB is not a supported SQL database")
+    if name == "mysql" and version < (5, 7):
+        raise ValueError("MySQL 5.7 or newer is required")
+    if name == "postgresql" and version < (9, 5):
+        raise ValueError("PostgreSQL 9.5 or newer is required")
+    return DatabaseCapabilities(
+        dialect=name,
+        server_version=tuple(version),
+        row_locks=name != "sqlite",
+        skip_locked=name == "postgresql" or (name == "mysql" and version >= (8,)),
+    )
+
+
+def sqlite_lock_error(error: BaseException) -> bool:
+    """Identify SQLite BUSY/LOCKED, including extended codes, without text matching."""
+
+    original = error.orig if isinstance(error, DBAPIError) else error
+    if not isinstance(original, sqlite3.Error):
+        return False
+    code = getattr(original, "sqlite_errorcode", None)
+    return isinstance(code, int) and (code & 0xFF) in {5, 6}
+
+
+def mysql_error_code(error: BaseException) -> int | None:
+    """Return a numeric MySQL driver code without deciding whether to retry."""
+
+    original = error.orig if isinstance(error, DBAPIError) else error
+    args = () if original is None else original.args
+    return args[0] if args and isinstance(args[0], int) else None
+
+
+def postgresql_error_code(error: BaseException) -> str | None:
+    """Return SQLSTATE from asyncpg or psycopg's SQLAlchemy driver boundary."""
+
+    original = error.orig if isinstance(error, DBAPIError) else error
+    code = getattr(original, "sqlstate", None) or getattr(original, "pgcode", None)
+    return code if isinstance(code, str) else None

tinkerfin_sqlalchemy/errors.py

@@ -0,0 +1,40 @@
+"""Failures owned by the shared SQL transaction boundary."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+from sqlalchemy.exc import SQLAlchemyError
+
+
+class SqlTransactionError(SQLAlchemyError):
+    """A transaction cannot establish or release its required database guarantees.
+
+    SQLAlchemyError inheritance lets a storage integration translate this failure
+    together with driver failures. Context is safe for callers; cause is diagnostic
+    evidence and must not be serialized into client responses.
+    """
+
+    code = "sqlalchemy.transaction"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        context: Mapping[str, str | int | bool | None] | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        """Snapshot safe context and retain the original diagnostic failure."""
+
+        self.message = message
+        self.context = MappingProxyType(dict(context or {}))
+        self.cause = cause
+        if cause is not None:
+            self.__cause__ = cause
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        """Return the safe message without interpreting the code as a SQLAlchemy URL."""
+
+        return self.message

tinkerfin_sqlalchemy/transaction.py

@@ -0,0 +1,556 @@
+"""Single-attempt transactions that restore or discard every borrowed connection."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+from types import TracebackType
+from typing import Literal
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine
+from sqlalchemy.pool import PoolProxiedConnection, StaticPool
+
+from ._settlement import restore_caller_cancellation, select_failure, settle
+from .capabilities import database_capabilities, engine_dialect, sqlite_lock_error
+from .errors import SqlTransactionError
+
+
+class SqlTransaction:
+    """Borrow one connection for an atomic write or a consistent read snapshot.
+
+    A successful write scope commits automatically; read scopes and failed writes
+    roll back. The Engine stays caller-owned. SQLite uses explicit BEGIN IMMEDIATE
+    for writes and BEGIN for reads. MySQL and PostgreSQL use explicit transactions
+    even when the host Engine uses AUTOCOMMIT. Connection settings are restored
+    before pool return; restoration or advisory-lock release failure discards the
+    physical connection.
+
+    The scope never retries domain operations. A storage implementation may call
+    commit() itself to retain the same transaction after SQLite COMMIT BUSY, and
+    inspect the outcome before applying its own retry policy. Use the yielded
+    connection for statements; transaction control and connection closure belong to
+    this scope. Engines must provide exclusive checkouts; StaticPool is rejected
+    because one borrower can otherwise roll back another borrower's work.
+    Cancellation during body I/O propagates after cleanup. Connection acquisition,
+    commit, rollback, and pool return settle before repeated caller cancellation
+    propagates. Driver connection and statement timeouts remain controlled by the
+    Engine's owner.
+
+    Args:
+        engine: Borrowed asynchronous SQLite, MySQL, or PostgreSQL Engine.
+        read_only: Select one repeatable snapshot instead of a write transaction.
+        isolation_level: Optional write isolation, for batches that read one snapshot
+            before writing. Read-only scopes require REPEATABLE READ; schema setup
+            requires READ COMMITTED. SQLite uses its explicit transaction guarantees.
+        sqlite_busy_timeout_ms: Temporary SQLite lock wait in milliseconds, or None
+            to retain the host setting. The scope never retries a busy result.
+        mysql_lock_wait_timeout_seconds: Temporary MySQL InnoDB row-lock wait.
+        schema_lock: Stable database-local name for mutually exclusive schema setup.
+            The lock and DDL must use this scope's connection.
+        schema_lock_timeout_seconds: Maximum database wait for the schema lock;
+            zero rejects an occupied lock immediately.
+
+    Raises:
+        TypeError: An Engine or timing argument has the wrong type.
+        ValueError: A timing value, dialect, or read-only option is invalid.
+        SqlTransactionError: A scope is reused or its database guarantees fail.
+    """
+
+    def __init__(
+        self,
+        engine: AsyncEngine,
+        *,
+        read_only: bool = False,
+        isolation_level: Literal["READ COMMITTED", "REPEATABLE READ"] | None = None,
+        sqlite_busy_timeout_ms: int | None = None,
+        mysql_lock_wait_timeout_seconds: int | None = None,
+        schema_lock: str | None = None,
+        schema_lock_timeout_seconds: int = 30,
+    ) -> None:
+        """Validate one transaction declaration without opening a connection."""
+
+        self._dialect = engine_dialect(engine)
+        if isinstance(engine.sync_engine.pool, StaticPool):
+            raise TypeError(
+                "SQL transactions require exclusive connection checkouts; "
+                "use AsyncAdaptedQueuePool for SQLite in-memory engines"
+            )
+        if schema_lock_timeout_seconds is None:
+            raise TypeError("schema_lock_timeout_seconds must be an integer")
+        for name, value, minimum in (
+            ("sqlite_busy_timeout_ms", sqlite_busy_timeout_ms, 0),
+            ("mysql_lock_wait_timeout_seconds", mysql_lock_wait_timeout_seconds, 1),
+            ("schema_lock_timeout_seconds", schema_lock_timeout_seconds, 0),
+        ):
+            if value is not None:
+                if isinstance(value, bool) or not isinstance(value, int):
+                    raise TypeError(f"{name} must be an integer")
+                if value < minimum:
+                    raise ValueError(f"{name} must be at least {minimum}")
+        if not isinstance(read_only, bool):
+            raise TypeError("read_only must be a boolean")
+        if isolation_level not in {None, "READ COMMITTED", "REPEATABLE READ"}:
+            raise ValueError("Unsupported transaction isolation level")
+        if read_only and isolation_level == "READ COMMITTED":
+            raise ValueError("Read-only scopes require a repeatable snapshot")
+        if schema_lock is not None:
+            if not isinstance(schema_lock, str):
+                raise TypeError("schema_lock must be a string or None")
+            if not schema_lock or schema_lock != schema_lock.strip():
+                raise ValueError("schema_lock must be a non-empty canonical name")
+            schema_lock.encode("utf-8")
+            if read_only:
+                raise ValueError("schema setup requires a write transaction")
+            if isolation_level == "REPEATABLE READ":
+                raise ValueError("schema setup requires READ COMMITTED isolation")
+        self._engine = engine
+        self._read_only = read_only
+        self._isolation_level = isolation_level or (
+            "REPEATABLE READ" if read_only else "READ COMMITTED"
+        )
+        self._busy_timeout = sqlite_busy_timeout_ms
+        self._mysql_timeout = mysql_lock_wait_timeout_seconds
+        self._schema_lock = schema_lock
+        self._schema_timeout = schema_lock_timeout_seconds
+        self._connection: AsyncConnection | None = None
+        self._pooled: PoolProxiedConnection | None = None
+        self._old_sqlite_timeout: int | None = None
+        self._old_sqlite_query_only: int | None = None
+        self._old_mysql_timeout: int | None = None
+        self._mysql_schema_lock: str | None = None
+        self._used = False
+        self._began = False
+        self._discard = False
+        self._committed = False
+        self._rolled_back = False
+        self._commit_uncertain = False
+        self._cleanup_failed = False
+        self._commit_failure: BaseException | None = None
+        self._cancellations = 0
+
+    @property
+    def committed(self) -> bool:
+        """Whether the database acknowledged this attempt's COMMIT."""
+
+        return self._committed
+
+    @property
+    def rolled_back(self) -> bool:
+        """Whether this attempt ended with an acknowledged ROLLBACK."""
+
+        return self._rolled_back
+
+    @property
+    def commit_uncertain(self) -> bool:
+        """Whether an issued COMMIT failed without proving that it stayed uncommitted."""
+
+        return self._commit_uncertain
+
+    @property
+    def cleanup_failed(self) -> bool:
+        """Whether rollback, settings restoration, or connection return failed.
+
+        A storage implementation must preserve this failure instead of retrying
+        the domain operation, even when physical connection disposal succeeded.
+
+        Returns:
+            True if any connection cleanup step failed.
+        """
+
+        return self._cleanup_failed
+
+    async def __aenter__(self) -> AsyncConnection:
+        """Open and initialize one owned connection checkout before exposing it.
+
+        Returns:
+            The borrowed SQLAlchemy connection inside its active transaction.
+
+        Raises:
+            SqlTransactionError: This declaration was already entered.
+            BaseException: Acquisition or initialization fails after cleanup.
+        """
+
+        if self._used:
+            raise SqlTransactionError("A SQL transaction declaration is single-use")
+        self._used = True
+        caller = asyncio.current_task()
+        self._cancellations = 0 if caller is None else caller.cancelling()
+        connection = self._engine.connect()
+        self._connection = connection
+        try:
+            await settle(connection.start())
+            self._pooled = await connection.get_raw_connection()
+            database_capabilities(connection)
+            await self._begin(connection)
+        except BaseException as error:
+            # Failed initialization may leave next-transaction settings or a session
+            # advisory lock active even when the driver reports no open transaction.
+            self._discard = True
+            primary = restore_caller_cancellation(error, self._cancellations)
+            await self._finish(primary)
+            if primary is not error:
+                raise primary
+            raise
+        return connection
+
+    async def __aexit__(
+        self,
+        _exc_type: type[BaseException] | None,
+        error: BaseException | None,
+        _traceback: TracebackType | None,
+    ) -> None:
+        """Commit successful work and settle all connection ownership before returning."""
+
+        primary = (
+            None
+            if error is None
+            else restore_caller_cancellation(error, self._cancellations)
+        )
+        try:
+            if primary is None and not self._read_only and not self._rolled_back:
+                await self.commit()
+        except BaseException as failure:  # noqa: BLE001 - pool return still owns every outcome
+            primary = failure
+        await self._finish(primary)
+        if primary is not None and primary is not error:
+            raise primary
+
+    def _require_connection(self) -> AsyncConnection:
+        connection = self._connection
+        if connection is None or connection.sync_connection is None:
+            raise SqlTransactionError("The SQL transaction is not active")
+        return connection
+
+    async def commit(self) -> None:
+        """Commit once, retaining a SQLite BUSY transaction for a domain-owned retry.
+
+        Raises:
+            SqlTransactionError: The scope is inactive, read-only, or rolled back.
+            BaseException: COMMIT fails or caller cancellation follows its settlement.
+        """
+
+        connection = self._require_connection()
+        if self._read_only or self._rolled_back:
+            raise SqlTransactionError("This SQL transaction cannot commit")
+        if self._committed:
+            return
+        if self._commit_uncertain:
+            assert self._commit_failure is not None
+            raise self._commit_failure
+
+        async def commit_once() -> None:
+            try:
+                if self._dialect == "sqlite":
+                    await connection.exec_driver_sql("COMMIT")
+                else:
+                    await connection.commit()
+            except BaseException as error:
+                self._commit_failure = error
+                self._commit_uncertain = not (
+                    self._dialect == "sqlite"
+                    and sqlite_lock_error(error)
+                    and not connection.invalidated
+                )
+                raise
+            self._committed = True
+            # Explicit SQL also works under host AUTOCOMMIT. Clear SQLAlchemy's
+            # autobegin bookkeeping after the server acknowledged completion.
+            await connection.rollback()
+
+        await settle(commit_once())
+
+    async def rollback(self) -> None:
+        """Acknowledge rollback without returning the connection or selecting a retry."""
+
+        connection = self._require_connection()
+        if self._committed or self._rolled_back:
+            return
+
+        async def rollback_once() -> None:
+            if self._began and not connection.invalidated:
+                if self._dialect == "sqlite" or (
+                    self._dialect == "mysql"
+                    and self._read_only
+                    and connection.dialect.skip_autocommit_rollback
+                ):
+                    # A host may disable driver rollback under AUTOCOMMIT, but the
+                    # explicit read transaction still has to end before pool return.
+                    await connection.exec_driver_sql("ROLLBACK")
+                else:
+                    await connection.rollback()
+                self._rolled_back = True
+            await connection.rollback()
+
+        try:
+            await settle(rollback_once())
+        except BaseException:
+            self._cleanup_failed = True
+            self._discard = True
+            raise
+
+    async def _begin(self, connection: AsyncConnection) -> None:
+        if self._dialect == "sqlite":
+            if self._read_only:
+                self._old_sqlite_query_only = await self._integer_setting(
+                    connection, "PRAGMA query_only"
+                )
+                await connection.exec_driver_sql("PRAGMA query_only = 1")
+                await connection.rollback()
+            wait = self._busy_timeout
+            if self._schema_lock is not None and wait is None:
+                wait = self._schema_timeout * 1000
+            if wait is not None:
+                self._old_sqlite_timeout = await self._integer_setting(
+                    connection, "PRAGMA busy_timeout"
+                )
+                await connection.exec_driver_sql(f"PRAGMA busy_timeout = {wait}")
+                await connection.rollback()
+            await connection.exec_driver_sql(
+                "BEGIN" if self._read_only else "BEGIN IMMEDIATE"
+            )
+            self._began = True
+            return
+
+        if self._dialect == "mysql":
+            if self._mysql_timeout is not None:
+                self._old_mysql_timeout = await self._integer_setting(
+                    connection, "SELECT @@SESSION.innodb_lock_wait_timeout"
+                )
+                await connection.exec_driver_sql(
+                    f"SET SESSION innodb_lock_wait_timeout = {self._mysql_timeout}"
+                )
+                await connection.rollback()
+            if self._schema_lock is not None:
+                database = self._engine.url.database or ""
+                digest = hashlib.sha256(
+                    f"{database}\0{self._schema_lock}".encode()
+                ).hexdigest()[:48]
+                lock_name = f"tinkerfin:{digest}"
+                acquired = await connection.scalar(
+                    text("SELECT GET_LOCK(:name, :timeout)"),
+                    {"name": lock_name, "timeout": self._schema_timeout},
+                )
+                if acquired != 1:
+                    raise SqlTransactionError(
+                        "The SQL schema lock could not be acquired"
+                    )
+                self._mysql_schema_lock = lock_name
+                await connection.rollback()
+            if self._read_only:
+                await connection.exec_driver_sql(
+                    "SET TRANSACTION ISOLATION LEVEL REPEATABLE READ"
+                )
+                await connection.exec_driver_sql("START TRANSACTION READ ONLY")
+            else:
+                await connection.execution_options(
+                    isolation_level=self._isolation_level
+                )
+                await connection.begin()
+        else:
+            # asyncpg starts its driver transaction before preparing the first SQL
+            # statement (SQLAlchemy 2.0.52 AsyncAdapt_asyncpg_cursor). Configure that
+            # transaction rather than issuing a nested raw BEGIN. Pool return resets
+            # the connection's isolation to the host Engine's configured default.
+            await connection.execution_options(isolation_level=self._isolation_level)
+            await connection.begin()
+            if self._read_only:
+                await connection.exec_driver_sql("SET TRANSACTION READ ONLY")
+        self._began = True
+
+        if self._dialect == "postgresql" and self._schema_lock is not None:
+            lock_key = int.from_bytes(
+                hashlib.sha256(self._schema_lock.encode("utf-8")).digest()[:8],
+                "big",
+                signed=True,
+            )
+            if self._schema_timeout == 0:
+                acquired = await connection.scalar(
+                    text("SELECT pg_try_advisory_xact_lock(:key)"), {"key": lock_key}
+                )
+                if not acquired:
+                    raise SqlTransactionError(
+                        "The SQL schema lock could not be acquired"
+                    )
+            else:
+                await connection.execute(
+                    text("SELECT set_config('lock_timeout', :timeout, true)"),
+                    {"timeout": f"{self._schema_timeout * 1000}ms"},
+                )
+                await connection.execute(
+                    text("SELECT pg_advisory_xact_lock(:key)"), {"key": lock_key}
+                )
+
+    @staticmethod
+    async def _integer_setting(connection: AsyncConnection, query: str) -> int:
+        value = (await connection.exec_driver_sql(query)).scalar_one()
+        if not isinstance(value, int) or value < 0:
+            raise SqlTransactionError(
+                "The database returned an invalid connection setting"
+            )
+        await connection.rollback()
+        return value
+
+    async def _invalidate(
+        self, connection: AsyncConnection, error: BaseException | None
+    ) -> None:
+        pooled = self._pooled
+        failures: list[BaseException] = []
+        try:
+            if (
+                connection.dialect.driver == "asyncmy"
+                and pooled is not None
+                and pooled.is_valid
+            ):
+                # asyncmy marks an interrupted socket unusable. Pool proxy
+                # invalidation terminates it outside that failed greenlet.
+                pooled.invalidate(error)
+            else:
+                # aiosqlite needs awaited graceful close to release SQLite locks.
+                await connection.invalidate(error)
+        except BaseException as failure:  # noqa: BLE001 - verify physical disposal even when host events fail
+            failures.append(failure)
+        if pooled is not None and pooled.is_valid:
+            try:
+                await self._retire_connection(connection, pooled)
+            except BaseException as failure:  # noqa: BLE001 - retain every failure from the disposal boundary
+                failures.append(failure)
+        try:
+            await connection.rollback()
+        except BaseException as failure:  # noqa: BLE001 - clear transaction bookkeeping after driver disposal
+            failures.append(failure)
+        if failures:
+            selected = failures[0]
+            for failure in failures[1:]:
+                selected = select_failure(selected, failure)
+            raise selected
+
+    async def _retire_connection(
+        self, connection: AsyncConnection, pooled: PoolProxiedConnection
+    ) -> None:
+        """Detach an unsafe live checkout before closing its actual driver connection.
+
+        SQLAlchemy 2.0.52 _ConnectionRecord.invalidate dispatches host listeners
+        before physical close. A listener failure must not return the unsafe socket
+        to the pool. Public detach removes pool ownership before its own event, so
+        driver disposal can finish even if that event fails as well. The dialect's
+        close runs inside run_sync to await native async driver cleanup.
+        """
+
+        dbapi = pooled.dbapi_connection
+        assert dbapi is not None
+        failures: list[BaseException] = []
+        try:
+            await connection.run_sync(lambda _sync: pooled.detach())
+        except BaseException as failure:  # noqa: BLE001 - detach events run after pool ownership is released
+            failures.append(failure)
+        if not pooled.is_detached:
+            raise SqlTransactionError(
+                "An unsafe SQL connection could not be detached from its pool",
+                cause=failures[0] if failures else None,
+            )
+        try:
+            await connection.run_sync(lambda sync: sync.dialect.do_close(dbapi))
+        except BaseException as failure:  # noqa: BLE001 - a failed graceful close still requires termination
+            failures.append(failure)
+            try:
+                await connection.run_sync(lambda sync: sync.dialect.do_terminate(dbapi))
+            except BaseException as termination_error:  # noqa: BLE001 - retain the failed final termination
+                failures.append(termination_error)
+        finally:
+            # A detached proxy has no pool record: invalidate clears its references
+            # without invoking the failed pool event or closing the driver again.
+            pooled.invalidate()
+        if failures:
+            selected = failures[0]
+            for failure in failures[1:]:
+                selected = select_failure(selected, failure)
+            raise selected
+
+    async def _finish(self, primary: BaseException | None) -> None:
+        connection = self._connection
+        if connection is None:
+            return
+
+        async def cleanup() -> None:
+            errors: list[BaseException] = []
+            try:
+                if connection.sync_connection is None:
+                    return
+                discard = (
+                    self._discard
+                    or self._commit_uncertain
+                    or isinstance(primary, asyncio.CancelledError)
+                )
+                if not discard and not connection.invalidated:
+                    try:
+                        await self.rollback()
+                        if self._old_sqlite_timeout is not None:
+                            await connection.exec_driver_sql(
+                                f"PRAGMA busy_timeout = {self._old_sqlite_timeout}"
+                            )
+                        if self._old_sqlite_query_only is not None:
+                            await connection.exec_driver_sql(
+                                f"PRAGMA query_only = {self._old_sqlite_query_only}"
+                            )
+                        if self._old_mysql_timeout is not None:
+                            await connection.exec_driver_sql(
+                                f"SET SESSION innodb_lock_wait_timeout = {self._old_mysql_timeout}"
+                            )
+                        if self._mysql_schema_lock is not None:
+                            released = await connection.scalar(
+                                text("SELECT RELEASE_LOCK(:name)"),
+                                {"name": self._mysql_schema_lock},
+                            )
+                            if released != 1:
+                                raise SqlTransactionError(
+                                    "The SQL schema lock could not be released"
+                                )
+                        await connection.rollback()
+                    except BaseException as error:  # noqa: BLE001 - failed settings cannot enter the pool
+                        errors.append(error)
+                        discard = True
+                if discard or connection.invalidated:
+                    try:
+                        await self._invalidate(connection, primary)
+                    except BaseException as error:  # noqa: BLE001 - close still has to return the checkout
+                        errors.append(error)
+            finally:
+                try:
+                    if connection.sync_connection is not None:
+                        await connection.close()
+                except BaseException as error:  # noqa: BLE001 - preserve all cleanup evidence
+                    errors.append(error)
+                    # A failed AsyncConnection.close() is not evidence of pool
+                    # return. Invalidate the physical connection, then close its
+                    # already captured invalid proxy to return this checkout. That
+                    # final proxy close performs no driver I/O after invalidation.
+                    if not connection.closed:
+                        try:
+                            await self._invalidate(connection, error)
+                        except BaseException as invalidate_error:  # noqa: BLE001 - retain cleanup failures together
+                            errors.append(invalidate_error)
+                        finally:
+                            pooled = self._pooled
+                            if pooled is not None and not pooled.is_valid:
+                                try:
+                                    pooled.close()
+                                except BaseException as return_error:  # noqa: BLE001 - report a failed checkout return
+                                    errors.append(return_error)
+            if errors:
+                self._cleanup_failed = True
+                selected = errors[0]
+                for error in errors[1:]:
+                    selected = select_failure(selected, error)
+                raise selected
+
+        try:
+            await settle(cleanup())
+        except BaseException as cleanup_error:
+            if primary is None:
+                raise
+            selected = select_failure(primary, cleanup_error)
+            if selected is not primary:
+                raise selected
+        finally:
+            self._connection = None

tinkerfin_sqlalchemy-0.1.1.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: tinkerfin-sqlalchemy
+Version: 0.1.1
+Summary: Async SQL transaction and connection ownership for TinkerFin storage integrations.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/tinkerfin-ai/tinkerfin-harness
+Project-URL: Repository, https://github.com/tinkerfin-ai/tinkerfin-harness
+Project-URL: Issues, https://github.com/tinkerfin-ai/tinkerfin-harness/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy[asyncio]==2.0.52
+Dynamic: license-file
+
+# tinkerfin-sqlalchemy
+
+Async transaction support for storage integrations using SQLite, MySQL, or PostgreSQL.
+Application code normally uses a TinkerFin Store and supplies its own SQLAlchemy
+`AsyncEngine`; storage integrations use `SqlTransaction` directly.
+
+## Installation
+
+```bash
+pip install tinkerfin-sqlalchemy
+```
+
+Python 3.11 or newer is required. Install an asynchronous database driver such as
+`aiosqlite`, `asyncmy`, or `asyncpg`.
+
+## Quick Start
+
+Install the driver for this in-memory example:
+
+```bash
+pip install aiosqlite
+```
+
+```python
+import asyncio
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.pool import AsyncAdaptedQueuePool
+
+from tinkerfin_sqlalchemy import SqlTransaction
+
+
+async def main() -> None:
+    engine = create_async_engine(
+        "sqlite+aiosqlite:///:memory:",
+        poolclass=AsyncAdaptedQueuePool,
+        pool_size=1,
+        max_overflow=0,
+    )
+    try:
+        async with SqlTransaction(engine, schema_lock="example-balances") as connection:
+            await connection.execute(
+                text("CREATE TABLE balances (amount INTEGER NOT NULL)")
+            )
+            await connection.execute(text("INSERT INTO balances (amount) VALUES (0)"))
+
+        async with SqlTransaction(engine) as connection:
+            await connection.execute(text("UPDATE balances SET amount = amount + 1"))
+
+        async with SqlTransaction(engine, read_only=True) as connection:
+            result = await connection.execute(text("SELECT amount FROM balances"))
+            print(result.scalar_one())
+    finally:
+        await engine.dispose()
+
+
+asyncio.run(main())
+```
+
+Successful writes commit; failed writes roll back. Reads share one database snapshot.
+The Engine remains owned by the caller. Temporary lock settings are restored before
+connections return to the pool; connections that cannot be restored are discarded.
+Cancellation waits for connection cleanup. Driver timeouts remain host configuration.
+
+Connections must have exclusive pool checkouts. File-based SQLite engines use this
+by default. For an in-memory SQLite database, configure `AsyncAdaptedQueuePool` with
+`pool_size=1` and `max_overflow=0`; `StaticPool` shares one live connection across
+transactions and is rejected. Discarding an in-memory connection also discards its data.
+
+For schema setup, supply a stable `schema_lock` name and run DDL on the yielded
+connection. Integrations keep their own schema, retry policy, and commit confirmation.
+`SqlTransaction` performs one attempt and never replays application work.
+
+## Documentation
+
+[TinkerFin documentation](https://github.com/tinkerfin-ai/tinkerfin-harness/blob/main/docs/en/index.md)
+
+## License
+
+[Apache-2.0](https://github.com/tinkerfin-ai/tinkerfin-harness/blob/main/LICENSE)

tinkerfin_sqlalchemy-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+tinkerfin_sqlalchemy/__init__.py,sha256=JTzqME2LhNnbBUX0N2bqEwp3fnZx1zdR-I_BWHyl_5g,583
+tinkerfin_sqlalchemy/_settlement.py,sha256=KlAETDijrMturZKoGXcZR6SPEy7eSjWSMJbEN6rvyV8,5774
+tinkerfin_sqlalchemy/capabilities.py,sha256=GUPwQOzW9demX4gpBNf1XQIP-DSb17CH9z7ByxN-VJU,3965
+tinkerfin_sqlalchemy/errors.py,sha256=z09qckYsRPAsT6MZ1jJnW36zGR4jTokkuniHmCZeiAQ,1260
+tinkerfin_sqlalchemy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tinkerfin_sqlalchemy/transaction.py,sha256=5QV3__fVQTEtWAu9UW9ukVpDbX9QnauH7kteQQ-RhGg,25299
+tinkerfin_sqlalchemy-0.1.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+tinkerfin_sqlalchemy-0.1.1.dist-info/METADATA,sha256=44LaROp_HSNToYI797lGAxXQHRoxHeo-n4wfUGDYQOQ,3694
+tinkerfin_sqlalchemy-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+tinkerfin_sqlalchemy-0.1.1.dist-info/top_level.txt,sha256=DHpaqBxnErj85Q0OzNQTk3vuPg9D9ysPFQRKXkOr_IM,21
+tinkerfin_sqlalchemy-0.1.1.dist-info/RECORD,,

tinkerfin_sqlalchemy-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tinkerfin_sqlalchemy-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

tinkerfin_sqlalchemy-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+tinkerfin_sqlalchemy