Narrow encode_value / decode_value types and accept bytes-like in inference

Introduce two PEP 695 type aliases at the top of types.py — WireInput
(bool|int|float|str|bytes|bytearray|memoryview|None) for the encoder
input set, and WireValue (bool|int|float|str|bytes|None) for the
decoder output set — and use them to narrow the previously-Any
signatures of encode_value and decode_value. The encoder's type
inference now maps bytearray and memoryview to BLOB the way the
explicit BLOB branch already did (and the way stdlib sqlite3 does),
so zero-copy or mutation-built payloads no longer hit EncodeError on
pure inference paths. The decoder keeps producing plain bytes, so
WireValue is intentionally narrower than WireInput.

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

Author: antoineleclair

src/dqlitewire/types.py

@@ -11,11 +11,24 @@
 """
 
 import struct
-from typing import Any
 
 from dqlitewire.constants import WORD_SIZE, ValueType
 from dqlitewire.exceptions import DecodeError, EncodeError
 
+# Exact set of Python types ``encode_value`` accepts. Callers see a
+# type-checker error if they pass something else, instead of a runtime
+# EncodeError at the first wire round-trip. ``bytes``-like siblings
+# (``bytearray``, ``memoryview``) are accepted because the BLOB encoder
+# normalises them through ``bytes(value)``; the inference path maps
+# them to ValueType.BLOB for the same reason stdlib ``sqlite3`` does.
+type WireInput = bool | int | float | str | bytes | bytearray | memoryview | None
+
+# Exact set of Python types ``decode_value`` may return (first element
+# of the ``(value, consumed)`` tuple). Narrower than ``Any`` — wire
+# values are always one of these primitives, and the driver layer
+# widens to ``Any`` only at the PEP 249 row-tuple boundary.
+type WireValue = bool | int | float | str | bytes | None
+
 # Per-BLOB byte cap. The overall frame-size cap in ``buffer.py`` (64 MiB)
 # already bounds any single message, but a hostile or buggy peer can
 # otherwise pack a single BLOB field that consumes the whole frame. The
@@ -258,7 +271,7 @@ def decode_blob(data: bytes | memoryview) -> tuple[bytes, int]:
     return bytes(data[8 : 8 + length]), total_size
 
 
-def encode_value(value: Any, value_type: ValueType | None = None) -> tuple[bytes, ValueType]:
+def encode_value(value: WireInput, value_type: ValueType | None = None) -> tuple[bytes, ValueType]:
     """Encode a Python value to wire format.
 
     If value_type is not provided, it's inferred from the Python type.
@@ -281,14 +294,19 @@ def encode_value(value: Any, value_type: ValueType | None = None) -> tuple[bytes
             value_type = ValueType.FLOAT
         elif isinstance(value, str):
             value_type = ValueType.TEXT
-        elif isinstance(value, bytes):
+        elif isinstance(value, (bytes, bytearray, memoryview)):
+            # Parity with the explicit BLOB branch and with stdlib
+            # ``sqlite3``: all three bytes-like types infer to BLOB.
+            # Callers building payloads via mutation (bytearray) or
+            # zero-copy slicing (memoryview) no longer need to wrap
+            # values in ``bytes(...)`` before passing them here.
             value_type = ValueType.BLOB
         else:
             raise EncodeError(
                 f"Cannot infer wire type for value of type {type(value).__name__!r}. "
-                f"The wire codec only accepts bool, int, float, str, bytes, or None. "
-                f"Callers passing datetime/date/etc. must convert to str (for ISO8601) "
-                f"or int (for UNIXTIME) at the driver layer."
+                f"The wire codec only accepts bool, int, float, str, bytes-like, "
+                f"or None. Callers passing datetime/date/etc. must convert to str "
+                f"(for ISO8601) or int (for UNIXTIME) at the driver layer."
             )
 
     if value_type == ValueType.BOOLEAN:
@@ -351,7 +369,7 @@ def encode_value(value: Any, value_type: ValueType | None = None) -> tuple[bytes
         raise EncodeError(f"Unknown value type: {value_type}")
 
 
-def decode_value(data: bytes | memoryview, value_type: ValueType) -> tuple[Any, int]:
+def decode_value(data: bytes | memoryview, value_type: ValueType) -> tuple[WireValue, int]:
     """Decode a value from wire format.
 
     Returns (value, bytes_consumed).

tests/test_types.py

@@ -701,6 +701,21 @@ def test_encode_value_blob_accepts_memoryview(self) -> None:
         decoded, _ = decode_value(encoded, ValueType.BLOB)
         assert decoded == b"\x03\x04"
 
+    def test_encode_value_infers_blob_from_bytearray(self) -> None:
+        """Inference path must accept every bytes-like the explicit BLOB
+        branch accepts, otherwise zero-copy / mutation-built payloads
+        hit EncodeError on pure inference paths."""
+        encoded, vtype = encode_value(bytearray(b"\x01\x02\x03"))
+        assert vtype == ValueType.BLOB
+        decoded, _ = decode_value(encoded, ValueType.BLOB)
+        assert decoded == b"\x01\x02\x03"
+
+    def test_encode_value_infers_blob_from_memoryview(self) -> None:
+        encoded, vtype = encode_value(memoryview(b"\x04\x05\x06\x07"))
+        assert vtype == ValueType.BLOB
+        decoded, _ = decode_value(encoded, ValueType.BLOB)
+        assert decoded == b"\x04\x05\x06\x07"
+
     def test_decode_int64_short_data(self) -> None:
         with pytest.raises(DecodeError):
             decode_int64(b"\x00" * 7)
@@ -823,3 +838,66 @@ def __index__(self) -> int:
 
         with pytest.raises(EncodeError, match="Cannot infer wire type"):
             encode_value(OnlyIndex())
+
+
+class TestWireTypeAliases:
+    """Pin the public WireInput / WireValue type aliases so an
+    accidental widening to ``Any`` or narrowing that drops a supported
+    runtime type is caught by the test suite.
+    """
+
+    def test_wire_input_matches_runtime_accepted_types(self) -> None:
+        """WireInput is the documented set of types ``encode_value``
+        accepts. Drift it and a downstream caller would believe their
+        bound parameter is acceptable when it isn't (or vice-versa).
+        """
+        import typing
+
+        from dqlitewire.types import WireInput
+
+        # PEP 695 ``type X = Union`` produces a TypeAliasType; the
+        # underlying union is reachable via ``__value__``.
+        expected_members = {
+            bool,
+            int,
+            float,
+            str,
+            bytes,
+            bytearray,
+            memoryview,
+            type(None),
+        }
+        assert set(typing.get_args(WireInput.__value__)) == expected_members
+
+    def test_encode_value_parameter_is_wire_input(self) -> None:
+        import typing
+
+        from dqlitewire.types import WireInput, encode_value
+
+        hints = typing.get_type_hints(encode_value)
+        assert hints["value"] is WireInput
+
+    def test_wire_value_matches_runtime_decoded_types(self) -> None:
+        """WireValue is the union of possible first-element returns of
+        ``decode_value``. The decoder never produces bytearray/memoryview
+        (it always returns ``bytes``), so this alias is narrower than
+        WireInput.
+        """
+        import typing
+
+        from dqlitewire.types import WireValue
+
+        expected_members = {bool, int, float, str, bytes, type(None)}
+        assert set(typing.get_args(WireValue.__value__)) == expected_members
+
+    def test_decode_value_return_is_wire_value(self) -> None:
+        import typing
+
+        from dqlitewire.types import WireValue, decode_value
+
+        hints = typing.get_type_hints(decode_value)
+        # Return is tuple[WireValue, int] — verify the first arg is
+        # exactly the alias (identity), not a structural copy.
+        return_args = typing.get_args(hints["return"])
+        assert return_args[0] is WireValue
+        assert return_args[1] is int