Annotate module-level constants in dqliteclient as Final / ClassVar

Per PEP 591, immutable module-level constants should be annotated as
Final and class-level singletons as ClassVar. The dqliteclient
package had bare assignments throughout; mypy treated them as
mutable.

Touch:
  - connection.py: _TRANSACTION_{BEGIN,COMMIT,ROLLBACK}_SQL,
    _BARE_IDENT_{FIRST,REST}, _RAFT_BUSY_MESSAGE_FRAGMENTS
  - exceptions.py: _MAX_DISPLAY_MESSAGE on OperationalError (ClassVar)
  - cluster.py: _DEFAULT_CONNECT_MAX_ATTEMPTS, _MAX_ERROR_MESSAGE_SNIPPET,
    _LEADER_PROBE_DRAIN_TIMEOUT_SECONDS, _cluster_random
  - pool.py: _POOL_CLEANUP_EXCEPTIONS
  - protocol.py: _READ_CHUNK_SIZE, _HEARTBEAT_READ_TIMEOUT_CAP_SECONDS

No runtime behavior change. Tests and mypy clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: antoineleclair

src/dqliteclient/cluster.py

@@ -5,6 +5,7 @@
 import logging
 import random
 from collections.abc import Callable, Iterable
+from typing import Final
 
 from dqliteclient.connection import DqliteConnection, _parse_address, _validate_timeout
 from dqliteclient.exceptions import (
@@ -39,27 +40,27 @@
 # hiding genuine cluster instability under what looks like "a slow
 # connect". Operators can override via ClusterClient.connect(
 # max_attempts=...).
-_DEFAULT_CONNECT_MAX_ATTEMPTS = 3
+_DEFAULT_CONNECT_MAX_ATTEMPTS: Final[int] = 3
 
 # Cap per-node error messages at this length before concatenating them
 # into the final ClusterError. A failing peer that returns a multi-MB
 # FailureResponse message would otherwise produce an O(N * M) string
 # held in memory and serialised into every traceback.
-_MAX_ERROR_MESSAGE_SNIPPET = 200
+_MAX_ERROR_MESSAGE_SNIPPET: Final[int] = 200
 
 # Use OS-entropy randomness for the per-sweep node shuffle so that the
 # stampede-avoidance is not defeated by a downstream call to
 # ``random.seed(...)``. Test suites and some libraries seed the global
 # PRNG for determinism; if we used ``random.shuffle`` directly, every
 # process picking up that seed would produce the same shuffle and pile
 # onto the same node. ``SystemRandom`` ignores ``random.seed()``.
-_cluster_random = random.SystemRandom()
+_cluster_random: Final[random.Random] = random.SystemRandom()
 
 # Budget for the bounded writer-drain in ``_query_leader``. A
 # responsive peer drains FIN/ACK in microseconds; a slow peer must not
 # hold up leader discovery. 100 ms is generous for LAN and still
 # negligible against the per-probe ``self._timeout`` (typically seconds).
-_LEADER_PROBE_DRAIN_TIMEOUT_SECONDS = 0.1
+_LEADER_PROBE_DRAIN_TIMEOUT_SECONDS: Final[float] = 0.1
 
 
 def _addr_equiv(a: str, b: str) -> bool:

src/dqliteclient/connection.py

@@ -10,7 +10,7 @@
 from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
 from contextlib import asynccontextmanager
 from types import TracebackType
-from typing import Any
+from typing import Any, Final
 
 from dqliteclient.exceptions import (
     DataError,
@@ -43,16 +43,16 @@
 # and Go peer clients which also emit a bare ``BEGIN``. The constant
 # pins the literal so a refactor can't silently upgrade to ``BEGIN
 # IMMEDIATE`` without showing up in review.
-_TRANSACTION_BEGIN_SQL = "BEGIN"
+_TRANSACTION_BEGIN_SQL: Final[str] = "BEGIN"
 
 # ``COMMIT`` and ``ROLLBACK`` literals are pinned for the same reason as
 # ``_TRANSACTION_BEGIN_SQL``: a refactor must not silently switch to a
 # vendor-qualified form (``COMMIT TRANSACTION``) or a savepoint variant.
 # Consistency between ``transaction()`` and the pool's reset-on-return
 # path is a correctness invariant — if they diverge, a connection could
 # be returned to the pool with a still-open server-side transaction.
-_TRANSACTION_COMMIT_SQL = "COMMIT"
-_TRANSACTION_ROLLBACK_SQL = "ROLLBACK"
+_TRANSACTION_COMMIT_SQL: Final[str] = "COMMIT"
+_TRANSACTION_ROLLBACK_SQL: Final[str] = "ROLLBACK"
 
 # ``_TX_AUTO_ROLLBACK_PRIMARY_CODES`` is imported above from ``dqlitewire``
 # (canonical home for SQLite-side constants). It contains the primary
@@ -78,8 +78,8 @@
 # a fresh transaction whose boundary the user code does not know about.
 
 
-_BARE_IDENT_FIRST = frozenset(string.ascii_letters + "_")
-_BARE_IDENT_REST = frozenset(string.ascii_letters + string.digits + "_")
+_BARE_IDENT_FIRST: Final[frozenset[str]] = frozenset(string.ascii_letters + "_")
+_BARE_IDENT_REST: Final[frozenset[str]] = frozenset(string.ascii_letters + string.digits + "_")
 
 # Coupled to dqlite-upstream/src/gateway.c failure() emissions for the
 # Raft-side BUSY path that means "the in-flight write was not accepted;
@@ -90,7 +90,7 @@
 # the matcher here keeps the upstream-coupling explicit so a future
 # rewording (or addition of a new Raft-BUSY message) is one-line update
 # rather than a hunt through the classifier.
-_RAFT_BUSY_MESSAGE_FRAGMENTS: tuple[str, ...] = ("checkpoint in progress",)
+_RAFT_BUSY_MESSAGE_FRAGMENTS: Final[tuple[str, ...]] = ("checkpoint in progress",)
 
 
 def _is_keyword_boundary(s: str, kw_len: int) -> bool:

src/dqliteclient/exceptions.py

@@ -1,5 +1,7 @@
 """Exceptions for dqlite client."""
 
+from typing import ClassVar
+
 from dqlitewire.exceptions import ProtocolError as _WireProtocolError
 
 __all__ = [
@@ -81,7 +83,7 @@ class OperationalError(DqliteError):
     ``super().__init__`` keeps the raw payload on ``self.args``.
     """
 
-    _MAX_DISPLAY_MESSAGE = 1024
+    _MAX_DISPLAY_MESSAGE: ClassVar[int] = 1024
 
     code: int
     message: str

src/dqliteclient/pool.py

@@ -6,7 +6,7 @@
 from collections.abc import AsyncIterator, Sequence
 from contextlib import asynccontextmanager
 from types import TracebackType
-from typing import Any
+from typing import Any, Final
 
 from dqliteclient.cluster import ClusterClient
 from dqliteclient.connection import (
@@ -53,7 +53,7 @@
 # ``_check_in_use`` raise ``InterfaceError("owned by another task")``.
 # That should drop the connection, not crash the pool's release path
 # (which would leak a ``_size`` slot and eventually wedge the pool).
-_POOL_CLEANUP_EXCEPTIONS = (
+_POOL_CLEANUP_EXCEPTIONS: Final[tuple[type[BaseException], ...]] = (
     OSError,
     DqliteConnectionError,
     ProtocolError,

src/dqliteclient/protocol.py

@@ -5,7 +5,7 @@
 import secrets
 import sys
 from collections.abc import Sequence
-from typing import Any
+from typing import Any, Final
 
 from dqliteclient.exceptions import DqliteConnectionError, OperationalError, ProtocolError
 from dqlitewire import (
@@ -47,7 +47,7 @@
 
 # Socket read buffer size. 4 KiB balances syscall overhead for typical
 # request/response payloads against latency for small wire messages.
-_READ_CHUNK_SIZE = 4096
+_READ_CHUNK_SIZE: Final[int] = 4096
 
 # Upper bound on how wide a server's advertised heartbeat can stretch
 # the per-read deadline on a connection that opted into
@@ -60,7 +60,7 @@
 # ``trust_server_heartbeat`` docstrings at protocol.py:82 and :106,
 # connection.py:__init__ docstring, and the top-level ``connect`` /
 # ``create_pool`` docstrings in ``__init__.py``.
-_HEARTBEAT_READ_TIMEOUT_CAP_SECONDS = 300.0
+_HEARTBEAT_READ_TIMEOUT_CAP_SECONDS: Final[float] = 300.0
 
 
 def _failure_message(message: str, addr_suffix: str) -> str: