xaeian 0.7.2__tar.gz → 0.7.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xaeian
-Version: 0.7.2
+Version: 0.7.3
 Summary: Python utilities for files, strings, time, serial, structs, media, electronics, plotting, and database and more...
 Author: Xaeian
 License: MIT

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xaeian"
-version = "0.7.2"
+version = "0.7.3"
 description = "Python utilities for files, strings, time, serial, structs, media, electronics, plotting, and database and more..."
 readme = "readme.md"
 license = {text = "MIT"}

xaeian-0.7.3/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.3/tests/test_cstruct.py

@@ -0,0 +1,110 @@
+# 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 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.3/tests/test_files.py

@@ -0,0 +1,275 @@
+# tests/test_files.py
+
+"""File submodule: PATH/FILE/DIR + INI/CSV/JSON/YAML round-trips, in both modes
+(global `file_context` and object-bound `Files`)."""
+
+import os
+import json
+import pytest
+from xaeian import file_context, Files, PATH, DIR, FILE, INI, CSV, JSON, YAML
+
+@pytest.fixture(autouse=True)
+def _root_context(tmp_path):
+  # every test runs under a global context rooted at a fresh temp dir (restored on exit);
+  # tests that need the path itself take the standard `tmp_path` fixture directly
+  with file_context(root_path=str(tmp_path)):
+    yield
+
+#------------------------------------------------------------------------------------------ PATH
+
+@pytest.mark.parametrize("method, expected", [
+  ("basename", "c.txt"),
+  ("dirname", "a/b"),
+  ("stem", "c"),
+  ("ext", ".txt"),
+])
+def path_extracts_components(method, expected):
+  assert getattr(PATH, method)("a/b/c.txt") == expected
+
+def path_with_and_ensure_suffix():
+  assert PATH.with_suffix("a/b.txt", ".md") == "a/b.md"
+  assert PATH.ensure_suffix("a/b", ".txt") == "a/b.txt"
+  assert PATH.ensure_suffix("a/b.txt", ".txt") == "a/b.txt" # idempotent
+
+def path_normalize_posix_and_collapse():
+  assert PATH.normalize("a\\b//c/./d") == "a/b/c/d"
+
+def path_match_glob():
+  assert PATH.match("src/main.py", "*.py")
+  assert not PATH.match("src/main.py", "*.txt")
+
+def path_expand_env_and_user():
+  os.environ["XAEIAN_T"] = "/env/val"
+  assert PATH.expand("$XAEIAN_T/y") == "/env/val/y"
+  assert "~" not in PATH.expand("~/x") # ~ expands away
+
+def path_resolve_joins_root_for_relative(tmp_path):
+  resolved = PATH.resolve("data/x.txt")
+  assert resolved.startswith(PATH.normalize(str(tmp_path))) and resolved.endswith("/data/x.txt")
+
+def path_resolve_keeps_absolute(tmp_path):
+  abs_in = str(tmp_path / "x.txt")
+  assert PATH.resolve(abs_in) == PATH.normalize(abs_in)
+
+def path_join_resolves():
+  assert PATH.join("a", "b", "c.txt").endswith("/a/b/c.txt")
+
+def path_rel_and_is_under(tmp_path):
+  assert PATH.rel(str(tmp_path / "sub" / "f.txt")) == "sub/f.txt"
+  assert PATH.rel(str(tmp_path / "p/q/f.txt"), base=str(tmp_path / "p")) == "q/f.txt"
+  assert PATH.is_under("sub/f.txt")
+  assert not PATH.is_under("../outside")
+
+def path_ext_empty_for_no_extension():
+  assert PATH.ext("noext") == ""
+
+def path_exists_is_file_is_dir():
+  FILE.save("a.txt", "x")
+  DIR.ensure("d/")
+  assert PATH.exists("a.txt") and PATH.is_file("a.txt") and not PATH.is_dir("a.txt")
+  assert PATH.is_dir("d") and not PATH.is_file("d")
+  assert not PATH.exists("nope.txt")
+
+#------------------------------------------------------------------------------------------ FILE
+
+def file_text_roundtrip():
+  FILE.save("a.txt", "Hello!")
+  assert FILE.load("a.txt") == "Hello!"
+
+def file_binary_roundtrip():
+  FILE.save("b.bin", b"\x00\x01\x02")
+  assert FILE.load("b.bin", binary=True) == b"\x00\x01\x02"
+
+def file_append_and_lines():
+  FILE.save("c.txt", "a")
+  FILE.append("c.txt", "b")
+  FILE.append_line("c.txt", "c")
+  assert FILE.load("c.txt") == "abc\n"
+  FILE.save_lines("d.txt", ["x\n", "y\n"])
+  assert FILE.load_lines("d.txt") == ["x\n", "y\n"]
+  assert list(FILE.iter_lines("d.txt", strip=True)) == ["x", "y"]
+
+def file_save_creates_parent_dirs():
+  FILE.save("deep/nested/x.txt", "ok") # parent dirs auto-created
+  assert FILE.load("deep/nested/x.txt") == "ok"
+
+def file_exists_and_remove():
+  FILE.save("e.txt", "x")
+  assert FILE.exists("e.txt") and not FILE.exists(["e.txt", "missing"])
+  assert FILE.remove("e.txt") and not FILE.exists("e.txt")
+  assert FILE.remove("missing", missing_ok=True) is False
+
+def file_load_missing_raises():
+  with pytest.raises(FileNotFoundError):
+    FILE.load("nope.txt")
+
+def file_hash_and_size():
+  FILE.save("h.txt", "abc")
+  assert FILE.hash("h.txt", algo="md5") == "900150983cd24fb0d6963f7d28e17f72"      # md5("abc")
+  assert FILE.hash("h.txt") == "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" # sha256
+  assert FILE.size("h.txt") == 3 and FILE.mtime("h.txt") > 0
+
+#------------------------------------------------------------------------------------------- DIR
+
+def dir_ensure_creates_dirs(tmp_path):
+  DIR.ensure("a/b/c/")
+  assert (tmp_path / "a/b/c").is_dir()
+  DIR.ensure("x/y/file.txt", is_file=True) # only the parent dir is created
+  assert (tmp_path / "x/y").is_dir() and not (tmp_path / "x/y/file.txt").exists()
+
+def dir_file_list_filters_by_ext():
+  FILE.save("p/a.txt", "1"); FILE.save("p/b.py", "2"); FILE.save("p/sub/c.txt", "3")
+  assert sorted(DIR.file_list("p", exts=[".txt"], local=True)) == ["a.txt", "sub/c.txt"]
+
+def dir_file_list_match_and_blacklist():
+  FILE.save("p/a.txt", "1"); FILE.save("p/sub/c.py", "2")
+  assert DIR.file_list("p", match="*.py", local=True) == ["sub/c.py"]
+  assert DIR.file_list("p", blacklist=["sub"], local=True) == ["a.txt"]
+
+def dir_folder_list_and_iter_files():
+  FILE.save("base/a.txt", "1"); FILE.save("base/sub/b.txt", "2")
+  assert DIR.folder_list("base", basename=True) == ["sub"]
+  assert sorted(PATH.rel(f) for f in DIR.iter_files("base")) == ["base/a.txt", "base/sub/b.txt"]
+
+def dir_copy_move_remove(tmp_path):
+  FILE.save("src/a.txt", "x")
+  DIR.copy("src", "dst")
+  assert (tmp_path / "dst/a.txt").read_text(encoding="utf-8") == "x"
+  DIR.move("dst", "moved")
+  assert (tmp_path / "moved/a.txt").exists() and not (tmp_path / "dst").exists()
+  DIR.remove("moved")
+  assert not (tmp_path / "moved").exists()
+
+def dir_copy_single_file():
+  FILE.save("f.txt", "X")
+  DIR.copy("f.txt", "g.txt")
+  assert FILE.load("g.txt") == "X"
+
+def dir_remove_nonexistent_raises():
+  with pytest.raises(NotADirectoryError):
+    DIR.remove("missingdir")
+
+def dir_zip_unzip_roundtrip():
+  FILE.save("z/a.txt", "1"); FILE.save("z/inner/b.txt", "2")
+  DIR.zip("z")
+  DIR.unzip("z.zip", "out")
+  assert sorted(DIR.file_list("out", local=True)) == ["a.txt", "inner/b.txt"]
+
+#--------------------------------------------------------------------------------- INI/CSV/JSON
+
+def ini_roundtrip_preserves_types_and_sections():
+  data = {"top": 1, "main": {"k": "v", "n": 42, "flag": True, "pi": 1.5}}
+  INI.save("c", data)
+  assert INI.load("c") == data
+
+def ini_load_skips_comments_and_inline():
+  FILE.save("z.ini", "; comment\nk = 1 # inline\n[s]\nv = 2\n")
+  assert INI.load("z") == {"k": 1, "s": {"v": 2}}
+
+def ini_save_writes_inline_comment():
+  INI.save("w", {"k": (5, "note")}) # (value, comment) tuple → trailing comment
+  assert FILE.load("w.ini").strip() == "k = 5 # note"
+
+def ini_parse_hex_and_load_missing_empty():
+  assert INI.parse("0x10") == 16
+  assert INI.load("none") == {}
+
+@pytest.mark.parametrize("value, text", [(None, ""), (True, "true"), (False, "false"), (42, "42")])
+def ini_format_matches(value, text):
+  assert INI.format(value) == text
+
+@pytest.mark.parametrize("text, value", [
+  ("true", True), ("false", False), ("42", 42), ("1.5", 1.5), ('"hi"', "hi"),
+])
+def ini_parse_matches(text, value):
+  assert INI.parse(text) == value
+
+def csv_roundtrip_with_types():
+  CSV.save("d", [{"a": 1, "b": 2}, {"a": 3, "b": 4}])
+  assert CSV.load("d", types={"a": int, "b": int}) == [{"a": 1, "b": 2}, {"a": 3, "b": 4}]
+
+def csv_load_raw_and_vectors():
+  CSV.save("d", [{"a": 1, "b": 2}, {"a": 3, "b": 4}])
+  assert CSV.load_raw("d") == [["a", "b"], ["1", "2"], ["3", "4"]] # raw is strings
+  assert CSV.load_vectors("d", types={"a": int, "b": int}) == {"a": [1, 3], "b": [2, 4]}
+
+def csv_load_vectors_group_by():
+  CSV.save("g", [{"grp": "x", "v": 1}, {"grp": "x", "v": 2}, {"grp": "y", "v": 3}])
+  assert CSV.load_vectors("g", types={"v": int}, group_by="grp") == {"x": {"v": [1, 2]}, "y": {"v": [3]}}
+
+def csv_add_row_dict_and_list_rows():
+  CSV.add_row("e", {"x": 1, "y": 2}); CSV.add_row("e", {"x": 3, "y": 4})
+  assert CSV.load("e", types={"x": int, "y": int}) == [{"x": 1, "y": 2}, {"x": 3, "y": 4}]
+  CSV.add_row("lst", [1, 2], header=["x", "y"]); CSV.add_row("lst", [3, 4])
+  assert CSV.load("lst", types={"x": int, "y": int}) == [{"x": 1, "y": 2}, {"x": 3, "y": 4}]
+
+def csv_save_vectors_zips_and_rejects_mismatch():
+  CSV.save_vectors("v", [1, 2], [3, 4], header=["a", "b"])
+  assert CSV.load("v", types={"a": int, "b": int}) == [{"a": 1, "b": 3}, {"a": 2, "b": 4}]
+  with pytest.raises(ValueError):
+    CSV.save_vectors("bad", [1, 2], [3]) # unequal column lengths
+
+def csv_load_missing_returns_empty():
+  assert CSV.load("none") == []
+
+def json_roundtrip():
+  data = {"a": 1, "b": [1, 2, 3], "c": {"x": True}}
+  JSON.save("j", data)
+  assert JSON.load("j") == data
+
+def json_pretty_and_smart_roundtrip():
+  data = {"name": "ok", "xs": [1, 2, 3]}
+  JSON.save_pretty("p", data); assert JSON.load("p") == data
+  JSON.save_smart("s", data); assert JSON.load("s") == data
+
+def json_smart_stays_valid_and_ascii_escapes():
+  data = {"xs": [1, 2, 3], "m": {"a": 1}}
+  assert json.loads(JSON.smart(data)) == data # smart layout is still valid JSON
+  JSON.save("u", {"k": "ą"}, ensure_ascii=True)
+  assert "ą" not in FILE.load("u.json") # non-ascii escaped
+
+def json_load_missing_returns_default():
+  assert JSON.load("nope", otherwise={"def": 1}) == {"def": 1}
+
+def yaml_roundtrip():
+  data = {"debug": True, "port": 8080, "tags": ["a", "b"]}
+  YAML.save("y", data)
+  assert YAML.load("y") == data
+
+def yaml_pretty_multi_doc_and_missing():
+  YAML.save_pretty("yp", {"a": 1, "b": [1, 2]}); assert YAML.load("yp") == {"a": 1, "b": [1, 2]}
+  YAML.save_all("m", [{"id": 1}, {"id": 2}]); assert YAML.load_all("m") == [{"id": 1}, {"id": 2}]
+  assert YAML.load("none", otherwise=[]) == []
+
+#------------------------------------------------------------------------------------ Modes
+
+def file_context_restores_previous_root(tmp_path):
+  a, b = tmp_path / "A", tmp_path / "B"
+  with file_context(root_path=str(a)):
+    FILE.save("x.txt", "a")
+    with file_context(root_path=str(b)):
+      FILE.save("y.txt", "b")
+    FILE.save("z.txt", "a2") # back to A after the inner block exits
+  assert (a / "x.txt").exists() and (a / "z.txt").exists()
+  assert (b / "y.txt").exists() and not (b / "z.txt").exists()
+
+def files_object_uses_its_own_root(tmp_path):
+  fs = Files(root_path=str(tmp_path / "obj"))
+  fs.FILE.save("o.txt", "obj")
+  assert (tmp_path / "obj" / "o.txt").read_text(encoding="utf-8") == "obj"
+  assert fs.FILE.load("o.txt") == "obj"
+
+def files_object_data_namespaces(tmp_path):
+  fs = Files(root_path=str(tmp_path / "data"))
+  fs.JSON.save("cfg", {"a": 1}); assert fs.JSON.load("cfg") == {"a": 1}
+  fs.CSV.save("d", [{"x": 1}]); assert fs.CSV.load("d", types={"x": int}) == [{"x": 1}]
+  fs.INI.save("s", {"m": {"k": "v"}}); assert fs.INI.load("s") == {"m": {"k": "v"}}
+
+def files_object_independent_of_global_context(tmp_path):
+  a, b = tmp_path / "A", tmp_path / "B"
+  fs = Files(root_path=str(a))
+  with file_context(root_path=str(b)):
+    fs.FILE.save("iso.txt", "in-A") # bound to A despite active context B
+    FILE.save("ctx.txt", "in-B")    # global namespace follows the context → B
+  assert (a / "iso.txt").exists() and not (b / "iso.txt").exists()
+  assert (b / "ctx.txt").exists()

xaeian-0.7.3/tests/test_log.py

@@ -0,0 +1,84 @@
+# tests/test_log.py
+
+"""Colored logging: Print (level-filtered output) and Logger (rotating file)."""
+
+import io
+import logging
+from xaeian import logger, Print
+
+# Print writes to its `file=`; assertions use substrings (the level marker text
+# is embedded in the colored Ico, so it survives regardless of ANSI codes).
+
+def print_filters_below_threshold():
+  buf = io.StringIO()
+  p = Print(file=buf, level="WRN")
+  p.inf("ignored")
+  p.err("shown")
+  out = buf.getvalue()
+  assert "ignored" not in out
+  assert "shown" in out and "ERR" in out
+
+def print_default_level_shows_debug():
+  buf = io.StringIO()
+  Print(file=buf).dbg("hello")
+  assert "hello" in buf.getvalue()
+
+def print_sub_entry_inherits_last_level():
+  buf = io.StringIO()
+  p = Print(file=buf, level="WRN")
+  p.inf("hi"); p.dot("under-inf")   # INFO < WRN → both suppressed
+  p.err("boom"); p.dot("under-err") # ERROR shown; dot inherits ERROR → shown
+  out = buf.getvalue()
+  assert "under-inf" not in out
+  assert "boom" in out and "under-err" in out
+
+def print_level_property_accepts_name_or_int():
+  p = Print()
+  p.level = "WRN"
+  assert p.level == logging.WARNING
+  p.level = 10
+  assert p.level == 10
+
+def print_long_aliases_delegate_to_short():
+  buf = io.StringIO()
+  p = Print(file=buf, level="WRN")
+  p.info("hidden"); p.error("visible")
+  out = buf.getvalue()
+  assert "hidden" not in out and "visible" in out
+
+def print_ok_appends_badge():
+  buf = io.StringIO()
+  Print(file=buf).ok("done") # INFO ≥ default DBG → shown
+  out = buf.getvalue()
+  assert "done" in out and "OK" in out
+
+# Logger's file handler writes plain, ANSI-stripped lines with 3-char levels.
+
+def logger_writes_abbreviated_levels_to_file(tmp_path):
+  log = logger("xaeian_test_a", file=str(tmp_path / "a.log"), stream=False, file_lvl=logging.DEBUG)
+  log.debug("dbgmsg"); log.error("boom"); log.warning("warn"); log.panic("kaboom")
+  content = (tmp_path / "a.log").read_text(encoding="utf-8")
+  for line in ("DBG dbgmsg", "ERR boom", "WRN warn", "PNC kaboom"):
+    assert line in content
+
+def logger_item_inherits_last_level(tmp_path):
+  log = logger("xaeian_test_b", file=str(tmp_path / "b.log"), stream=False, file_lvl=logging.DEBUG)
+  log.error("failed")
+  log.item("detail") # " -  " prefix, logged at the last level (ERROR)
+  assert "ERR  -  detail" in (tmp_path / "b.log").read_text(encoding="utf-8")
+
+def logger_ok_appends_stripped_badge(tmp_path):
+  log = logger("xaeian_test_c", file=str(tmp_path / "c.log"), stream=False, file_lvl=logging.DEBUG)
+  log.ok("done")
+  assert "INF done OK" in (tmp_path / "c.log").read_text(encoding="utf-8")
+
+def logger_respects_file_level(tmp_path):
+  log = logger("xaeian_test_d", file=str(tmp_path / "d.log"), stream=False, file_lvl=logging.WARNING)
+  log.info("below"); log.warning("at")
+  content = (tmp_path / "d.log").read_text(encoding="utf-8")
+  assert "below" not in content and "WRN at" in content
+
+def logger_file_property_reports_path(tmp_path):
+  path = str(tmp_path / "e.log")
+  log = logger("xaeian_test_e", file=path, stream=False)
+  assert log.file == path

xaeian-0.7.3/tests/test_table.py

@@ -0,0 +1,144 @@
+# tests/test_table.py
+
+"""Tabular ops on list[dict]: filter, columns, sort/dedup, group/aggregate, join, markdown."""
+
+import pytest
+from xaeian.table import (
+  where, first, take,
+  columns, select, exclude, rename, add_column, pluck, set_defaults,
+  sort_by, unique,
+  group_by, count_by, aggregate,
+  join, concat,
+  replace_values, map_column,
+  describe, markdown, markdown_raw,
+)
+
+@pytest.fixture
+def rows():
+  return [
+    {"name": "Ann", "dept": "eng", "salary": 100},
+    {"name": "Bob", "dept": "eng", "salary": 120},
+    {"name": "Cy", "dept": "ops", "salary": 90},
+  ]
+
+def where_filters_by_predicate(rows):
+  assert where(rows, lambda r: r["salary"] >= 100) == rows[:2]
+
+def first_returns_match_or_none(rows):
+  assert first(rows, lambda r: r["dept"] == "ops") == rows[2]
+  assert first(rows, lambda r: r["dept"] == "hr") is None
+
+def take_slices_with_offset(rows):
+  assert take(rows, 1, offset=1) == [rows[1]]
+
+def columns_from_first_row(rows):
+  assert columns(rows) == ["name", "dept", "salary"]
+  assert columns([]) == []
+
+def select_keeps_only_named_columns(rows):
+  assert select(rows, "name") == [{"name": "Ann"}, {"name": "Bob"}, {"name": "Cy"}]
+
+def exclude_drops_named_columns(rows):
+  assert exclude(rows, "salary", "dept") == [{"name": "Ann"}, {"name": "Bob"}, {"name": "Cy"}]
+
+def rename_remaps_keys(rows):
+  assert rename(rows, {"dept": "team"})[0] == {"name": "Ann", "team": "eng", "salary": 100}
+
+def add_column_computes_in_place(rows):
+  out = add_column(rows, "bonus", lambda r: r["salary"] // 10)
+  assert out is rows and rows[0]["bonus"] == 10 # mutates and returns the same list
+
+def pluck_extracts_one_column(rows):
+  assert pluck(rows, "name") == ["Ann", "Bob", "Cy"]
+
+def set_defaults_fills_only_missing():
+  data = [{"a": 1}, {"a": 2, "b": 9}]
+  set_defaults(data, b=0)
+  assert data == [{"a": 1, "b": 0}, {"a": 2, "b": 9}] # existing b kept
+
+def sort_by_orders_with_none_last():
+  data = [{"s": 3}, {"s": None}, {"s": 1}]
+  assert pluck(sort_by(data, "s"), "s") == [1, 3, None]
+  assert pluck(sort_by(data, "s", reverse=True), "s") == [3, 1, None]
+
+def sort_by_tolerates_mixed_types():
+  assert pluck(sort_by([{"x": 1}, {"x": "a"}, {"x": 2}], "x"), "x") == [1, 2, "a"]
+
+def unique_dedupes_by_key_and_unhashable():
+  assert unique([{"id": 1}, {"id": 1}, {"id": 2}], "id") == [{"id": 1}, {"id": 2}]
+  assert unique([{"t": [1, 2]}, {"t": [1, 2]}, {"t": [3]}], "t") == [{"t": [1, 2]}, {"t": [3]}]
+
+def group_by_buckets_rows(rows):
+  groups = group_by(rows, "dept")
+  assert list(groups) == ["eng", "ops"] and len(groups["eng"]) == 2
+
+def count_by_counts_values(rows):
+  assert count_by(rows, "dept") == {"eng": 2, "ops": 1}
+
+def aggregate_supports_sum_count_join(rows):
+  assert aggregate(rows, "dept", {"salary": "sum", "name": "join", "n": "count"}) == [
+    {"dept": "eng", "salary": 220, "name": "Ann,Bob", "n": 2},
+    {"dept": "ops", "salary": 90, "name": "Cy", "n": 1},
+  ]
+  assert aggregate(rows, "dept", {"name": "join:;"})[0]["name"] == "Ann;Bob"
+
+@pytest.mark.parametrize("agg, eng_value", [
+  ("mean", 110.0), ("min", 100), ("max", 120),
+  ("first", 100), ("last", 120),
+  (lambda vs: sum(vs), 220),
+])
+def aggregate_reduces_eng_salary(rows, agg, eng_value):
+  assert aggregate(rows, "dept", {"salary": agg})[0]["salary"] == eng_value
+
+@pytest.mark.parametrize("how, names", [
+  ("inner", ["a"]),
+  ("left", ["a", "b"]),
+  ("right", ["a", None]),
+  ("outer", ["a", "b", None]),
+])
+def join_modes_match_keys(how, names):
+  left = [{"id": 1, "name": "a"}, {"id": 2, "name": "b"}]
+  right = [{"id": 1, "city": "X"}, {"id": 3, "city": "Z"}]
+  assert pluck(join(left, right, on="id", how=how), "name") == names
+
+def concat_stacks_and_fills_missing():
+  assert concat([{"a": 1}], [{"b": 2}]) == [{"a": 1, "b": None}, {"a": None, "b": 2}]
+
+def replace_values_maps_in_place(rows):
+  replace_values(rows, "dept", {"eng": "E"})
+  assert pluck(rows, "dept") == ["E", "E", "ops"]
+
+def map_column_applies_fn_in_place(rows):
+  map_column(rows, "salary", lambda v: v + 1)
+  assert pluck(rows, "salary") == [101, 121, 91]
+
+def describe_summarizes_numeric_column(rows):
+  d = describe(rows, "salary")
+  assert (d["count"], d["nulls"], d["unique"], d["min"], d["max"]) == (3, 0, 3, 90, 120)
+  assert d["mean"] == pytest.approx(103.333, abs=0.01)
+
+def describe_counts_nulls_and_skips_non_numeric_mean():
+  d = describe([{"v": "x"}, {"v": None}, {"v": "y"}], "v")
+  assert (d["count"], d["nulls"], d["unique"], d["mean"]) == (3, 1, 2, None)
+
+def markdown_renders_table_with_auto_align():
+  data = [{"name": "R1", "value": 10}, {"name": "R2", "value": 22}]
+  assert markdown(data) == (
+    "| name | value |\n"
+    "| :--- | ----: |\n" # numeric column auto-aligns right
+    "| R1   |    10 |\n"
+    "| R2   |    22 |"
+  )
+
+def markdown_raw_renders_list_of_lists():
+  raw = [["Name", "Ohm"], ["R1", "10k"], ["R2", "22k"]]
+  assert markdown_raw(raw) == (
+    "| Name | Ohm |\n"
+    "| :--- | :-- |\n"
+    "| R1   | 10k |\n"
+    "| R2   | 22k |"
+  )
+
+def markdown_escapes_pipe_and_handles_empty():
+  assert markdown([{"a": "x|y"}]) == "| a    |\n| :--- |\n| x\\|y |"
+  assert markdown([]) == ""