sqlalchemy-dqlite 0.2.0__tar.gz → 0.2.2__tar.gz

{sqlalchemy_dqlite-0.2.0 → sqlalchemy_dqlite-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlalchemy-dqlite
-Version: 0.2.0
+Version: 0.2.2
 Summary: SQLAlchemy 2.0 dialect for dqlite distributed SQLite
 Project-URL: Homepage, https://github.com/letsdiscodev/sqlalchemy-dqlite
 Project-URL: Repository, https://github.com/letsdiscodev/sqlalchemy-dqlite
@@ -22,9 +22,9 @@ Classifier: Topic :: Database :: Database Engines/Servers
 Classifier: Topic :: Database :: Front-Ends
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
-Requires-Dist: dqlite-client<0.3.0,>=0.2.0
-Requires-Dist: dqlite-dbapi<0.3.0,>=0.2.0
-Requires-Dist: dqlite-wire<0.3.0,>=0.2.0
+Requires-Dist: dqlite-client<0.3.0,>=0.2.2
+Requires-Dist: dqlite-dbapi<0.3.0,>=0.2.2
+Requires-Dist: dqlite-wire<0.3.0,>=0.2.2
 Requires-Dist: sqlalchemy<3.0,>=2.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'

{sqlalchemy_dqlite-0.2.0 → sqlalchemy_dqlite-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlalchemy-dqlite"
-version = "0.2.0"
+version = "0.2.2"
 description = "SQLAlchemy 2.0 dialect for dqlite distributed SQLite"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -26,15 +26,15 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "dqlite-dbapi>=0.2.0,<0.3.0",
+    "dqlite-dbapi>=0.2.2,<0.3.0",
     # The SA dialect imports dqliteclient and dqlitewire directly
     # (base.py / aio.py reach into client exception classes for
     # is_disconnect, and into dqlitewire for shared helpers). Pin
     # both transitively so a future major-version bump in either
     # package surfaces at install time, not at module-import time
     # in user code.
-    "dqlite-client>=0.2.0,<0.3.0",
-    "dqlite-wire>=0.2.0,<0.3.0",
+    "dqlite-client>=0.2.2,<0.3.0",
+    "dqlite-wire>=0.2.2,<0.3.0",
     "sqlalchemy>=2.0,<3.0",
 ]
 

{sqlalchemy_dqlite-0.2.0 → sqlalchemy_dqlite-0.2.2}/src/sqlalchemydqlite/__init__.py

@@ -27,7 +27,7 @@ from sqlalchemy.dialects.sqlite import (
 from sqlalchemydqlite.aio import DqliteDialect_aio
 from sqlalchemydqlite.base import DqliteCompiler, DqliteDialect
 
-__version__: _Final[str] = "0.2.0"
+__version__: _Final[str] = "0.2.2"
 
 # SA convention (every shipped dialect package — sqlite, mysql, mssql,
 # oracle, postgresql): expose ``<package>.dialect`` pointing at the

{sqlalchemy_dqlite-0.2.0 → sqlalchemy_dqlite-0.2.2}/src/sqlalchemydqlite/aio.py

@@ -514,6 +514,25 @@ class AsyncAdaptedCursor:
         very large bind set must drive multiple ``execute()`` calls
         themselves; ``executemany`` cannot stream because the retry
         contract requires re-iteration.
+
+        ``lastrowid`` handling: same sticky-INSERT contract as
+        ``execute`` (see ``execute``'s docstring for the full
+        rationale). Both branches below write ``self.lastrowid`` only
+        when the underlying cursor reports a non-None value (i.e., an
+        INSERT/REPLACE actually ran in this executemany); a subsequent
+        ``UPDATE``/``DELETE``/``SELECT`` executemany preserves the
+        prior INSERT's lastrowid, matching stdlib ``sqlite3.Cursor``
+        stickiness. DIVERGES from SA's aiosqlite reference
+        (``sqlalchemy/dialects/sqlite/aiosqlite.py``'s ``executemany``
+        body) which assigns ``self.lastrowid = _cursor.lastrowid``
+        unconditionally — under that shape, a non-INSERT
+        ``executemany`` clears the value to ``None``. Cross-driver
+        code consulting ``cursor.lastrowid`` after a non-INSERT
+        ``executemany`` sees the prior INSERT's value here vs ``None``
+        on aiosqlite. The dqlite stance privileges stdlib parity over
+        SA-reference parity; the choice is documented at both call
+        sites because the underlying RETURNING-path drain pattern
+        otherwise structurally mirrors the SA reference shape.
         """
         # Mirror the closed-cursor guard the other methods on this
         # class apply; see ``execute`` for the rationale.
@@ -933,11 +952,20 @@ class AsyncAdaptedConnection(AdaptedConnection):
         exposes it, and ``AttributeError`` on dqlite would force those
         tools onto a less-informative fallback path.
 
-        Returns the union of the project-wide transport-class catch
-        tuple (``OperationalError`` / ``InterfaceError`` /
-        ``DqliteConnectionError`` / ``OSError``) plus
-        ``asyncio.CancelledError`` — i.e., the same exceptions that the
-        hand-rolled :meth:`terminate` body explicitly suppresses.
+        Returns the union of three groups, one per catch arm in the
+        hand-rolled :meth:`terminate` body:
+
+        * ``_TRANSPORT_CLASS_EXCEPTIONS`` — ``OperationalError`` /
+          ``InterfaceError`` / ``DqliteConnectionError`` / ``OSError``
+          (terminate() arm 1; the body DEBUG-logs and returns).
+        * ``RuntimeError`` — defunct-loop close shape
+          (``RuntimeError("Event loop is closed")``) from
+          ``engine.dispose()`` after an ``asyncio.run()`` per-call
+          tore the loop down (terminate() arm 2; the body
+          DEBUG-logs and runs ``_force_close_transport``).
+        * ``asyncio.CancelledError`` — outer cancel during forced
+          reclaim (terminate() arm 3; the body runs
+          ``_force_close_transport`` and re-raises).
 
         ``terminate()`` itself stays hand-rolled rather than reusing
         SA's ``AsyncAdapt_terminate`` mixin: the dqlite lifecycle
@@ -945,9 +973,11 @@ class AsyncAdaptedConnection(AdaptedConnection):
         both ``_terminate_graceful_close`` and ``_terminate_force_close``
         against an inert template. This method exists purely so
         introspection-only callers see a tuple
-        that matches the hand-rolled body's catch arms.
+        that matches the hand-rolled body's catch arms. Any new
+        ``except`` arm added to ``terminate()`` must be reflected
+        here to keep the contract honoured.
         """
-        return _TRANSPORT_CLASS_EXCEPTIONS + (asyncio.CancelledError,)
+        return _TRANSPORT_CLASS_EXCEPTIONS + (RuntimeError, asyncio.CancelledError)
 
     def __init__(
         self,
@@ -991,6 +1021,42 @@ class AsyncAdaptedConnection(AdaptedConnection):
         else:
             inner_conn = connection
             dbapi_module = dbapi
+        # Type-shape guard: detect the third plausible call shape —
+        # the positional swap ``AsyncAdaptedConnection(connection,
+        # dbapi)`` — that the ``_UNSET`` sentinel cannot discriminate.
+        # Without this guard the swap silently poisons both slots and
+        # the downstream ``AttributeError`` (on ``self._connection.cursor()``
+        # or third-party ``self.dbapi.OperationalError`` lookup) surfaces
+        # many frames from the construction site.
+        #
+        # Confirmed-swap signature: the supposed dbapi (first
+        # positional) lacks ``OperationalError`` but exposes
+        # ``cursor`` — i.e. it shape-looks like a connection — AND
+        # the supposed connection (second positional) lacks
+        # ``cursor`` but exposes ``OperationalError`` — i.e. it
+        # shape-looks like a dbapi module. Both conditions firing
+        # together is the unambiguous swap fingerprint; a single
+        # mismatch could be a minimal in-tree fake that lacks both
+        # attributes by design (the test suite has several), so the
+        # guard tolerates that shape and only rejects the
+        # bilaterally swapped call.
+        if (
+            dbapi_module is not None
+            and inner_conn is not None
+            and not hasattr(dbapi_module, "OperationalError")
+            and hasattr(dbapi_module, "cursor")
+            and not hasattr(inner_conn, "cursor")
+            and hasattr(inner_conn, "OperationalError")
+        ):
+            raise TypeError(
+                f"AsyncAdaptedConnection __init__: positional "
+                f"arguments appear swapped — first positional "
+                f"({type(dbapi_module).__name__}) has 'cursor' but "
+                f"no 'OperationalError'; second positional "
+                f"({type(inner_conn).__name__}) has "
+                f"'OperationalError' but no 'cursor'. Reference "
+                f"shape: AsyncAdaptedConnection(dbapi, connection)."
+            )
         # ``_connection`` is the concrete ``dqlitedbapi.aio.AsyncConnection``
         # this adapter wraps; SQLAlchemy's parent ``AdaptedConnection``
         # declares the attribute with a wider Protocol type, so we keep
@@ -1321,6 +1387,24 @@ class AsyncAdaptedConnection(AdaptedConnection):
             # raises from the matched hop; if no hop matches, falls
             # through to the wrap below.
             _remap_loop_state_runtime_error(remainder)
+            # Single-child remainder unwrap: a ``TaskGroup`` /
+            # ``anyio.create_task_group`` wrapping ONE inner SQL
+            # operation produces a group-of-one whose only child is
+            # the original ``IntegrityError`` / ``DataError`` /
+            # ``ProgrammingError`` / etc. Unconditionally wrapping
+            # the remainder as ``OperationalError(code=None)`` would
+            # silently lose the original class identity — user
+            # ``except IntegrityError`` clauses miss the rewritten
+            # exception and ``is_disconnect``'s substring scan runs
+            # on an aggregate message that isn't a wire fault. The
+            # group-of-one case is structurally byte-equivalent to
+            # the non-group path; dispatch through the same shape.
+            # ``raise child from remainder`` preserves the group on
+            # ``__cause__`` so SA's ``_walk_cause_chain`` still finds
+            # the structured-concurrency context if it needs to.
+            if len(remainder.exceptions) == 1:
+                child = remainder.exceptions[0]
+                raise child from remainder
             child_classes = {type(c).__name__ for c in remainder.exceptions}
             raise OperationalError(
                 f"aggregate {type(remainder).__name__} with "
@@ -1460,8 +1544,17 @@ class AsyncAdaptedConnection(AdaptedConnection):
                     # leak bare ``RuntimeError`` past
                     # ``engine.dispose()``.
                     msg_lower = str(exc).lower()
+                    # Use ``if / elif / else`` (not sequential
+                    # ``if``s) so the mutual-exclusion contract is
+                    # structural rather than dependent on
+                    # ``_handle_exception``'s ``NoReturn`` annotation
+                    # (which has no runtime enforcement). A future
+                    # refactor that breaks the NoReturn invariant —
+                    # or a contributor adding a fourth substring arm
+                    # — cannot accidentally fall through to the
+                    # trailing ``raise``.
                     if "different loop" in msg_lower or "different event loop" in msg_lower:
-                        self._handle_exception(exc)
+                        self._handle_exception(exc)  # NoReturn
                     # ``RuntimeError("Event loop is closed")`` lands
                     # here during ``engine.dispose()`` after a per-call
                     # ``asyncio.run()`` finished and tore the loop down
@@ -1472,7 +1565,7 @@ class AsyncAdaptedConnection(AdaptedConnection):
                     # try/finally still runs the proxy swap on this
                     # return path. The debug log preserves the
                     # traceback for triage.
-                    if "event loop is closed" in msg_lower:
+                    elif "event loop is closed" in msg_lower:
                         peer = _log_safe_peer(self._connection)
                         logger.debug(
                             "AsyncAdaptedConnection.close (id=%s, peer=%s): "
@@ -1494,10 +1587,11 @@ class AsyncAdaptedConnection(AdaptedConnection):
                     # the close-arm matches that discipline rather than
                     # leaking a bare ``RuntimeError`` past
                     # ``engine.dispose()``.
-                    if "loop is already running" in msg_lower:
-                        self._handle_exception(exc)
-                    # Other RuntimeErrors (programmer bugs) propagate.
-                    raise
+                    elif "loop is already running" in msg_lower:
+                        self._handle_exception(exc)  # NoReturn
+                    else:
+                        # Other RuntimeErrors (programmer bugs) propagate.
+                        raise
                 # The non-greenlet path is handled by the
                 # ``in_greenlet()`` preflight at the top of ``close()``;
                 # ``MissingGreenlet`` cannot land here.
@@ -1613,18 +1707,25 @@ class AsyncAdaptedConnection(AdaptedConnection):
         on a single supported method instead of walking three layers
         of private attributes.
 
-        Idempotent. Absorbs every ``Exception`` and
-        ``asyncio.CancelledError`` from the hook call — a missing
-        hook (older dbapi version), a dead ``weakref.proxy``
-        ``ReferenceError`` (the post-``_release_inner_strong_ref``
-        state), or a writer.close() failure is silently swallowed
-        and logged. Does NOT catch ``BaseException`` shapes that
-        signal cooperative interpreter shutdown —
-        ``KeyboardInterrupt`` and ``SystemExit`` (and any other
-        non-``Exception`` ``BaseException``) propagate so a
-        signal-handler-driven ``engine.dispose()`` cannot mask
-        them. Mirrors the discipline ``DqliteDialect.do_terminate``
-        documents at ``base.py``.
+        Idempotent. Absorbs every ``Exception`` from the hook call
+        — a missing hook (older dbapi version), a dead
+        ``weakref.proxy`` ``ReferenceError`` (the post-
+        ``_release_inner_strong_ref`` state), or a writer.close()
+        failure is silently swallowed and logged. Does NOT catch
+        ``asyncio.CancelledError`` (a ``BaseException`` subclass
+        since 3.8): asyncio's structured-concurrency contract
+        requires the cancel signal to reach the parent
+        ``TaskGroup`` / ``asyncio.timeout`` so the parent's wait
+        completes with cancelled status. Callers that need to run
+        the force-close on a cancel path catch ``CancelledError``
+        themselves and re-raise after invoking this helper (see the
+        close-arm at the ``except asyncio.CancelledError`` site and
+        the terminate-arm's symmetric handler). Also does NOT catch
+        ``KeyboardInterrupt`` / ``SystemExit`` (and any other
+        non-``Exception`` ``BaseException``) so a signal-handler-
+        driven ``engine.dispose()`` cannot mask them. Mirrors the
+        discipline ``DqliteDialect.do_terminate`` documents at
+        ``base.py``.
 
         The two ``getattr`` reads on ``self._connection`` sit
         INSIDE the try frame so a ``ReferenceError`` from a dead
@@ -1659,13 +1760,21 @@ class AsyncAdaptedConnection(AdaptedConnection):
                 id(self),
                 peer,
             )
-        except (Exception, asyncio.CancelledError) as exc:  # pragma: no cover - defensive
-            # Narrow to ``(Exception, asyncio.CancelledError)`` so a
-            # greenlet-level cancel from SA's pool-dispose path is
-            # still absorbed (``CancelledError`` is a ``BaseException``
-            # subclass since 3.8) but ``KeyboardInterrupt`` /
-            # ``SystemExit`` propagate. Mirrors the sibling cursor-
-            # close discipline upstream in this module.
+        except Exception as exc:  # pragma: no cover - defensive
+            # Narrow to ``Exception`` only — ``asyncio.CancelledError``
+            # (a ``BaseException`` subclass since 3.8) must propagate
+            # so an outer ``asyncio.TaskGroup`` / ``asyncio.timeout``
+            # / ``anyio.create_task_group`` parent that issued the
+            # cancel sees the child complete with cancelled status.
+            # Absorbing the cancel here would leave the parent
+            # waiting indefinitely on its ``__aexit__`` for a
+            # cancel-acknowledgement that never arrives. The
+            # close-arm and terminate-arm call sites catch
+            # ``CancelledError`` externally, invoke this helper, and
+            # then re-raise — that pattern preserves the cancel
+            # without requiring this helper to swallow it.
+            # ``KeyboardInterrupt`` / ``SystemExit`` propagate by the
+            # same ``BaseException`` rule.
             logger.debug(
                 "AsyncAdaptedConnection._force_close_transport (id=%s, peer=%s): "
                 "best-effort sync close raised (%s); ignoring",
@@ -1861,20 +1970,23 @@ class DqliteDialect_aio(DqliteDialect):
         is deliberately NOT caught — asyncio's structured-concurrency
         contract says cancels must propagate, and an outer cancel
         signalling "abort dispose now" must not be silently swallowed.
+
+        Two-tier catch (mirrors the sync sibling):
+
+        * ``_FORCE_CLOSE_TAIL_EXCEPTIONS`` — expected transport-class
+          shapes. DEBUG-log + absorb.
+        * Any other ``Exception`` — most likely a cross-repo dbapi
+          refactor regression. WARNING-log + absorb so the SA contract
+          holds while the regression stays loudly observable.
         """
         peer = _log_safe_peer(dbapi_connection)
         try:
             dbapi_connection.terminate()
         except _FORCE_CLOSE_TAIL_EXCEPTIONS:
-            # Narrow tuple: covers every transport-class shape so the
-            # has_terminate=True non-raising contract holds for real
-            # transport failures (OSError, dbapi.Error subclasses,
-            # DqliteConnectionError). AttributeError / TypeError from
-            # cross-repo dbapi-package refactor breaks (where
-            # ``terminate()`` is removed or renamed) propagate so the
-            # regression surfaces loudly rather than silent no-op on
-            # every ``engine.dispose()``. Sync sibling at
-            # base.py::do_terminate uses the same tuple.
+            # Expected shapes — DEBUG-log + absorb. Narrow tuple covers
+            # transport-class failures (OSError + dbapi.Error subclasses
+            # + DqliteConnectionError + RuntimeError + ReferenceError)
+            # that ``terminate()`` legitimately surfaces.
             logger.debug(
                 "do_terminate: terminate raised on dispose for peer=%s id=%s; "
                 "proceeding (has_terminate=True non-raising contract)",
@@ -1882,6 +1994,25 @@ class DqliteDialect_aio(DqliteDialect):
                 id(dbapi_connection),
                 exc_info=True,
             )
+        except Exception:
+            # Unexpected shape — most likely a cross-repo dbapi
+            # refactor regression (``terminate`` renamed, removed,
+            # signature-changed, or swapped to a raising property).
+            # SA's ``has_terminate=True`` contract is binary non-
+            # raising; absorbing here prevents the regression from
+            # aborting ``engine.dispose()`` and leaking sibling slots.
+            # WARNING-tier (vs DEBUG) so the regression stays loudly
+            # visible in operator logs. Sync sibling at
+            # base.py::do_terminate uses the same two-tier shape.
+            logger.warning(
+                "do_terminate: terminate raised UNEXPECTED exception type "
+                "on dispose for peer=%s id=%s; SA has_terminate=True "
+                "contract absorbs to prevent dispose abort. Likely a "
+                "dbapi-side refactor regression — investigate.",
+                peer,
+                id(dbapi_connection),
+                exc_info=True,
+            )
 
     def do_ping(self, dbapi_connection: Any) -> bool:
         """Async-side bespoke ping.
@@ -1978,6 +2109,22 @@ class DqliteDialect_aio(DqliteDialect):
         # and SA's ``_handle_dbapi_exception`` see a clean
         # ``dbapi.Error``.
         if type(dbapi_connection._connection) in weakref.ProxyTypes:
+            # Diagnostic: SA's pool sees this raise as a ping failure
+            # and retires the slot silently. Without a DEBUG line a
+            # flapping pool's root cause (sibling task closed the
+            # adapter between pool checkout and ping, GC sweep,
+            # engine.dispose race) is invisible to log analysis.
+            # Sibling close()/terminate()/transport-class arms in this
+            # module emit DEBUG signal on analogous slot-retirement
+            # transitions; mirror that discipline here.
+            logger.debug(
+                "_async_ping: adapter already closed (id=%s); reporting "
+                "ping failure so SA pool retires the slot. Likely a "
+                "sibling task closed the adapter between pool checkout "
+                "and ping (GC sweep, engine.dispose race, parallel "
+                "task close).",
+                id(dbapi_connection),
+            )
             raise InterfaceError(f"Connection is closed (id={id(dbapi_connection)})")
         try:
             cur = dbapi_connection._connection.cursor()
@@ -2181,11 +2328,17 @@ class DqliteDialect_aio(DqliteDialect):
         # ``RuntimeWarning: coroutine '...' was never awaited``.
         # Surface the misuse with ``ArgumentError`` at connect time so
         # the diagnostic points at the configuration site.
-        # ``inspect.iscoroutinefunction`` on Python 3.12+ recognises
+        # ``inspect.iscoroutinefunction`` recognises
         # ``functools.partial`` wrappers around an ``async def`` (a
-        # legitimate user pattern). The check mirrors SA's overall
-        # trust-the-creator discipline while catching the single most
-        # common user mistake.
+        # legitimate user pattern). That unwrap behaviour was added in
+        # CPython 3.12 (cpython#101174). The project's
+        # ``pyproject.toml`` pins ``requires-python = ">=3.13"`` so
+        # the partial-detection path is structurally guaranteed; any
+        # future relaxation of the requires-python floor below 3.12
+        # would silently leave the partial-wrapper case undetected
+        # and must re-evaluate this gate. The check mirrors SA's
+        # overall trust-the-creator discipline while catching the
+        # single most common user mistake.
         if creator_fn is not None and not callable(creator_fn):
             raise ArgumentError(
                 f"async_creator_fn must be callable; got "