fix(connection): validate settings in the setter and keep one timeout value

set_query_timeout() and set_max_threads_for_exec() now check the value
before queueing it: an integer (TypeError otherwise) between 0 and
2**64 - 1 (ValueError otherwise). Only the native call is deferred to the
next query. Before, a bad value surfaced on the next execute() on the
pybind backend (TypeError from the uint64 conversion), and the C-API
backend wrapped negative values into huge ones. Negative values now raise
ValueError on both backends.

The connection no longer keeps its own copy of the timeout: the C-API
short-circuit reads the backend connection's value, which is set when the
native setter runs, so both backends see the timeout from the same point.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: 2 people

src_py/connection.py

@@ -4,6 +4,7 @@
 import functools
 import inspect
 import json
+import operator
 import re
 import threading
 import uuid
@@ -385,6 +386,15 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
     return wrapper
 
 
+def _setting_value(name: str, value: int) -> int:
+    """Validate a connection setting before it is queued; the engine takes a uint64."""
+    value = operator.index(value)
+    if not 0 <= value < 2**64:
+        msg = f"{name} must be between 0 and 2**64 - 1; found {value}."
+        raise ValueError(msg)
+    return value
+
+
 class Connection:
     """Connection to a database."""
 
@@ -410,7 +420,6 @@ def __init__(self, database: Database, num_threads: int = 0):
         self._calls = threading.Condition()
         self._calls_in_flight = 0
         self._prefer_pybind = False
-        self._query_timeout_ms = 0
         # Native setter name -> value, applied before the next query.
         self._pending_settings: dict[str, int] = {}
         self._pending_settings_lock = threading.Lock()
@@ -474,12 +483,21 @@ def set_max_threads_for_exec(self, num_threads: int) -> None:
         Parameters
         ----------
         num_threads : int
-            Maximum number of threads to use for executing queries.
+            Maximum number of threads to use for executing queries; 0 uses the
+            database's limit.
+
+        Raises
+        ------
+        TypeError
+            If `num_threads` is not an integer.
+        ValueError
+            If `num_threads` is negative or does not fit in 64 bits.
 
         """
+        num_threads = _setting_value("num_threads", num_threads)
         self.init_connection()
         with self._pending_settings_lock:
-            self._pending_settings["set_max_threads_for_exec"] = int(num_threads)
+            self._pending_settings["set_max_threads_for_exec"] = num_threads
 
     def _apply_pending_settings(self) -> None:
         # The engine applies settings under the lock a running query holds, so
@@ -1005,7 +1023,7 @@ def execute(
 
         if (
             not self._using_pybind_backend()
-            and self._query_timeout_ms > 0
+            and self._connection._query_timeout_ms > 0
             and isinstance(query, str)
             and len(re.findall(r"(?i)\bUNWIND\s+RANGE\s*\(", query)) >= 2
         ):
@@ -1213,11 +1231,18 @@ def set_query_timeout(self, timeout_in_ms: int) -> None:
         timeout_in_ms : int
             query timeout value in ms for executing queries.
 
+        Raises
+        ------
+        TypeError
+            If `timeout_in_ms` is not an integer.
+        ValueError
+            If `timeout_in_ms` is negative or does not fit in 64 bits.
+
         """
+        timeout_in_ms = _setting_value("timeout_in_ms", timeout_in_ms)
         self.init_connection()
-        self._query_timeout_ms = int(timeout_in_ms)
         with self._pending_settings_lock:
-            self._pending_settings["set_query_timeout"] = self._query_timeout_ms
+            self._pending_settings["set_query_timeout"] = timeout_in_ms
 
     def interrupt(self) -> None:
         """

test/test_timeout.py

@@ -80,3 +80,25 @@ def test_applying_settings_lets_other_threads_run(conn: lb.Connection) -> None:
     elapsed = time.monotonic() - started
     _interrupt_until_done(conn, running, waiting)
     assert elapsed < 1, elapsed
+
+
+@pytest.mark.parametrize("setter", ["set_query_timeout", "set_max_threads_for_exec"])
+@pytest.mark.parametrize(
+    ("value", "error"),
+    [("1", TypeError), (1.5, TypeError), (-1, ValueError), (2**64, ValueError)],
+)
+def test_settings_reject_invalid_values_at_once(
+    conn: lb.Connection, setter: str, value: object, error: type[Exception]
+) -> None:
+    with pytest.raises(error):
+        getattr(conn, setter)(value)
+    assert conn.execute("RETURN 1").get_all() == [[1]]
+
+
+def test_cleared_timeout_applies_to_next_query(conn: lb.Connection) -> None:
+    query = "UNWIND range(1, 10) AS x UNWIND range(1, 10) AS y RETURN count(*)"
+    conn.set_query_timeout(1000)
+    with contextlib.suppress(RuntimeError):
+        conn.execute(query)
+    conn.set_query_timeout(0)
+    assert conn.execute(query).get_all() == [[100]]