vgi-python 0.26.0__tar.gz → 0.28.0__tar.gz

{vgi_python-0.26.0 → vgi_python-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.26.0
+Version: 0.28.0
 Summary: Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow
 Project-URL: Homepage, https://query.farm
 Project-URL: Repository, https://github.com/Query-farm/vgi-python

vgi_python-0.28.0/RELEASE-RUNBOOK.md

@@ -0,0 +1,69 @@
+# Release runbook — describe.json retirement + attach-option `required`
+
+All code is committed on `main` in each repo and green. Nothing is pushed.
+This is the ordering and the per-repo trigger; fill in `X.Y.Z` per package.
+
+**Version decision needed first.** Three transports drop `DescribeProvider`
+from their public API (breaking): `@query-farm/vgi-rpc`, `vgi-rpc` (Rust),
+`farm.query:vgirpc`. Choose major or minor per your compatibility policy — it
+cascades into the implementation pins below.
+
+## 1. Transports (must publish first)
+
+| Repo | Trigger | Version lives in |
+|---|---|---|
+| vgi-rpc-typescript | `gh release create vX.Y.Z` (release: published) | `package.json` (+ `bun install` to sync `bun.lock`) |
+| vgi-rpc-rust | tag push — `gh release create vX.Y.Z` | `[workspace.package] version`; `cargo update -w` |
+| vgi-rpc-java | `gh release create vX.Y.Z` (release: published) | `build.gradle.kts` |
+| vgi-rpc-go | tag push — `gh release create vX.Y.Z` | none (module proxy reads the tag) |
+
+Then wait for index propagation: npm, `https://index.crates.io/3/v/vgi-rpc`,
+Maven Central, Go proxy.
+
+## 2. Implementation dependency pins
+
+These currently cannot build against published transports:
+
+- **vgi-typescript** — peer range is `>=0.18.1 <0.19.0`; widen to the new
+  transport version. `LandingInfo` resolves only once the transport publishes.
+- **vgi-rust** — workspace dep already bumped to `vgi-rpc 0.20.0`; adjust if you
+  pick a different number. The `[patch.crates-io]` block stays uncommitted (it
+  is documented in `Cargo.toml` for local co-development only).
+- **vgi-java** — bump `api("farm.query:vgirpc:X")` and the `VGI_RPC_JAVA_REF`
+  pin in `.github/workflows/integration.yml`. (`landing.yml` was deleted with
+  the contract it checked.)
+- **vgi-go** — self-contained; no pin, but it needs the new vgi-rpc-go tag.
+
+## 3. Implementations
+
+| Repo | Trigger | Version lives in |
+|---|---|---|
+| vgi-python | `gh release create vX.Y.Z --target main` (PyPI on release) | root `pyproject.toml`; `uv lock` |
+| vgi-go | `gh release create vX.Y.Z` (tag → module proxy) | none |
+| vgi-rust | `gh release create vX.Y.Z` (tag → crates.io) | `[workspace.package] version` |
+| vgi-typescript | **`git tag vX.Y.Z && git push origin vX.Y.Z`** — pushing the bump to main does NOT publish and fails silently | `package.json`; `bun install` |
+| vgi-java | `gh release create vX.Y.Z` (Maven Central on release) | `build.gradle.kts` |
+
+## 4. Frontend
+
+- **vgi-web-frontend** — auto-deploys on push to `main`. Push last, so no worker
+  is serving a page newer than its vendored bundle.
+
+## Verified before release
+
+- vgi-python 2175 pass / 99 skip; ruff + mypy clean
+- vgi-go `go test ./...` clean; vet + gofmt clean
+- vgi-rust tests pass; clippy `-D warnings` clean
+- vgi-java `:vgi:test` passes
+- vgi-rpc-typescript 715 pass / 26 fail — exactly the pre-change baseline
+  (confirmed by running the suite at the parent commit in a worktree)
+- Landing page verified in a browser against all four language workers:
+  Python 221 functions, Go 221, Rust 654, Java 219 — each 2 schemas, 59 tables,
+  3 views, with lazy columns loading.
+
+## Not done, tracked
+
+- `vgi-rpc-typescript` has 26 pre-existing test failures (integration/streaming;
+  unrelated to this work, present before it).
+- `~/vgi-java/CLAUDE.md` still references the landing-conformance workflow in
+  its historical notes; the workflow itself is deleted.

{vgi_python-0.26.0 → vgi_python-0.28.0}/docs/column-statistics.md

@@ -180,6 +180,30 @@ Statistics are transmitted via the `catalog_table_column_statistics_get` RPC met
 
 Cache TTL is carried as IPC batch `custom_metadata` with key `cache_max_age_seconds`.
 
+## Reading Statistics From a Client
+
+DuckDB is not the only caller. A pure-Python [`Client`][vgi.client.Client] reads the same statistics with
+`table_column_statistics`, which issues the RPC and decodes the sparse-union batch for you:
+
+```python test="skip"
+stats = client.table_column_statistics(
+    attach_opaque_data=attach.attach_opaque_data,
+    schema_name="main",
+    name="events",
+)
+for column in stats:
+    print(column.column_name, column.min, column.max, column.distinct_count)
+```
+
+Workers may also inline statistics on `TableInfo.column_statistics` rather than serving them
+lazily; `TableInfo.supports_column_statistics` advertises which. Prefer the inlined copy when
+it is present and fall back to the call above.
+
+To decode bytes you already hold, use `deserialize_column_statistics` — the inverse of
+`serialize_column_statistics`. The `cache_max_age_seconds` TTL travels in the batch's custom
+metadata rather than in the statistics, so read it with `deserialize_record_batch` if you
+need it.
+
 ## Capability Flags
 
 Statistics are opt-in at two levels:

{vgi_python-0.26.0 → vgi_python-0.28.0}/docs/how-to/function-patterns.md

@@ -213,6 +213,31 @@ ATTACH 'buffers' (TYPE vgi, LOCATION 'uv run row_count_worker.py');
 SELECT * FROM buffers.row_count((SELECT * FROM big_table));
 ```
 
+### Getting the input in order
+
+The sink runs in parallel across DuckDB threads, so `process` sees batches in no particular order.
+When output depends on input *order* — a running total, a row pattern match — set
+`Meta.requires_input_batch_index = True` and each `process` call receives `params.batch_index`, a
+monotonic ordinal you can sort the buffered batches by in `finalize`.
+
+Not every source can supply one (a base table scan can; `range()` and `VALUES` cannot). When it
+cannot, the extension serializes the sink and numbers the batches itself, so a worker always gets a
+valid index and callers never have to wrap their input. This example reports the indices it saw, one
+row per buffered batch:
+
+```python
+--8<-- "examples/batch_index_worker.py"
+```
+
+```sql
+ATTACH 'bi' (TYPE vgi, LOCATION 'uv run batch_index_worker.py');
+SELECT * FROM bi.batch_indexes((SELECT * FROM range(5000))) ORDER BY batch_index;
+```
+
+The alternative, `Meta.sink_order_dependent = True`, delivers ordered input by forcing a
+single-threaded sink. It works with any source but gives up parallel ingest, which is usually the
+bulk of a buffering query's wall time. The two flags are mutually exclusive.
+
 ??? info "Buffering vs. table-in-out"
     Both consume a relation, but a **table-in-out** function emits *per input batch* and never
     holds the whole input — use it for streaming transforms (filter, enrich, reshape). Reach for

vgi_python-0.28.0/examples/batch_index_worker.py

@@ -0,0 +1,142 @@
+# /// script
+# requires-python = ">=3.13"
+# dependencies = ["vgi-python"]
+# ///
+"""A buffering function that asks for input order, and reports what it got.
+
+A buffering sink normally runs in parallel across DuckDB threads, so batches
+arrive in no particular order. Setting ``Meta.requires_input_batch_index`` asks
+for DuckDB's per-chunk index alongside each batch, which is what lets a worker
+put the input back in order — the prerequisite for anything order-sensitive,
+like row pattern matching or a running total.
+
+Not every source can supply one: a base table scan can, while ``range()`` and
+``VALUES`` cannot. When it cannot, the extension serializes the sink and numbers
+the batches itself, so a worker sees a valid monotonic index either way and never
+has to care which route produced it.
+
+This function emits one row per buffered batch — its index and its row count — so
+the guarantee is directly observable:
+
+    ATTACH 'bi' (TYPE vgi, LOCATION 'uv run batch_index_worker.py');
+    SELECT * FROM bi.batch_indexes((SELECT * FROM range(5000))) ORDER BY batch_index;
+"""
+
+from dataclasses import dataclass
+from typing import Annotated
+
+import pyarrow as pa
+from vgi_rpc import ArrowSerializableDataclass
+
+from vgi import Arg, Worker
+from vgi.arguments import TableInput
+from vgi.catalog import Catalog, Schema
+from vgi.invocation import BindResponse
+from vgi.table_buffering_function import OutputCollector, TableBufferingFunction, TableBufferingParams
+from vgi.table_function import BindParams
+
+_RESULT = pa.schema([("batch_index", pa.int64()), ("rows", pa.int64())])
+
+# One log entry per buffered batch: the index DuckDB gave us, and the batch size.
+_NS = b"batches"
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class BatchIndexArgs:
+    """Arguments: the input table whose batches should be reported."""
+
+    data: Annotated[TableInput, Arg(0, doc="Input table")]
+
+
+@dataclass(kw_only=True)
+class DrainState(ArrowSerializableDataclass):
+    """Per-finalize-stream cursor: emit the report once, then finish."""
+
+    done: bool = False
+
+
+class BatchIndexes(TableBufferingFunction[BatchIndexArgs, DrainState]):
+    """Report the batch index and row count of every buffered input batch."""
+
+    class Meta:
+        """Function metadata."""
+
+        name = "batch_indexes"
+        # Ask for DuckDB's per-chunk index. Mutually exclusive with
+        # sink_order_dependent, which orders the input by serializing the sink
+        # instead of by numbering it.
+        requires_input_batch_index = True
+
+    @classmethod
+    def on_bind(cls, params: BindParams[BatchIndexArgs]) -> BindResponse:
+        """Output shape is fixed: one row per input batch."""
+        return BindResponse(output_schema=_RESULT)
+
+    @classmethod
+    def process(cls, batch: pa.RecordBatch, params: TableBufferingParams[BatchIndexArgs]) -> bytes:
+        """Sink: record this batch's index and size.
+
+        ``params.batch_index`` is populated because ``Meta`` asked for it; -1
+        stands in for the absent case so an older host that does not supply one
+        degrades to a visible marker instead of a crash.
+        """
+        index = params.batch_index if params.batch_index is not None else -1
+        payload = index.to_bytes(8, "little", signed=True) + batch.num_rows.to_bytes(8, "little")
+        params.storage.state_append(_NS, b"", payload)
+        return params.execution_id
+
+    @classmethod
+    def combine(cls, state_ids: list[bytes], params: TableBufferingParams[BatchIndexArgs]) -> list[bytes]:
+        """Nothing to reduce: the log already holds one entry per batch."""
+        return [params.execution_id]
+
+    @classmethod
+    def initial_finalize_state(
+        cls, finalize_state_id: bytes, params: TableBufferingParams[BatchIndexArgs]
+    ) -> DrainState:
+        """One cursor per finalize stream."""
+        return DrainState()
+
+    @classmethod
+    def finalize(
+        cls,
+        params: TableBufferingParams[BatchIndexArgs],
+        finalize_state_id: bytes,
+        state: DrainState,
+        out: OutputCollector,
+    ) -> None:
+        """Source: emit the report, ordered by batch index."""
+        if state.done:
+            out.finish()
+            return
+        entries = [
+            (
+                int.from_bytes(value[:8], "little", signed=True),
+                int.from_bytes(value[8:16], "little"),
+            )
+            for _id, value in params.storage.state_log_scan(_NS, b"")
+        ]
+        entries.sort()
+        out.emit(
+            pa.RecordBatch.from_pydict(
+                {
+                    "batch_index": [index for index, _rows in entries],
+                    "rows": [rows for _index, rows in entries],
+                },
+                schema=params.output_schema,
+            )
+        )
+        state.done = True
+
+
+class BatchIndexWorker(Worker):
+    """A worker exposing the ``bi`` catalog."""
+
+    catalog = Catalog(
+        name="bi",
+        schemas=[Schema(name="main", functions=[BatchIndexes])],
+    )
+
+
+if __name__ == "__main__":
+    BatchIndexWorker().run()

{vgi_python-0.26.0 → vgi_python-0.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.26.0"
+version = "0.28.0"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [

vgi_python-0.28.0/tests/catalog/test_attach_option.py

@@ -0,0 +1,192 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Tests for the AttachOption descriptor, its ``required`` flag, and validation."""
+
+from typing import Annotated
+
+import pyarrow as pa
+import pytest
+from vgi_rpc.utils import deserialize_record_batch, serialize_record_batch_bytes
+
+from vgi.catalog._descriptor_spec import _SpecBase
+from vgi.catalog.attach_option import (
+    AttachOption,
+    AttachOptionSpec,
+    MissingAttachOptionsError,
+    extract_attach_option_specs,
+    validate_required_attach_options,
+)
+from vgi.catalog.catalog_interface import ReadOnlyCatalogInterface
+from vgi.catalog.setting import SettingSpec
+
+
+class _Options:
+    """Attach options mixing defaulted and required entries."""
+
+    region: Annotated[str, AttachOption(desc="AWS region")] = "us-east-1"
+    # No class-level assignment: nothing to fall back to, so the caller must supply it.
+    api_key: Annotated[str, AttachOption(desc="API key", required=True)]
+
+
+def _roundtrip(spec: AttachOptionSpec) -> AttachOptionSpec:
+    batch, _ = deserialize_record_batch(spec.serialize())
+    return AttachOptionSpec.deserialize(batch)
+
+
+class TestRequiredExtraction:
+    """Extraction of the ``required`` flag from Annotated declarations."""
+
+    def test_defaults_to_false(self) -> None:
+        """An option that isn't declared required isn't required."""
+        specs = {s.name: s for s in extract_attach_option_specs(_Options)}
+        assert specs["region"].required is False
+        assert specs["region"].default == "us-east-1"
+
+    def test_required_option_extracted(self) -> None:
+        """``required=True`` survives extraction, with no default."""
+        specs = {s.name: s for s in extract_attach_option_specs(_Options)}
+        assert specs["api_key"].required is True
+        assert specs["api_key"].default is None
+
+    def test_required_with_default_rejected(self) -> None:
+        """A required option that also defaults is contradictory."""
+        with pytest.raises(ValueError, match="required but also declares a default"):
+            AttachOptionSpec(name="api_key", desc="", type=pa.string(), default="fallback", required=True)
+
+
+class TestWireFormat:
+    """Serialization of the added ``required`` column."""
+
+    @pytest.mark.parametrize("required", [True, False], ids=["required", "optional"])
+    def test_roundtrip_preserves_required(self, required: bool) -> None:
+        """``required`` survives an Arrow IPC round trip in both states."""
+        spec = AttachOptionSpec(name="api_key", desc="API key", type=pa.string(), default=None, required=required)
+        assert _roundtrip(spec).required is required
+
+    def test_roundtrip_preserves_shared_fields(self) -> None:
+        """Widening the schema doesn't disturb the four shared columns."""
+        spec = AttachOptionSpec(name="region", desc="AWS region", type=pa.string(), default="us-east-1")
+        restored = _roundtrip(spec)
+        assert (restored.name, restored.desc, restored.type, restored.default) == (
+            "region",
+            "AWS region",
+            pa.string(),
+            "us-east-1",
+        )
+
+    def test_setting_wire_format_unchanged(self) -> None:
+        """``Setting`` keeps the original four columns; only AttachOption widened."""
+        assert SettingSpec.ARROW_SCHEMA.names == ["name", "description", "type", "default_value"]
+        assert AttachOptionSpec.ARROW_SCHEMA.names == [
+            "name",
+            "description",
+            "type",
+            "default_value",
+            "required",
+        ]
+
+    def test_reads_batch_without_required_column(self) -> None:
+        """A peer that predates the column yields ``required=False``, not an error."""
+        type_bytes = pa.schema([pa.field("value", pa.string())]).serialize().to_pybytes()
+        legacy = pa.RecordBatch.from_pylist(
+            [{"name": "region", "description": "AWS region", "type": type_bytes, "default_value": None}],
+            schema=_SpecBase.ARROW_SCHEMA,
+        )
+        restored = AttachOptionSpec.deserialize(legacy)
+        assert restored.required is False
+        assert restored.name == "region"
+
+    def test_older_reader_ignores_required_column(self) -> None:
+        """A four-column reader still reads a five-column batch (forward compatible)."""
+        spec = AttachOptionSpec(name="api_key", desc="API key", type=pa.string(), default=None, required=True)
+        batch, _ = deserialize_record_batch(spec.serialize())
+        legacy_read = SettingSpec.deserialize(batch)
+        assert legacy_read.name == "api_key"
+        assert legacy_read.default is None
+
+    def test_null_required_reads_as_false(self) -> None:
+        """An explicit null in the nullable column means "not required"."""
+        type_bytes = pa.schema([pa.field("value", pa.string())]).serialize().to_pybytes()
+        batch = pa.RecordBatch.from_pylist(
+            [
+                {
+                    "name": "region",
+                    "description": "",
+                    "type": type_bytes,
+                    "default_value": None,
+                    "required": None,
+                }
+            ],
+            schema=AttachOptionSpec.ARROW_SCHEMA,
+        )
+        # Round-trip through IPC the way a real peer's bytes would arrive.
+        restored, _ = deserialize_record_batch(serialize_record_batch_bytes(batch))
+        assert AttachOptionSpec.deserialize(restored).required is False
+
+
+class TestValidateRequiredAttachOptions:
+    """The shared validation helper."""
+
+    SPECS = [
+        AttachOptionSpec(name="region", desc="", type=pa.string(), default="us-east-1"),
+        AttachOptionSpec(name="api_key", desc="", type=pa.string(), default=None, required=True),
+    ]
+
+    def test_missing_required_raises(self) -> None:
+        """Omitting a required option raises with the names attached."""
+        with pytest.raises(MissingAttachOptionsError) as exc:
+            validate_required_attach_options("demo", self.SPECS, {"region": "eu-west-1"})
+        assert exc.value.missing == ["api_key"]
+        assert "'api_key'" in str(exc.value)
+
+    def test_supplied_required_passes(self) -> None:
+        """Supplying the required option is enough; defaults cover the rest."""
+        validate_required_attach_options("demo", self.SPECS, {"api_key": "secret"})
+
+    def test_case_insensitive_match(self) -> None:
+        """DuckDB lowercases ATTACH option keys; matching follows."""
+        validate_required_attach_options("demo", self.SPECS, {"API_KEY": "secret"})
+
+    def test_no_required_specs_always_passes(self) -> None:
+        """A catalog with no required options accepts an empty mapping."""
+        validate_required_attach_options("demo", [self.SPECS[0]], {})
+
+    def test_multiple_missing_reported_together(self) -> None:
+        """Every missing option is reported in one error, not one at a time."""
+        specs = [
+            AttachOptionSpec(name="api_key", desc="", type=pa.string(), default=None, required=True),
+            AttachOptionSpec(name="tenant", desc="", type=pa.string(), default=None, required=True),
+        ]
+        with pytest.raises(MissingAttachOptionsError) as exc:
+            validate_required_attach_options("demo", specs, {})
+        assert exc.value.missing == ["api_key", "tenant"]
+
+
+class _GatedCatalog(ReadOnlyCatalogInterface):
+    """Read-only catalog that cannot be attached without ``api_key``."""
+
+    catalog_name = "gated"
+    attach_option_specs = [
+        AttachOptionSpec(name="api_key", desc="API key", type=pa.string(), default=None, required=True),
+    ]
+
+
+class TestCatalogAttachEnforcement:
+    """The default ``catalog_attach`` refuses an attach missing required options."""
+
+    def test_attach_without_required_option_raises(self) -> None:
+        """The attach fails loudly rather than yielding an empty-looking catalog."""
+        with pytest.raises(MissingAttachOptionsError, match="api_key"):
+            _GatedCatalog().catalog_attach(
+                name="gated", options={}, data_version_spec=None, implementation_version=None
+            )
+
+    def test_attach_with_required_option_succeeds(self) -> None:
+        """Supplying the option attaches normally."""
+        result = _GatedCatalog().catalog_attach(
+            name="gated",
+            options={"api_key": "secret"},
+            data_version_spec=None,
+            implementation_version=None,
+        )
+        assert result.attach_opaque_data is not None

{vgi_python-0.26.0 → vgi_python-0.28.0}/tests/catalog/test_column_statistics.py

@@ -12,6 +12,7 @@ from vgi_rpc.utils import deserialize_record_batch
 from vgi.catalog.catalog_interface import (
     ColumnStatistics,
     TableColumnStatisticsResult,
+    deserialize_column_statistics,
     serialize_column_statistics,
 )
 from vgi.catalog.descriptors import ColumnStatisticsInput, Table
@@ -199,6 +200,91 @@ class TestSerializeColumnStatistics:
         assert min_type.num_fields == 1
 
 
+# ============================================================================
+# deserialize_column_statistics
+# ============================================================================
+
+
+def _roundtrip(stats: list[ColumnStatistics]) -> list[ColumnStatistics]:
+    return deserialize_column_statistics(serialize_column_statistics(stats))
+
+
+class TestDeserializeColumnStatistics:
+    """Tests that deserialization is a faithful inverse of serialization."""
+
+    def test_empty_batch(self) -> None:
+        assert _roundtrip([]) == []
+
+    def test_int_column_roundtrips(self) -> None:
+        stats = [
+            ColumnStatistics(
+                column_name="id",
+                min=pa.scalar(1, pa.int64()),
+                max=pa.scalar(100, pa.int64()),
+                has_null=False,
+                has_not_null=True,
+                distinct_count=100,
+            )
+        ]
+        (got,) = _roundtrip(stats)
+        assert got.column_name == "id"
+        assert got.min.as_py() == 1  # type: ignore[union-attr]
+        assert got.max.as_py() == 100  # type: ignore[union-attr]
+        assert got.has_null is False
+        assert got.has_not_null is True
+        assert got.distinct_count == 100
+
+    def test_string_column_roundtrips_with_string_fields(self) -> None:
+        stats = [
+            ColumnStatistics(
+                column_name="name",
+                min=pa.scalar("Alice"),
+                max=pa.scalar("Zoe"),
+                contains_unicode=True,
+                max_string_length=5,
+            )
+        ]
+        (got,) = _roundtrip(stats)
+        assert got.min.as_py() == "Alice"  # type: ignore[union-attr]
+        assert got.max.as_py() == "Zoe"  # type: ignore[union-attr]
+        assert got.contains_unicode is True
+        assert got.max_string_length == 5
+
+    def test_unknown_min_max_stays_none(self) -> None:
+        """A column with no min/max must come back as None, not a null scalar."""
+        (got,) = _roundtrip([ColumnStatistics(column_name="opaque")])
+        assert got.min is None
+        assert got.max is None
+        assert got.distinct_count is None
+        assert got.contains_unicode is None
+        assert got.max_string_length is None
+
+    def test_mixed_types_keep_their_own_union_arm(self) -> None:
+        """Several column types share one sparse union; each must decode to its own type."""
+        stats = [
+            ColumnStatistics(column_name="i", min=pa.scalar(1, pa.int64()), max=pa.scalar(9, pa.int64())),
+            ColumnStatistics(column_name="s", min=pa.scalar("a"), max=pa.scalar("z")),
+            ColumnStatistics(column_name="f", min=pa.scalar(0.5, pa.float64()), max=pa.scalar(9.5, pa.float64())),
+        ]
+        got = _roundtrip(stats)
+        assert [s.column_name for s in got] == ["i", "s", "f"]
+        assert got[0].min.as_py() == 1  # type: ignore[union-attr]
+        assert got[1].min.as_py() == "a"  # type: ignore[union-attr]
+        assert got[2].max.as_py() == 9.5  # type: ignore[union-attr]
+
+    def test_order_is_preserved(self) -> None:
+        stats = [ColumnStatistics(column_name=f"c{i}", min=pa.scalar(i, pa.int64())) for i in range(6)]
+        assert [s.column_name for s in _roundtrip(stats)] == [f"c{i}" for i in range(6)]
+
+    def test_cache_ttl_rides_in_batch_metadata_not_the_stats(self) -> None:
+        """The TTL is out-of-band; deserialization returns only the statistics."""
+        data = serialize_column_statistics([ColumnStatistics(column_name="a")], cache_max_age_seconds=60)
+        _, metadata = deserialize_record_batch(data)
+        assert metadata is not None
+        assert metadata[b"cache_max_age_seconds"] == b"60"
+        assert len(deserialize_column_statistics(data)) == 1
+
+
 # ============================================================================
 # ColumnStatisticsInput
 # ============================================================================

{vgi_python-0.26.0 → vgi_python-0.28.0}/tests/client/test_broken_pipe.py

@@ -9,6 +9,8 @@ input or producing output).
 
 from __future__ import annotations
 
+import sys
+
 import pyarrow as pa
 import pytest
 
@@ -17,6 +19,16 @@ from vgi.client.catalog_mixin import CatalogClientError
 from vgi.client.client import Client, ClientError
 
 
+def _exits_with(code: int) -> list[str]:
+    """Argv for a worker that exits immediately with ``code``, reading no input.
+
+    A real process rather than the shell's ``exit`` builtin: workers are spawned
+    without a shell, so a builtin would not resolve. Returned as argv because no
+    one string quoting convention survives both POSIX and Windows.
+    """
+    return [sys.executable, "-c", f"raise SystemExit({code})"]
+
+
 def _make_test_batch() -> pa.RecordBatch:
     """Create a simple test batch for invoking functions."""
     return pa.RecordBatch.from_pydict({"x": [1, 2, 3]})
@@ -27,9 +39,9 @@ class TestClientWorkerExitHandling:
 
     def test_client_raises_error_when_worker_exits_immediately(self) -> None:
         """Client raises ClientError when worker exits before accepting input."""
-        # Use 'exit 1' which immediately terminates without reading stdin
-        # pool=None required because 'exit 1' is a shell command, not a binary
-        client = Client("exit 1", pool=None)
+        # A worker that terminates without ever reading stdin.
+        # pool=None: the pool is for real, reusable workers.
+        client = Client(_exits_with(1), pool=None)
 
         # Worker exits before sending any output - detected either via BrokenPipeError
         # or via early exit check when reading fails
@@ -48,9 +60,8 @@ class TestClientWorkerExitHandling:
 
     def test_client_raises_error_with_useful_message(self) -> None:
         """Client error message includes useful debugging information."""
-        # Use a specific exit code
-        # pool=None required because 'exit 42' is a shell command, not a binary
-        client = Client("exit 42", pool=None)
+        # Use a specific exit code so the message can be checked for it.
+        client = Client(_exits_with(42), pool=None)
 
         try:
             client.start()
@@ -84,8 +95,8 @@ class TestCatalogMixinWorkerExitHandling:
 
     def test_catalog_invoke_raises_error_when_worker_exits(self) -> None:
         """Catalog invoke raises CatalogClientError when worker exits."""
-        # Use 'exit 1' which immediately terminates without reading stdin
-        client = Client("exit 1")
+        # A worker that terminates without ever reading stdin.
+        client = Client(_exits_with(1))
 
         # Worker exits - detected either via BrokenPipeError (shows "terminated
         # unexpectedly") or via read failure (shows "Failed to read catalog result")
@@ -94,7 +105,7 @@ class TestCatalogMixinWorkerExitHandling:
 
     def test_catalog_invoke_error_includes_useful_info(self) -> None:
         """Catalog error message includes useful debugging information."""
-        client = Client("exit 42")
+        client = Client(_exits_with(42))
 
         try:
             list(client.catalogs())