zs-yaml 0.9.1.dev2__tar.gz → 0.9.2.dev10__tar.gz

{zs_yaml-0.9.1.dev2 → zs_yaml-0.9.2.dev10}/.github/workflows/ci.yml

@@ -77,6 +77,18 @@ jobs:
             echo "Compression tests failed"
             exit 1
           fi
+      - name: Generate schema API for perf example
+        run: |
+          cd examples/perf
+          zserio perf.zs -withTypeInfoCode -python zs_gen_api
+      - name: Perf regression - byte-identical reference
+        run: |
+          cd examples/perf
+          python benchmark.py
+      - name: Perf regression - fast-path structural assertion
+        run: |
+          cd examples/perf
+          python test_fast_path.py
       - name: Build package
         run: |
           python -m build

{zs_yaml-0.9.1.dev2 → zs_yaml-0.9.2.dev10}/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.10.0] - 2026-05-07
+
+### Changed
+- Conversion is significantly faster: `yaml_to_bin` ~10x and `bin_to_dict` ~3x on the perf benchmark (5,000 records). Drop-in upgrade — output is byte-identical to 0.9.x. Fixes #21
+
+### Added
+- `examples/perf` benchmark plus CI guards to catch future performance regressions
+
+## [0.9.1] - 2026-04-27
+
+### Changed
+- Improved API documentation: clearer top-level entry points and a landing-page overview
+
 ## [0.9.0] - 2026-04-23
 
 ### Added

{zs_yaml-0.9.1.dev2 → zs_yaml-0.9.2.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zs-yaml
-Version: 0.9.1.dev2
+Version: 0.9.2.dev10
 Summary: YAML support for zserio
 Author-email: "Navigation Data Standard e.V." <support@nds-association.org>
 License-Expression: MIT

zs_yaml-0.9.2.dev10/examples/perf/.gitignore

@@ -0,0 +1,4 @@
+perf.yaml
+perf.bin
+zs_gen_api/
+__pycache__/

zs_yaml-0.9.2.dev10/examples/perf/benchmark.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Benchmark yaml_to_bin and bin_to_dict on the perf example.
+
+Generates the perf YAML on demand, runs yaml_to_bin N times, then runs
+bin_to_dict N times. Reports median wall time for each direction and,
+if reference artifacts are present, verifies byte-identical output.
+
+Usage:
+    python benchmark.py [--runs 3] [--records 5000] [--points-per-record 5]
+"""
+import argparse
+import hashlib
+import json
+import os
+import statistics
+import sys
+import time
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.abspath(os.path.join(HERE, "..", "..")))
+sys.path.insert(0, os.path.join(HERE, "zs_gen_api"))
+
+from zs_yaml.convert import yaml_to_bin, bin_to_dict  # noqa: E402
+
+from generate_perf_yaml import generate  # noqa: E402
+
+YAML_PATH = os.path.join(HERE, "perf.yaml")
+BIN_PATH = os.path.join(HERE, "perf.bin")
+REFERENCE_BIN = os.path.join(HERE, "perf_reference.bin")
+REFERENCE_DICT_HASH = os.path.join(HERE, "perf_reference_dict.sha256")
+
+SCHEMA_MODULE = "perf.api"
+SCHEMA_TYPE = "Dataset"
+
+
+def ensure_yaml(records: int, points_per_record: int) -> None:
+    if not os.path.exists(YAML_PATH):
+        print(f"Generating {YAML_PATH}...")
+        generate(records, points_per_record, YAML_PATH)
+
+
+def run_yaml_to_bin() -> float:
+    if os.path.exists(BIN_PATH):
+        os.remove(BIN_PATH)
+    t0 = time.perf_counter()
+    yaml_to_bin(YAML_PATH, BIN_PATH)
+    return time.perf_counter() - t0
+
+
+def run_bin_to_dict():
+    t0 = time.perf_counter()
+    data, _ = bin_to_dict(BIN_PATH, SCHEMA_MODULE, SCHEMA_TYPE)
+    return time.perf_counter() - t0, data
+
+
+def _report(label, timings):
+    median = statistics.median(timings)
+    print(f"{label} median: {median:.3f}s "
+          f"(min {min(timings):.3f}s, max {max(timings):.3f}s, runs={len(timings)})")
+    return median
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--runs", type=int, default=3)
+    parser.add_argument("--records", type=int, default=5000)
+    parser.add_argument("--points-per-record", type=int, default=5)
+    parser.add_argument("--write-reference", action="store_true",
+                        help="Overwrite reference artifacts with freshly produced output")
+    args = parser.parse_args()
+
+    ensure_yaml(args.records, args.points_per_record)
+
+    yaml_size = os.path.getsize(YAML_PATH)
+    print(f"Input: {YAML_PATH} ({yaml_size / (1024 * 1024):.2f} MiB)")
+
+    # Forward: yaml -> bin
+    print("\n[yaml_to_bin]")
+    yaml_timings = []
+    for i in range(args.runs):
+        elapsed = run_yaml_to_bin()
+        yaml_timings.append(elapsed)
+        print(f"  run {i + 1}: {elapsed:.3f}s")
+    _report("yaml_to_bin", yaml_timings)
+    bin_size = os.path.getsize(BIN_PATH)
+    print(f"Output bin: {bin_size / (1024 * 1024):.2f} MiB")
+
+    # Reverse: bin -> dict
+    print("\n[bin_to_dict]")
+    bin_timings = []
+    last_dict = None
+    for i in range(args.runs):
+        elapsed, last_dict = run_bin_to_dict()
+        bin_timings.append(elapsed)
+        print(f"  run {i + 1}: {elapsed:.3f}s")
+    _report("bin_to_dict", bin_timings)
+
+    dict_hash = hashlib.sha256(
+        json.dumps(last_dict, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+
+    if args.write_reference:
+        import shutil
+        shutil.copyfile(BIN_PATH, REFERENCE_BIN)
+        print(f"\nWrote reference bin -> {REFERENCE_BIN}")
+        with open(REFERENCE_DICT_HASH, "w") as f:
+            f.write(dict_hash + "\n")
+        print(f"Wrote reference dict hash -> {REFERENCE_DICT_HASH}")
+        return 0
+
+    status = 0
+    print()
+    if os.path.exists(REFERENCE_BIN):
+        with open(BIN_PATH, "rb") as a, open(REFERENCE_BIN, "rb") as b:
+            if a.read() == b.read():
+                print("bin matches perf_reference.bin byte-for-byte.")
+            else:
+                print("MISMATCH: bin differs from perf_reference.bin")
+                status = 1
+    else:
+        print("No perf_reference.bin yet; run with --write-reference to pin one.")
+
+    if os.path.exists(REFERENCE_DICT_HASH):
+        with open(REFERENCE_DICT_HASH) as f:
+            expected_hash = f.read().strip()
+        if dict_hash == expected_hash:
+            print("dict matches perf_reference_dict.sha256.")
+        else:
+            print(f"MISMATCH: dict hash {dict_hash} != expected {expected_hash}")
+            status = 1
+    else:
+        print("No perf_reference_dict.sha256 yet; run with --write-reference to pin one.")
+
+    return status
+
+
+if __name__ == "__main__":
+    sys.exit(main())

zs_yaml-0.9.2.dev10/examples/perf/generate_perf_yaml.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Deterministically generate a sizeable perf YAML for benchmarking.
+
+Produces examples/perf/perf.yaml with a Dataset containing a parameterized
+number of records, each with a short nested array of Points. Matches the
+"large array of small records with nested small arrays" pattern from
+issue #21 - the shape where the JSON tokenizer cost dominates.
+
+Usage:
+    python generate_perf_yaml.py [--records N] [--points-per-record M] [--out PATH]
+"""
+import argparse
+import os
+
+DEFAULT_RECORDS = 5000
+DEFAULT_POINTS_PER_RECORD = 5
+DEFAULT_OUT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "perf.yaml")
+
+
+def generate(records: int, points_per_record: int, out_path: str) -> None:
+    with open(out_path, "w") as f:
+        f.write("_meta:\n")
+        f.write("  schema_module: perf.api\n")
+        f.write("  schema_type: Dataset\n")
+        f.write("\n")
+        f.write('name: "perf-dataset"\n')
+        f.write("records:\n")
+        for i in range(records):
+            f.write(f"  - id: {i}\n")
+            f.write(f'    label: "record-{i:08d}"\n')
+            f.write("    points:\n")
+            for j in range(points_per_record):
+                x = (i * 31 + j) & 0x7FFFFFFF
+                y = (i * 17 - j) & 0x7FFFFFFF
+                f.write(f"      - x: {x}\n")
+                f.write(f"        y: {y}\n")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--records", type=int, default=DEFAULT_RECORDS)
+    parser.add_argument("--points-per-record", type=int, default=DEFAULT_POINTS_PER_RECORD)
+    parser.add_argument("--out", default=DEFAULT_OUT)
+    args = parser.parse_args()
+    generate(args.records, args.points_per_record, args.out)
+    size = os.path.getsize(args.out)
+    print(f"Wrote {args.out} ({size / (1024 * 1024):.2f} MiB, {args.records} records x {args.points_per_record} points)")
+
+
+if __name__ == "__main__":
+    main()

zs_yaml-0.9.2.dev10/examples/perf/perf.zs

@@ -0,0 +1,20 @@
+package perf;
+
+struct Point
+{
+    int32 x;
+    int32 y;
+};
+
+struct Record
+{
+    uint32 id;
+    string label;
+    Point points[];
+};
+
+struct Dataset
+{
+    string name;
+    Record records[];
+};

zs_yaml-0.9.2.dev10/examples/perf/perf_reference_dict.sha256

@@ -0,0 +1 @@
+fd4029aa09b63ec6edbf4af9d823566ff665438f2099113025fb0fa5bb8160b4

zs_yaml-0.9.2.dev10/examples/perf/test_fast_path.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Structural perf-regression guard.
+
+The 0.10 perf rewrite replaced `zserio.creator.ZserioTreeCreator` and
+`zserio.walker.Walker` with a per-compound typeinfo descriptor cache.
+Those two classes must never be instantiated on the `yaml_to_bin` /
+`bin_to_dict` hot paths. This test asserts that invariant directly so a
+future change that re-introduces the slow path fails CI - even on noisy
+GitHub-hosted runners where wall-clock measurements are unreliable.
+"""
+import os
+import sys
+import tempfile
+from unittest.mock import patch
+
+import zserio.creator
+import zserio.walker
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.abspath(os.path.join(HERE, "..", "..")))
+sys.path.insert(0, os.path.join(HERE, "zs_gen_api"))
+
+from zs_yaml.convert import yaml_to_bin, bin_to_dict  # noqa: E402
+
+from generate_perf_yaml import generate  # noqa: E402
+
+YAML_PATH = os.path.join(HERE, "perf.yaml")
+SCHEMA_MODULE = "perf.api"
+SCHEMA_TYPE = "Dataset"
+
+
+def _ensure_yaml():
+    if not os.path.exists(YAML_PATH):
+        generate(records=200, points_per_record=3, out_path=YAML_PATH)
+
+
+def _run_with_patches(fn):
+    with patch.object(zserio.creator, "ZserioTreeCreator") as creator, \
+         patch.object(zserio.walker, "Walker") as walker:
+        fn()
+        return creator.call_count, walker.call_count
+
+
+def test_yaml_to_bin_skips_slow_path():
+    _ensure_yaml()
+    with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as tmp:
+        bin_path = tmp.name
+    try:
+        creator_calls, walker_calls = _run_with_patches(
+            lambda: yaml_to_bin(YAML_PATH, bin_path)
+        )
+    finally:
+        os.unlink(bin_path)
+    assert creator_calls == 0, f"ZserioTreeCreator instantiated {creator_calls}x - slow path re-introduced"
+    assert walker_calls == 0, f"Walker instantiated {walker_calls}x - slow path re-introduced"
+    print("yaml_to_bin: no ZserioTreeCreator, no Walker - fast path confirmed")
+
+
+def test_bin_to_dict_skips_slow_path():
+    _ensure_yaml()
+    with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as tmp:
+        bin_path = tmp.name
+    try:
+        yaml_to_bin(YAML_PATH, bin_path)
+        creator_calls, walker_calls = _run_with_patches(
+            lambda: bin_to_dict(bin_path, SCHEMA_MODULE, SCHEMA_TYPE)
+        )
+    finally:
+        os.unlink(bin_path)
+    assert creator_calls == 0, f"ZserioTreeCreator instantiated {creator_calls}x - slow path re-introduced"
+    assert walker_calls == 0, f"Walker instantiated {walker_calls}x - slow path re-introduced"
+    print("bin_to_dict: no ZserioTreeCreator, no Walker - fast path confirmed")
+
+
+def main():
+    test_yaml_to_bin_skips_slow_path()
+    test_bin_to_dict_skips_slow_path()
+    print("\nAll fast-path assertions passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{zs_yaml-0.9.1.dev2 → zs_yaml-0.9.2.dev10}/zs_yaml/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.9.1.dev2'
-__version_tuple__ = version_tuple = (0, 9, 1, 'dev2')
+__version__ = version = '0.9.2.dev10'
+__version_tuple__ = version_tuple = (0, 9, 2, 'dev10')
 
-__commit_id__ = commit_id = 'g71a5fc59c'
+__commit_id__ = commit_id = 'g9846aef5d'