sqlalchemy-dqlite 0.3.0__tar.gz → 0.4.0__tar.gz

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sqlalchemy-dqlite
-Version: 0.3.0
+Version: 0.4.0
 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.4.0,>=0.3.0
-Requires-Dist: dqlite-dbapi<0.4.0,>=0.3.0
-Requires-Dist: dqlite-wire<0.4.0,>=0.3.0
+Requires-Dist: dqlite-client<0.5.0,>=0.4.0
+Requires-Dist: dqlite-dbapi<0.5.0,>=0.4.0
+Requires-Dist: dqlite-wire<0.5.0,>=0.4.0
 Requires-Dist: sqlalchemy<3.0,>=2.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/docs/transactions.md

@@ -24,6 +24,24 @@ with engine.begin() as conn:
 The same applies to `engine.connect()`: SQLAlchemy auto-begins on the first
 execute, so a user-issued `text("BEGIN")` collides the same way.
 
+## Session modes
+
+The dialect emits a bare `BEGIN`; the dbapi qualifies it according to the
+connection's session mode (`BEGIN IMMEDIATE` by default, so a read-then-write
+block cannot lose its snapshot to a concurrent writer). The engine-wide default
+comes from the `session_mode` connect argument (`?session_mode=` in the URL or
+`connect_args`); a per-connection override is the `dqlite_session_mode`
+execution option:
+
+```python
+with engine.connect().execution_options(dqlite_session_mode="read_only") as conn:
+    conn.execute(text("SELECT ..."))          # writes raise OperationalError here
+```
+
+Accepted values are `immediate`, `deferred`, `exclusive`, and `read_only`.
+The option is transactional: it cannot be changed inside an open transaction,
+and the pool restores the connect-time default on checkin.
+
 ## No `AUTOCOMMIT`
 
 `isolation_level="AUTOCOMMIT"` is rejected. Every dqlite statement goes

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlalchemy-dqlite"
-version = "0.3.0"
+version = "0.4.0"
 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.3.0,<0.4.0",
+    "dqlite-dbapi>=0.4.0,<0.5.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.3.0,<0.4.0",
-    "dqlite-wire>=0.3.0,<0.4.0",
+    "dqlite-client>=0.4.0,<0.5.0",
+    "dqlite-wire>=0.4.0,<0.5.0",
     "sqlalchemy>=2.0,<3.0",
 ]
 

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/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.3.0"
+__version__: _Final[str] = "0.4.0"
 
 # SA convention: every shipped dialect package exposes ``<package>.dialect``
 # pointing at the default sync class.

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/src/sqlalchemydqlite/base.py

@@ -18,6 +18,7 @@ from sqlalchemy.engine import characteristics as _sa_characteristics
 from sqlalchemy.engine.interfaces import BindTyping, DBAPIConnection, IsolationLevel
 from sqlalchemy.exc import ArgumentError
 from sqlalchemy.sql.compiler import InsertmanyvaluesSentinelOpts
+from sqlalchemy.util import await_only
 
 import dqliteclient.exceptions as _client_exc
 import dqlitedbapi.exceptions as _dbapi_exc
@@ -357,9 +358,9 @@ class _DqliteDateTime(sqltypes.DateTime):
                         f"DateTime bind: tzinfo {value.tzinfo!r} returned "
                         f"None from utcoffset(); cannot serialise."
                     )
-                from dqlitedbapi.types import _format_utc_offset
+                from dqlitedbapi.types import format_utc_offset
 
-                return base + _format_utc_offset(offset)
+                return base + format_utc_offset(offset)
             return value
 
         return process
@@ -587,9 +588,9 @@ class _DqliteTime(sqltypes.Time):
                         f"returned None from utcoffset(); cannot "
                         f"serialise without a resolvable offset."
                     )
-                from dqlitedbapi.types import _format_utc_offset
+                from dqlitedbapi.types import format_utc_offset
 
-                return base + _format_utc_offset(offset)
+                return base + format_utc_offset(offset)
             return value
 
         return process
@@ -612,9 +613,9 @@ class _DqliteTime(sqltypes.Time):
             offset = value.utcoffset()
             if offset is None:
                 return f"'{base}'"
-            from dqlitedbapi.types import _format_utc_offset
+            from dqlitedbapi.types import format_utc_offset
 
-            return f"'{base + _format_utc_offset(offset)}'"
+            return f"'{base + format_utc_offset(offset)}'"
 
         return process
 
@@ -723,50 +724,28 @@ class DqliteCompiler(SQLiteCompiler):
 class DqliteSessionModeCharacteristic(_sa_characteristics.ConnectionCharacteristic):
     """Per-connection ``dqlite_session_mode`` characteristic.
 
-    Stores the mode on the underlying dqlitedbapi connection (unwrapped via
-    ``_unwrap_dqlite_connection``) so ``do_begin`` and the cursor BEGIN-rewrite
-    see it. ``transactional = True`` so mid-transaction toggles raise. Emits
-    ``PRAGMA query_only = N`` only when crossing the read_only boundary, before
-    updating the live attribute; force-closes the slot if the PRAGMA raises.
+    Delegates to the dbapi connection's ``session_mode`` / ``set_session_mode()``
+    (unwrapped via ``_unwrap_dqlite_connection``), which owns the ``PRAGMA query_only``
+    emission and the BEGIN rewrite. ``transactional = True`` so mid-transaction toggles
+    raise.
     """
 
     transactional: ClassVar[bool] = True
 
     def get_characteristic(self, dialect: Any, dbapi_conn: Any) -> str:
         target = dialect._unwrap_dqlite_connection(dbapi_conn)
-        return getattr(target, "_dqlite_session_mode", "immediate")
+        return str(getattr(target, "session_mode", "immediate"))
 
     def set_characteristic(self, dialect: Any, dbapi_conn: Any, value: Any) -> None:
         target = dialect._unwrap_dqlite_connection(dbapi_conn)
         requested = dialect._validate_dqlite_session_mode(value)
-        current = getattr(target, "_dqlite_session_mode", "immediate")
-        if current == requested:
-            return
-        need_query_only = 1 if requested == "read_only" else 0
-        was_query_only = 1 if current == "read_only" else 0
-        try:
-            if need_query_only != was_query_only:
-                # Emit on the SA-side dbapi cursor (async routes through the
-                # AsyncAdapt cursor under greenlet_spawn).
-                cur = dbapi_conn.cursor()
-                try:
-                    cur.execute(f"PRAGMA query_only = {need_query_only}")
-                finally:
-                    cur.close()
-        except BaseException:
-            # Don't return a poisoned slot to the pool; suppress force-close's own
-            # exceptions so the originating one propagates and SA invalidates.
-            with contextlib.suppress(Exception):
-                target.force_close_transport()
-            raise
-        target._dqlite_session_mode = requested
+        result = target.set_session_mode(requested)
+        if inspect.isawaitable(result):
+            await_only(result)
 
     def reset_characteristic(self, dialect: Any, dbapi_conn: Any) -> None:
-        # SA's reset passes no "before" value; restore the construct-time default
-        # captured once on ``_dqlite_session_mode_default``.
         target = dialect._unwrap_dqlite_connection(dbapi_conn)
-        default = getattr(target, "_dqlite_session_mode_default", "immediate")
-        self.set_characteristic(dialect, dbapi_conn, default)
+        self.set_characteristic(dialect, dbapi_conn, target.default_session_mode)
 
 
 class DqliteDialect(SQLiteDialect_pysqlite):
@@ -1378,36 +1357,18 @@ class DqliteDialect(SQLiteDialect_pysqlite):
     # pipeline which already classifies exceptions): do NOT mirror this raw-cursor
     # shape there.
     def do_begin(self, dbapi_connection: DBAPIConnection) -> None:
-        target = self._unwrap_dqlite_connection(dbapi_connection)
-        # Honour only a known str literal; any other shape (test MagicMock, etc.)
-        # falls back to "immediate" — do_begin is the wrong place to surface misuse
-        # (validation already ran at execution_options time).
-        raw_mode = getattr(target, "_dqlite_session_mode", "immediate")
-        mode = raw_mode.lower() if isinstance(raw_mode, str) and raw_mode else "immediate"
-        if mode in ("deferred", "read_only"):
-            # read_only rides DEFERRED (its PRAGMA query_only blocks writes); emit
-            # the explicit literal so the contract is visible at the SA layer too.
-            begin_sql = "BEGIN DEFERRED"
-        elif mode == "exclusive":
-            begin_sql = "BEGIN EXCLUSIVE"
-        else:
-            # "immediate" and any unknown value: bare BEGIN. The dbapi rewrites to
-            # IMMEDIATE unless its engine-wide default (connect_args session_mode)
-            # is non-immediate, in which case bare BEGIN is sent verbatim.
-            begin_sql = "BEGIN"
+        # pysqlite's parent is a no-op because stdlib auto-BEGINs; dqlite has no
+        # auto-BEGIN, so emit one. The dbapi qualifies it per the connection's
+        # session mode (IMMEDIATE by default).
         cursor = dbapi_connection.cursor()
         try:
-            cursor.execute(begin_sql)
+            cursor.execute("BEGIN")
         finally:
             # Guard close so a transport-class failure doesn't replace the
-            # propagating BEGIN exception (Python's finally-replaces rule) — SA's
-            # wrapping must see the BEGIN error directly, not as __context__.
+            # propagating BEGIN exception (Python's finally-replaces rule).
             try:
                 cursor.close()
             except _FORCE_CLOSE_TAIL_EXCEPTIONS:
-                # Wider tuple (matching do_close) so cross-loop RuntimeError /
-                # dead-proxy ReferenceError don't escape and mask the BEGIN error;
-                # programmer-bug shapes still escape.
                 logger.debug(
                     "do_begin: cursor.close failed after BEGIN; BEGIN exception preserved",
                     exc_info=True,

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/src/sqlalchemydqlite/requirements.py

@@ -384,8 +384,7 @@ class Requirements(SuiteRequirements):
 
     @property
     def fetch_first(self) -> compound:
-        """Closed: SA's compiler emits LIMIT/OFFSET for SQLite, so these tests
-        never actually exercise FETCH FIRST."""
+        """SQLite has no ``FETCH FIRST ... ROWS ONLY`` syntax, only LIMIT/OFFSET."""
         return exclusions.closed()
 
     @property

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/tests/conftest.py

@@ -8,20 +8,6 @@ from pathlib import Path
 import pytest
 
 
-@pytest.fixture(autouse=True)
-def _clear_resolve_leader_cache() -> Iterator[None]:
-    """Clear the process-wide ``_RESOLVE_LEADER_CACHE`` between tests.
-
-    Without this, two SA tests targeting the same (address, governors) via
-    different ClusterClient mocks would share a stale cached instance.
-    """
-    from dqlitedbapi import connection as _conn_mod
-
-    _conn_mod._RESOLVE_LEADER_CACHE.clear()
-    yield
-    _conn_mod._RESOLVE_LEADER_CACHE.clear()
-
-
 @pytest.fixture(autouse=True)
 def _reset_unparseable_iso_warning_gate() -> Iterator[None]:
     """Reset each type-class's one-shot ``_unparseable_iso_warning_emitted``

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/tests/test_adapter_stale_rows.py

@@ -68,7 +68,7 @@ def test_stale_rows_cleared_when_execute_raises(monkeypatch: pytest.MonkeyPatch)
 
     adapter = AsyncAdaptedCursor(conn_adapter)
     # Seed stale state simulating a prior successful execute.
-    adapter.description = [("a", None, None, None, None, None, None)]
+    adapter.description = [("a", 3, None, None, None, None, None)]
     adapter._rows = deque([(1,), (2,)])
     adapter.rowcount = 2
     adapter.lastrowid = 10
@@ -104,7 +104,7 @@ def test_stale_rows_cleared_when_executemany_raises(
     )
 
     adapter = AsyncAdaptedCursor(conn_adapter)  # type: ignore[arg-type]
-    adapter.description = [("a", None, None, None, None, None, None)]
+    adapter.description = [("a", 3, None, None, None, None, None)]
     adapter._rows = deque([(1,)])
     adapter.rowcount = 3
     adapter.lastrowid = 99

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/tests/test_aio_close_suppress_and_soft_close_noop.py

@@ -61,7 +61,7 @@ class TestAsyncAdaptedCursorSoftCloseNoop:
         adapted_conn._connection = underlying
         cur = AsyncAdaptedCursor(adapted_conn)
         cur._rows = deque([(1,), (2,)])
-        cur.description = (("col", None, None, None, None, None, None),)
+        cur.description = (("col", 3, None, None, None, None, None),)
         cur.rowcount = 2
         cur.lastrowid = None
 
@@ -76,5 +76,5 @@ class TestAsyncAdaptedCursorSoftCloseNoop:
         # Cursor state unchanged — soft-close is documentary, not destructive.
         assert cur._rows == deque([(1,), (2,)])
         assert cur.rowcount == 2
-        assert cur.description == (("col", None, None, None, None, None, None),)
+        assert cur.description == (("col", 3, None, None, None, None, None),)
         assert cur._closed is False

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/tests/test_async_creator_fn_noncallable_rejected.py

@@ -11,10 +11,8 @@ from sqlalchemy.exc import ArgumentError
 from sqlalchemydqlite.aio import DqliteDialect_aio
 
 
-@pytest.mark.parametrize("bogus", [42, "string", object(), None, [1, 2]])
+@pytest.mark.parametrize("bogus", [42, "string", object(), [1, 2]])
 def test_async_creator_fn_noncallable_raises_argument_error(bogus: Any) -> None:
-    if bogus is None:
-        pytest.skip("None means 'no creator_fn'; the gate correctly does not raise.")
     dialect = DqliteDialect_aio()
     with pytest.raises(ArgumentError, match="async_creator_fn"):
         dialect.connect(async_creator_fn=bogus)

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/tests/test_async_cursor_closed_guards.py

@@ -33,7 +33,7 @@ def test_executemany_on_closed_cursor_raises() -> None:
 
 def test_close_clears_result_set_but_preserves_rowcount_lastrowid() -> None:
     cur = _make_cursor()
-    cur.description = (("col", None, None, None, None, None, None),)
+    cur.description = (("col", 3, None, None, None, None, None),)
     cur.rowcount = 42
     cur.lastrowid = 7
     cur._rows.append((1,))

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/tests/test_async_executemany_leader_flip_state_reset.py

@@ -80,7 +80,7 @@ class TestAsyncExecutemanyLeaderFlipResetState:
         cur = _make_adapted_cursor(underlying)
 
         # Pre-populate state so the up-front reset is observable.
-        cur.description = [("col", None, None, None, None, None, None)]
+        cur.description = [("col", 3, None, None, None, None, None)]
         cur.rowcount = 99
         cur.lastrowid = 42
         cur._rows.extend([(1,), (2,)])

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/tests/test_detect_autocommit_setting.py

@@ -41,11 +41,11 @@ class TestDetectAutocommitSetting:
         the value SA's probe keys on. Pin the value, not just the descriptor."""
         from dqlitedbapi.connection import Connection as DqliteSyncConnection
 
-        instance_unused = DqliteSyncConnection.__new__(DqliteSyncConnection)
-        # The getter raises InterfaceError on a closed connection; __new__ skips
-        # __init__, so set _closed explicitly to reach the property body.
-        instance_unused._closed = False
-        assert instance_unused.isolation_level is None
+        conn = DqliteSyncConnection("localhost:19001")
+        try:
+            assert conn.isolation_level is None
+        finally:
+            conn.close()
 
     def test_async_dbapi_connection_isolation_level_also_returns_none(self) -> None:
         """Sibling pin on the async surface."""
@@ -53,10 +53,7 @@ class TestDetectAutocommitSetting:
             AsyncConnection as DqliteAsyncConnection,
         )
 
-        instance_unused = DqliteAsyncConnection.__new__(DqliteAsyncConnection)
-        # See sync sibling: _closed must be set before the property fires.
-        instance_unused._closed = False
-        assert instance_unused.isolation_level is None
+        assert DqliteAsyncConnection("localhost:19001").isolation_level is None
 
     def test_override_remains_load_bearing_against_isolation_level_eq_none(self) -> None:
         """The override returns False even when the probe sees isolation_level is None."""

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/tests/test_dialect_dialect_config.py

@@ -287,11 +287,17 @@ class TestURLGovernorsReachAioDbapi:
         )
         _, kwargs = dialect.create_connect_args(url)
         aio_module = DqliteDialect_aio.import_dbapi()
+        # A dropped or renamed knob would raise TypeError here.
         conn = aio_module.connect(**kwargs)
-        assert conn._max_total_rows == 500
-        assert conn._max_continuation_frames == 7
-        assert conn._trust_server_heartbeat is True
-        assert conn._timeout == 5
+        assert conn.max_total_rows == 500
+        assert kwargs == {
+            "address": "host:19001",
+            "database": "db",
+            "timeout": 5.0,
+            "max_total_rows": 500,
+            "max_continuation_frames": 7,
+            "trust_server_heartbeat": True,
+        }
 
 
 class TestDoPingNarrowExceptions:

{sqlalchemy_dqlite-0.3.0 → sqlalchemy_dqlite-0.4.0}/uv.lock

@@ -82,7 +82,7 @@ wheels = [
 
 [[package]]
 name = "dqlite-client"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "../python-dqlite-client" }
 dependencies = [
     { name = "dqlite-wire" },
@@ -104,7 +104,7 @@ provides-extras = ["dev", "yaml-store"]
 
 [[package]]
 name = "dqlite-dbapi"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "../python-dqlite-dbapi" }
 dependencies = [
     { name = "dqlite-client" },
@@ -125,7 +125,7 @@ provides-extras = ["dev"]
 
 [[package]]
 name = "dqlite-wire"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "../python-dqlite-wire" }
 
 [package.metadata]
@@ -413,7 +413,7 @@ wheels = [
 
 [[package]]
 name = "sqlalchemy-dqlite"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "dqlite-client" },