xaeian 0.7.2__tar.gz → 0.7.4__tar.gz

{xaeian-0.7.2 → xaeian-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xaeian
-Version: 0.7.2
+Version: 0.7.4
 Summary: Python utilities for files, strings, time, serial, structs, media, electronics, plotting, and database and more...
 Author: Xaeian
 License: MIT
@@ -29,9 +29,15 @@ Requires-Dist: pypdf; extra == "media"
 Provides-Extra: plot
 Requires-Dist: matplotlib; extra == "plot"
 Requires-Dist: numpy; extra == "plot"
+Provides-Extra: serial
+Requires-Dist: pyserial; extra == "serial"
+Provides-Extra: sftp
+Requires-Dist: paramiko; extra == "sftp"
 Provides-Extra: time
 Requires-Dist: pytz; extra == "time"
 Requires-Dist: tzlocal; extra == "time"
+Provides-Extra: yaml
+Requires-Dist: pyyaml; extra == "yaml"
 Provides-Extra: all
 Requires-Dist: Pillow; extra == "all"
 Requires-Dist: PyMuPDF; extra == "all"
@@ -40,10 +46,13 @@ Requires-Dist: aiosqlite; extra == "all"
 Requires-Dist: asyncpg; extra == "all"
 Requires-Dist: matplotlib; extra == "all"
 Requires-Dist: numpy; extra == "all"
+Requires-Dist: paramiko; extra == "all"
 Requires-Dist: psycopg2-binary; extra == "all"
 Requires-Dist: pymysql; extra == "all"
 Requires-Dist: pypdf; extra == "all"
+Requires-Dist: pyserial; extra == "all"
 Requires-Dist: pytz; extra == "all"
+Requires-Dist: pyyaml; extra == "all"
 Requires-Dist: scipy; extra == "all"
 Requires-Dist: sexpdata; extra == "all"
 Requires-Dist: tzlocal; extra == "all"
@@ -121,12 +130,13 @@ db.find("users", order="name", limit=10)
 async with db.transaction():
   db.update("users", {"verified": True}, "id = ?", 42)
 
-# Serial recorders: threaded read + 1Hz CSV append
-from xaeian.serial import Recorder, RecorderPool
+# Serial recorders: threaded read, latest value via .value
+from xaeian.serial import Recorder
 recs = [Recorder(p, name=n, regex=Recorder.SCI_NORM)
   for n, p in {"U1": "COM7", "I1": "COM8"}.items()]
-pool = RecorderPool(recs, period_ms=1000, csv_path="series.csv")
-pool.start(); ...; pool.stop()
+for r in recs: r.start() # background reader threads
+... # app-side reap loop snapshots r.value (CSV, DB, MQTT)
+for r in recs: r.stop()
 
 # Plot: fluent, stacked panels, auto datetime
 from xaeian.plot import Plot

{xaeian-0.7.2 → xaeian-0.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xaeian"
-version = "0.7.2"
+version = "0.7.4"
 description = "Python utilities for files, strings, time, serial, structs, media, electronics, plotting, and database and more..."
 readme = "readme.md"
 license = {text = "MIT"}
@@ -20,8 +20,11 @@ dsp = ["numpy", "scipy"]
 eda = ["PyMuPDF", "pypdf", "sexpdata"]
 media = ["Pillow", "PyMuPDF", "pypdf"]
 plot = ["matplotlib", "numpy"]
+serial = ["pyserial"]
+sftp = ["paramiko"]
 time = ["pytz", "tzlocal"]
-all = ["Pillow", "PyMuPDF", "aiomysql", "aiosqlite", "asyncpg", "matplotlib", "numpy", "psycopg2-binary", "pymysql", "pypdf", "pytz", "scipy", "sexpdata", "tzlocal"]
+yaml = ["pyyaml"]
+all = ["Pillow", "PyMuPDF", "aiomysql", "aiosqlite", "asyncpg", "matplotlib", "numpy", "paramiko", "psycopg2-binary", "pymysql", "pypdf", "pyserial", "pytz", "pyyaml", "scipy", "sexpdata", "tzlocal"]
 
 [project.scripts]
 xn = "xaeian.__main__:main"
@@ -31,3 +34,7 @@ Repository = "https://github.com/Xaeian/Python"
 
 [tool.setuptools.packages.find]
 include = ["xaeian*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_functions = ["*"]

{xaeian-0.7.2 → xaeian-0.7.4}/readme.md

@@ -71,12 +71,13 @@ db.find("users", order="name", limit=10)
 async with db.transaction():
   db.update("users", {"verified": True}, "id = ?", 42)
 
-# Serial recorders: threaded read + 1Hz CSV append
-from xaeian.serial import Recorder, RecorderPool
+# Serial recorders: threaded read, latest value via .value
+from xaeian.serial import Recorder
 recs = [Recorder(p, name=n, regex=Recorder.SCI_NORM)
   for n, p in {"U1": "COM7", "I1": "COM8"}.items()]
-pool = RecorderPool(recs, period_ms=1000, csv_path="series.csv")
-pool.start(); ...; pool.stop()
+for r in recs: r.start() # background reader threads
+... # app-side reap loop snapshots r.value (CSV, DB, MQTT)
+for r in recs: r.stop()
 
 # Plot: fluent, stacked panels, auto datetime
 from xaeian.plot import Plot

xaeian-0.7.4/tests/test_colors.py

@@ -0,0 +1,17 @@
+# tests/test_colors.py
+
+"""ANSI color codes and pre-formatted level indicators."""
+
+from xaeian import Color, Ico
+
+def color_codes_are_ansi_escape_sequences():
+  assert Color.RED.startswith("\033[") and Color.RED.endswith("m")
+  assert Color.END == "\033[0m"
+
+def ico_wraps_label_in_color_and_reset():
+  assert Ico.ERR == f"{Color.RED}ERR{Color.END}"
+  assert Ico.INF == f"{Color.BLUE}INF{Color.END}"
+  assert Ico.OK == f"{Color.GREEN}OK{Color.END}"
+
+def ico_gap_is_blank_padding():
+  assert Ico.GAP == "   " and Ico.GAP.strip() == ""

xaeian-0.7.4/tests/test_crc.py

@@ -0,0 +1,157 @@
+# tests/test_crc.py
+
+"""CRC checksums: catalog check values, round-trips, framing, parameter effects."""
+
+import zlib
+import pytest
+from xaeian.crc import (
+  CRC, reflect_bit,
+  crc32_iso, crc32_aixm, crc32_autosar, crc32_cksum,
+  crc16_kermit, crc16_modbus, crc16_buypass,
+  crc8_maxim, crc8_smbus,
+)
+
+CHECK = b"123456789" # the standard CRC catalog test vector
+
+#---------------------------------------------------------------------------------- reflect_bit
+
+def reflect_reverses_bit_order():
+  assert reflect_bit(0b1100, 4) == 0b0011
+  assert reflect_bit(0b10000000, 8) == 0b00000001
+
+def reflect_is_its_own_inverse():
+  for value in (0x00, 0x01, 0x80, 0xA5, 0xFF):
+    assert reflect_bit(reflect_bit(value, 8), 8) == value
+
+def reflect_palindrome_is_unchanged():
+  assert reflect_bit(0b1001_1001, 8) == 0b1001_1001
+
+#------------------------------------------------------------------------------- catalog values
+
+# Every predefined instance matched against its published check value for "123456789".
+CATALOG = [
+  (crc32_iso, 0xCBF43926), # standard CRC-32 (Ethernet, ZIP, PNG)
+  (crc32_aixm, 0x3010BF7F),
+  (crc32_autosar, 0x1697D06A),
+  (crc32_cksum, 0x765E7680),
+  (crc16_kermit, 0x2189),
+  (crc16_modbus, 0x374B), # 0x4B37 byte-swapped by invertOut
+  (crc16_buypass, 0xFEE8),
+  (crc8_maxim, 0xA1),
+  (crc8_smbus, 0xF4),
+]
+
+@pytest.mark.parametrize("crc, expected", CATALOG)
+def predefined_matches_catalog_check_value(crc, expected):
+  assert crc.checksum(CHECK) == expected
+
+@pytest.mark.parametrize("crc, _", CATALOG)
+def checksum_is_deterministic(crc, _):
+  assert crc.checksum(CHECK) == crc.checksum(CHECK)
+
+@pytest.mark.parametrize("crc, _", CATALOG)
+def checksum_fits_width(crc, _):
+  assert 0 <= crc.checksum(b"random payload") < (1 << crc.width)
+
+#---------------------------------------------------------------------------- to_bytes / to_int
+
+@pytest.mark.parametrize("crc", [crc8_smbus, crc16_kermit, crc32_iso])
+def bytes_int_round_trip(crc):
+  value = crc.checksum(CHECK)
+  assert crc.to_int(crc.to_bytes(value)) == value
+
+@pytest.mark.parametrize("crc, n", [(crc8_smbus, 1), (crc16_kermit, 2), (crc32_iso, 4)])
+def to_bytes_length_follows_width(crc, n):
+  assert len(crc.to_bytes(crc.checksum(CHECK))) == n
+
+def to_bytes_is_big_endian():
+  assert crc16_kermit.to_bytes(0x1234) == b"\x12\x34"
+  assert crc32_iso.to_bytes(0x01020304) == b"\x01\x02\x03\x04"
+
+def to_int_rejects_unsupported_width():
+  odd = CRC(8, 0x07, 0x00, False, False, 0x00, False)
+  odd.width = 24 # force an unsupported width past the constructor
+  with pytest.raises(ValueError):
+    odd.to_int(b"\x00\x00\x00")
+
+#--------------------------------------------------------------------------------------- encode
+
+def encode_appends_crc_after_message():
+  assert crc16_modbus.encode(b"hello") == b"hello\xf64"
+
+@pytest.mark.parametrize("crc, n", [(crc8_smbus, 1), (crc16_kermit, 2), (crc32_iso, 4)])
+def encode_keeps_message_and_adds_width_bytes(crc, n):
+  msg = b"payload"
+  frame = crc.encode(msg)
+  assert frame[:len(msg)] == msg
+  assert len(frame) == len(msg) + n
+
+#--------------------------------------------------------------------------------------- decode
+
+@pytest.mark.parametrize("crc", [crc8_smbus, crc16_modbus, crc16_kermit, crc32_iso])
+def decode_recovers_encoded_message(crc):
+  for msg in (b"", b"x", b"Hello!", bytes(range(64))):
+    assert crc.decode(crc.encode(msg)) == msg
+
+def decode_rejects_corrupted_payload():
+  frame = crc16_modbus.encode(b"important")
+  corrupt = bytes([frame[0] ^ 0xFF]) + frame[1:]
+  assert crc16_modbus.decode(corrupt) is None
+
+def decode_rejects_corrupted_crc():
+  frame = crc16_modbus.encode(b"important")
+  assert crc16_modbus.decode(frame[:-1] + bytes([frame[-1] ^ 0xFF])) is None
+
+@pytest.mark.parametrize("crc", [crc8_smbus, crc16_kermit, crc32_iso])
+def decode_rejects_frame_shorter_than_crc(crc):
+  assert crc.decode(b"") is None
+  assert crc.decode(b"\x00" * (crc.width // 8 - 1)) is None
+
+#---------------------------------------------------------------------------- parameter effects
+
+def reflect_in_out_change_the_result():
+  plain = CRC(16, 0x8005, 0x0000, False, False, 0x0000, False)
+  reflected = CRC(16, 0x8005, 0x0000, True, True, 0x0000, False)
+  assert plain.checksum(CHECK) != reflected.checksum(CHECK)
+
+def invert_out_byte_swaps_the_crc():
+  # crc16_modbus differs from the same spec without invertOut only by byte order
+  straight = CRC(16, 0x8005, 0xFFFF, True, True, 0x0000, False)
+  assert crc16_modbus.checksum(CHECK) == straight.checksum(CHECK) << 8 & 0xFF00 \
+    | straight.checksum(CHECK) >> 8
+
+def xor_mask_flips_output():
+  no_xor = CRC(16, 0x1021, 0x0000, True, True, 0x0000, False)
+  with_xor = CRC(16, 0x1021, 0x0000, True, True, 0xFFFF, False)
+  assert with_xor.checksum(CHECK) == no_xor.checksum(CHECK) ^ 0xFFFF
+
+def custom_crc_from_docstring_example():
+  crc = CRC(16, 0x8005, 0xFFFF, True, True, 0x0000, False)
+  assert crc.checksum(b"123456789") == 0x4B37
+
+#--------------------------------------------------------------------------- real-world vectors
+
+@pytest.mark.parametrize("data", [b"", b"The quick brown fox", bytes(range(256))])
+def crc32_iso_equals_zlib(data):
+  # crc32_iso is the standard CRC-32 - it must agree with the stdlib bit-for-bit
+  assert crc32_iso.checksum(data) == zlib.crc32(data)
+
+def modbus_rtu_request_frame():
+  # "read 10 holding registers from slave 1" - the canonical Modbus textbook frame
+  request = bytes([0x01, 0x03, 0x00, 0x00, 0x00, 0x0A])
+  assert crc16_modbus.encode(request).hex(" ") == "01 03 00 00 00 0a c5 cd"
+
+def one_wire_rom_checksums_to_zero():
+  # 1-Wire trick: a frame followed by its CRC-8/Maxim re-checksums back to 0
+  rom = bytes([0x28, 0xFF, 0x64, 0x1E, 0x0F, 0x9A, 0x6B]) # DS18B20-style ROM code
+  assert crc8_maxim.checksum(crc8_maxim.encode(rom)) == 0
+
+@pytest.mark.parametrize("crc", [crc8_smbus, crc16_modbus, crc32_iso])
+def every_single_bit_flip_is_detected(crc):
+  # the core promise of a CRC: any one-bit error in the frame fails verification
+  frame = crc.encode(b"sensor")
+  for i in range(len(frame)):
+    for bit in range(8):
+      broken = bytearray(frame)
+      broken[i] ^= (1 << bit)
+      assert crc.decode(bytes(broken)) is None

xaeian-0.7.4/tests/test_cstruct.py

@@ -0,0 +1,127 @@
+# tests/test_cstruct.py
+
+"""Binary (de)serialization: round-trips, transforms, framing, regressions."""
+
+import pytest
+from xaeian.cstruct import Struct, Field, Type, Bitfield, Variant, Endian, Frame
+from xaeian.crc import crc32_iso
+
+def scalars():
+  s = Struct(name="scalars").add(
+    Field(Type.uint8, "a"), Field(Type.int16, "b"), Field(Type.uint32, "c"),
+  )
+  data = {"a": 7, "b": -1234, "c": 100_000}
+  assert s.decode(s.encode(data)) == data
+
+def decode_returns_dict_for_one_list_for_many():
+  s = Struct(name="rec").add(Field(Type.uint8, "n"))
+  assert s.decode(s.encode({"n": 1})) == {"n": 1}
+  assert s.decode(s.encode([{"n": 1}, {"n": 2}])) == [{"n": 1}, {"n": 2}]
+
+def floats_keep_value():
+  s = Struct(name="floats").add(Field(Type.float, "x"), Field(Type.double, "y"))
+  data = {"x": 1.5, "y": 0.25} # exact in IEEE-754, no rounding slack needed
+  assert s.decode(s.encode(data)) == data
+
+def scale_stores_fixed_point():
+  s = Struct(name="scaled").add(Field(Type.uint16, "mv", scale=1000))
+  assert s.encode({"mv": 1.5}) == (1500).to_bytes(2, "little")
+  assert s.decode(s.encode({"mv": 1.5})) == {"mv": 1.5}
+
+def array_field():
+  s = Struct(name="arr").add(Field(Type.uint8, "xs", length=4))
+  data = {"xs": [10, 20, 30, 40]}
+  assert s.decode(s.encode(data)) == data
+
+def string_and_bytes():
+  s = Struct(name="blob").add(Field(Type.string, "name"), Field(Type.bytes, "data"))
+  data = {"name": "xaeian", "data": b"\x01\x02\x03"}
+  assert s.decode(s.encode(data)) == data
+
+def string_utf8_roundtrip():
+  s = Struct(name="txt").add(Field(Type.string, "t"))
+  data = {"t": "żółw → OK"}
+  assert s.decode(s.encode(data)) == data
+
+def crc_frame_roundtrip_single_and_multi():
+  s = Struct(name="cf", crc_frame=crc32_iso).add(Field(Type.uint16, "x"))
+  assert s.decode(s.encode({"x": 7})) == {"x": 7}
+  assert s.decode(s.encode([{"x": 1}, {"x": 2}])) == [{"x": 1}, {"x": 2}]
+
+def crc_frame_rejects_corruption():
+  s = Struct(name="cfbad", crc_frame=crc32_iso).add(Field(Type.uint16, "x"))
+  bad = bytearray(s.encode({"x": 7}))
+  bad[-1] ^= 0xFF
+  with pytest.raises(ValueError):
+    s.decode(bytes(bad))
+
+def bitfield():
+  s = Struct(name="flags").add(Bitfield("st", [("on", 1), ("err", 1), ("mode", 6)]))
+  data = {"st": {"on": 1, "err": 0, "mode": 42}}
+  assert s.decode(s.encode(data)) == data
+
+def optional_field_uses_default():
+  s = Struct(name="opt").add(
+    Field(Type.uint8, "a"), Field(Type.uint8, "b", optional=True, default=9),
+  )
+  assert s.decode(s.encode({"a": 1})) == {"a": 1, "b": 9}
+
+@pytest.mark.parametrize("endian, order", [(Endian.little, "little"), (Endian.big, "big")])
+def endian_mirrors_bytes(endian, order):
+  s = Struct(name=f"e_{order}", endian=endian).add(Field(Type.uint16, "n"))
+  assert s.encode({"n": 258}) == (258).to_bytes(2, order) # 258 == 0x0102
+  assert s.decode(s.encode({"n": 258})) == {"n": 258}
+
+@pytest.mark.parametrize("kind, body", [(0, {"a": 99}), (1, {"b": 1.5, "c": 2.5})])
+def variant_selects_layout(kind, body):
+  s = Struct(name="msg").add(
+    Field(Type.uint8, "kind"),
+    Variant("body", "kind", {
+      0: [Field(Type.uint32, "a")],
+      1: [Field(Type.float, "b"), Field(Type.float, "c")],
+    }),
+  )
+  msg = {"kind": kind, "body": body}
+  assert s.decode(s.encode(msg)) == msg
+
+@pytest.mark.usefixtures("registry")
+def frame_routes_by_code():
+  pos = Struct(code=1, name="pos").add(Field(Type.int16, "x"), Field(Type.int16, "y"))
+  temp = Struct(code=2, name="temp").add(Field(Type.float, "t"))
+  frame = Frame(pos, temp)
+  data = {"pos": {"x": -3, "y": 7}, "temp": {"t": 21.5}}
+  assert frame.decode(frame.encode(data)) == data
+
+def alignment_padding_roundtrips_each_record():
+  # regression: decode must consume the padding encode appends after each record
+  s = Struct(name="aligned", align=4).add(Field(Type.uint8, "a"), Field(Type.uint16, "b"))
+  recs = [{"a": 1, "b": 2}, {"a": 3, "b": 4}]
+  assert s.decode(s.encode(recs)) == recs
+
+def crc_detects_corruption():
+  s = Struct(name="guarded", crc=crc32_iso).add(Field(Type.uint16, "n"))
+  frame = s.encode({"n": 0xBEEF})
+  assert s.decode(frame) == {"n": 0xBEEF}
+  corrupt = bytes([frame[0] ^ 0xFF]) + frame[1:]
+  with pytest.raises(ValueError):
+    s.decode(corrupt)
+
+def missing_required_field_raises():
+  s = Struct(name="req").add(Field(Type.uint8, "a"))
+  with pytest.raises(KeyError):
+    s.encode({})
+
+@pytest.fixture
+def registry():
+  saved = dict(Struct._codes)
+  Struct._codes.clear()
+  yield
+  Struct._codes.clear()
+  Struct._codes.update(saved)
+
+@pytest.mark.usefixtures("registry")
+def code_registry_is_idempotent():
+  Struct(code=0xA1, name="Frame")
+  Struct(code=0xA1, name="Frame") # same code + name: allowed
+  with pytest.raises(ValueError):
+    Struct(code=0xA1, name="Other") # same code, new name: rejected

xaeian-0.7.4/tests/test_db_kv_common.py

@@ -0,0 +1,128 @@
+# tests/test_db_kv_common.py
+
+"""KeyValue store internals: key/table validation, canonical JSON, SQL builders."""
+
+import json
+import time
+
+import pytest
+from xaeian.db.kv_common import (
+  check_key, check_table, dumps, loads, now_ms,
+  KEY_MAX, VALUE_MAX_BYTES,
+  sql_create, sql_get_value, sql_get_meta, sql_read_all, sql_read_all_meta, where_key,
+)
+
+#------------------------------------------------------------------------------------ check_key
+
+@pytest.mark.parametrize("key", ["a", "config.timeout", "x" * KEY_MAX])
+def check_key_accepts_reasonable_keys(key):
+  check_key(key) # no exception == pass
+
+def check_key_rejects_non_string():
+  with pytest.raises(TypeError):
+    check_key(123)
+
+def check_key_rejects_empty():
+  with pytest.raises(ValueError):
+    check_key("")
+
+def check_key_rejects_overlong():
+  with pytest.raises(ValueError):
+    check_key("x" * (KEY_MAX + 1))
+
+#---------------------------------------------------------------------------------- check_table
+
+@pytest.mark.parametrize("table", ["kv", "_store", "Cache1"])
+def check_table_accepts_valid_identifiers(table):
+  check_table(table)
+
+def check_table_rejects_non_string():
+  with pytest.raises(TypeError):
+    check_table(None)
+
+@pytest.mark.parametrize("table", ["", "1table", "drop table", "a-b", "a;b"])
+def check_table_rejects_bad_identifiers(table):
+  # stricter than keys: table names are interpolated into DDL, so no leading digit / symbols
+  with pytest.raises(ValueError):
+    check_table(table)
+
+def check_table_rejects_overlong():
+  with pytest.raises(ValueError):
+    check_table("t" * (KEY_MAX + 1))
+
+#---------------------------------------------------------------------------------------- dumps
+
+def dumps_is_canonical_sorted_and_compact():
+  assert dumps({"b": 1, "a": 2}) == '{"a":2,"b":1}'
+
+def dumps_preserves_unicode():
+  text = dumps("zażółć")
+  assert "\\u" not in text # not escaped
+  assert json.loads(text) == "zażółć"
+
+def dumps_rejects_oversized_values():
+  with pytest.raises(ValueError):
+    dumps("x" * (VALUE_MAX_BYTES + 1))
+
+def dumps_rejects_non_json_types():
+  with pytest.raises(TypeError):
+    dumps({1, 2, 3}) # a set is not JSON-serializable
+
+#---------------------------------------------------------------------------------------- loads
+
+def loads_round_trips_dumps():
+  for value in [None, True, 42, 1.5, "text", [1, 2], {"a": 1}]:
+    assert loads(dumps(value), "k") == value
+
+def loads_rejects_non_string_row():
+  with pytest.raises(ValueError):
+    loads(123, "mykey")
+
+def loads_wraps_bad_json_with_key_context():
+  with pytest.raises(ValueError, match="mykey"):
+    loads("{not json}", "mykey")
+
+#--------------------------------------------------------------------------------------- now_ms
+
+def now_ms_returns_epoch_milliseconds():
+  ts = now_ms()
+  assert isinstance(ts, int)
+  # bracket against the wall clock: catches a seconds (too small) or nanoseconds mixup
+  assert time.time() * 1000 - 5000 < ts < time.time() * 1000 + 5000
+
+#--------------------------------------------------------------------------------- SQL builders
+
+def sql_create_declares_kv_schema():
+  assert sql_create("kv") == (
+    "CREATE TABLE IF NOT EXISTS kv ("
+    f"key VARCHAR({KEY_MAX}) PRIMARY KEY, "
+    "value TEXT NOT NULL, "
+    "updated_at INTEGER NOT NULL)"
+  )
+
+def sql_get_value_selects_single_value():
+  assert sql_get_value("kv", "?") == "SELECT value FROM kv WHERE key = ?"
+
+def sql_get_meta_selects_value_and_timestamp():
+  assert sql_get_meta("kv", "$1") == "SELECT value, updated_at FROM kv WHERE key = $1"
+
+def sql_read_all_is_ordered_by_key():
+  assert sql_read_all("kv") == "SELECT key, value FROM kv ORDER BY key"
+
+def sql_read_all_meta_includes_timestamp():
+  assert sql_read_all_meta("kv") == "SELECT key, value, updated_at FROM kv ORDER BY key"
+
+def where_key_builds_lookup_clause():
+  assert where_key("%s") == "key = %s"
+
+@pytest.mark.parametrize("build", [
+  lambda t: sql_create(t),
+  lambda t: sql_get_value(t, "?"),
+  lambda t: sql_get_meta(t, "?"),
+  lambda t: sql_read_all(t),
+  lambda t: sql_read_all_meta(t),
+], ids=["create", "get_value", "get_meta", "read_all", "read_all_meta"])
+def sql_builders_reject_bad_table_names(build):
+  # every table name flows through ident(), so injection attempts blow up at build time
+  with pytest.raises(ValueError):
+    build("kv; DROP TABLE kv")