vgi-python 0.30.0__tar.gz → 0.31.0__tar.gz

{vgi_python-0.30.0 → vgi_python-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.30.0
+Version: 0.31.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.30.0 → vgi_python-0.31.0}/pyproject.toml

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

{vgi_python-0.30.0 → vgi_python-0.31.0}/tests/catalog/test_serialization.py

@@ -1008,6 +1008,33 @@ class TestScanFunctionResultSerialization:
 
         assert restored.required_extensions == ["iceberg", "parquet", "httpfs"]
 
+    def test_schema_name_round_trip(self) -> None:
+        """schema_name (protocol 1.5.0) round-trips when set."""
+        original = ScanFunctionResult(
+            function_name="rowid_sequence",
+            positional_arguments=[],
+            named_arguments={},
+            schema_name="main",
+        )
+        serialized = original.serialize()
+        batch, _ = deserialize_record_batch(serialized)
+        restored = ScanFunctionResult.deserialize(batch)
+
+        assert restored.schema_name == "main"
+
+    def test_schema_name_defaults_to_none(self) -> None:
+        """schema_name is None when the caller doesn't set it (e.g. a pre-1.5.0 peer)."""
+        original = ScanFunctionResult(
+            function_name="read_parquet",
+            positional_arguments=[],
+            named_arguments={},
+        )
+        serialized = original.serialize()
+        batch, _ = deserialize_record_batch(serialized)
+        restored = ScanFunctionResult.deserialize(batch)
+
+        assert restored.schema_name is None
+
 
 class TestSettingSpecSerialization:
     """Test SettingSpec serialization round-trip."""
@@ -1176,6 +1203,10 @@ class TestArrowSchemaCorrectness:
         assert schema.field("function_name").type == pa.string()
         assert schema.field("arguments").type == pa.binary()
         assert schema.field("required_extensions").type == pa.list_(pa.string())
+        # Added in protocol 1.5.0 — nullable so a pre-1.5.0 peer's payload
+        # still deserializes (the column is simply absent there).
+        assert schema.field("schema_name").type == pa.string()
+        assert schema.field("schema_name").nullable is True
 
 
 class TestScanBranchSerialization:
@@ -1192,6 +1223,10 @@ class TestScanBranchSerialization:
         assert schema.field("branch_filter").nullable is True
         assert schema.field("writable").type == pa.bool_()
         assert schema.field("writable").nullable is False
+        # Added in protocol 1.5.0 — function-branch only; None for a
+        # catalog-table/format branch or a pre-1.5.0 peer.
+        assert schema.field("schema_name").type == pa.string()
+        assert schema.field("schema_name").nullable is True
 
     def test_scan_branches_result_schema(self) -> None:
         """ScanBranchesResult Arrow schema: branches as list<binary>, required_extensions hoisted to top-level."""
@@ -1249,6 +1284,36 @@ class TestScanBranchSerialization:
         assert restored.branch_filter == "ts >= TIMESTAMP '2026-05-15 00:00:00'"
         assert len(restored.positional_arguments) == 2
 
+    def test_scan_branch_schema_name_round_trip(self) -> None:
+        """A function branch's schema_name (protocol 1.5.0) round-trips when set."""
+        from vgi.catalog import ScanBranch
+
+        original = ScanBranch(
+            function_name="rowid_sequence",
+            positional_arguments=[],
+            named_arguments={},
+            schema_name="main",
+        )
+        batch, _ = deserialize_record_batch(original.serialize())
+        restored = ScanBranch.deserialize(batch)
+        assert restored.schema_name == "main"
+
+    def test_scan_branch_schema_name_defaults_to_none(self) -> None:
+        """schema_name is None for a branch that doesn't set it (e.g. a catalog-table branch)."""
+        from vgi.catalog import ScanBranch
+
+        original = ScanBranch(
+            function_name="",
+            positional_arguments=[],
+            named_arguments={},
+            source_catalog="lakehouse",
+            source_schema="bronze",
+            source_table="orders",
+        )
+        batch, _ = deserialize_record_batch(original.serialize())
+        restored = ScanBranch.deserialize(batch)
+        assert restored.schema_name is None
+
     def test_scan_branches_result_round_trip(self) -> None:
         """ScanBranchesResult round-trips two heterogeneous branches + required_extensions."""
         from vgi.catalog import ScanBranch, ScanBranchesResult

{vgi_python-0.30.0 → vgi_python-0.31.0}/tests/conformance/test_protocol_version.py

@@ -32,14 +32,14 @@ CLIENT_PROTOCOL_VERSION = VgiProtocol.protocol_version
 
 def test_client_protocol_version_is_canonical() -> None:
     """Sanity-check the constants this test reasons about haven't drifted apart."""
-    assert CLIENT_PROTOCOL_VERSION == "1.4.0"
+    assert CLIENT_PROTOCOL_VERSION == "1.5.0"
     # The fixture must be a genuine mismatch in the major/minor that the
     # framework compares; a patch-only difference would (correctly) pass.
     assert BAD_PROTOCOL_VERSION.split(".")[:2] != CLIENT_PROTOCOL_VERSION.split(".")[:2]
 
 
 def test_mismatched_worker_protocol_version_raises() -> None:
-    """A worker enforcing 99.0.0 must reject the 1.4.0 client at dispatch."""
+    """A worker enforcing 99.0.0 must reject the 1.5.0 client at dispatch."""
     with Client("vgi-fixture-bad-protocol-worker") as client, pytest.raises(ClientError) as exc_info:
         list(
             client.table_function(
@@ -54,5 +54,5 @@ def test_mismatched_worker_protocol_version_raises() -> None:
     assert "protocol_version mismatch" in message
     assert CLIENT_PROTOCOL_VERSION in message
     assert BAD_PROTOCOL_VERSION in message
-    # Directional hint: the client (1.3.0) is older than the worker (99.0.0).
+    # Directional hint: the client (1.5.0) is older than the worker (99.0.0).
     assert "upgrade the VGI extension/client" in message

{vgi_python-0.30.0 → vgi_python-0.31.0}/tests/test_wire_record_schema_parity.py

@@ -81,6 +81,7 @@ def _scan_function_result() -> ScanFunctionResult:
         positional_arguments=positional,
         named_arguments=named,
         required_extensions=["parquet"],
+        schema_name="main",
     )
 
 
@@ -98,6 +99,7 @@ def _scan_branch() -> ScanBranch:
         format_name="parquet",
         format_locations=["s3://bucket/a.parquet"],
         format_options={"delim": pa.scalar("|", pa.string())},
+        schema_name="main",
     )
 
 

{vgi_python-0.30.0 → vgi_python-0.31.0}/uv.lock

@@ -2569,7 +2569,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.30.0"
+version = "0.31.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

vgi_python-0.31.0/vgi/_test_fixtures/table/same_name_schemas.py

@@ -0,0 +1,136 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Same-name-in-two-schemas producer, backing a DECLARATIVE TABLE in each schema.
+
+The table-dispatch member of the schema-disambiguation family (see
+``scalar/same_name.py``, ``table_in_out_same_name.py``, ``aggregate/same_name.py``,
+and ``table/same_name_cached.py`` for the result-cache member). Those probe a
+function called directly (or the result cache); this one probes
+``catalog_table_scan_function_get``/``catalog_table_scan_branches_get`` — the RPC
+pair that tells a client which function backs a *declarative catalog table*.
+
+``test_same_name_table_scan`` is a one-row producer registered under the SAME
+NAME in BOTH the ``main`` and ``data`` schemas of the ``example`` catalog, each
+emitting a single row tagged with its own schema. A declarative ``Table``
+descriptor named ``test_same_name_table`` is registered in each schema too, each
+backed by that schema's own implementation.
+
+This is also the end-to-end regression guard for protocol 1.5.0's
+``ScanFunctionResult.schema_name``/``ScanBranch.schema_name``: the C++ extension
+now prefers the worker-declared schema over its old table-schema/default-schema
+heuristic when resolving which catalog entry ``function_name`` refers to. A
+worker that regressed to leaving ``schema_name`` unset, or a client that stopped
+consuming it, would silently fall back to the old heuristic — which still
+happens to get *this* two-schema case right (the table's own schema is tried
+first and always matches here), so a regression here would show up not as a
+wrong row, but as the exact filter/projection-pushdown breakage this session's
+own investigation traced to passing the wire-parsed schema string somewhere the
+resolver couldn't safely reuse it — see ``cache/filter_pushdown_keys.test`` and
+this table family's own pushdown assertions below. Driven by
+``table/same_name_schemas.test``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+import pyarrow as pa
+from vgi_rpc import ArrowSerializableDataclass
+from vgi_rpc.rpc import OutputCollector
+
+from vgi.metadata import FunctionExample
+from vgi.schema_utils import schema
+from vgi.table_function import (
+    ProcessParams,
+    TableFunctionGenerator,
+    bind_fixed_schema,
+    init_single_worker,
+)
+
+FUNCTION_NAME = "test_same_name_table_scan"
+TABLE_NAME = "test_same_name_table"
+
+
+@dataclass(slots=True, frozen=True)
+class _SameNameTableArgs:
+    """Arguments for the same-name table producer (none)."""
+
+
+@dataclass(kw_only=True)
+class _SameNameTableState(ArrowSerializableDataclass):
+    """One-shot emit latch for the single output row."""
+
+    done: bool = False
+
+
+class _SameNameTableScan(TableFunctionGenerator[_SameNameTableArgs, _SameNameTableState]):
+    """Shared body; each subclass supplies the schema it is declared in."""
+
+    #: Schema this implementation is declared in — the tag it stamps.
+    OWNING_SCHEMA: ClassVar[str] = ""
+
+    FunctionArguments = _SameNameTableArgs
+    FIXED_SCHEMA: ClassVar[pa.Schema] = schema(tag=pa.string())
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[_SameNameTableArgs]) -> _SameNameTableState:
+        """Fresh latch per invocation."""
+        return _SameNameTableState()
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[_SameNameTableArgs],
+        state: _SameNameTableState,
+        out: OutputCollector,
+    ) -> None:
+        """Emit the single schema-tagged row once."""
+        if state.done:
+            out.finish()
+            return
+        batch = pa.RecordBatch.from_pydict({"tag": [cls.OWNING_SCHEMA]}, schema=params.output_schema)
+        out.emit(batch)
+        state.done = True
+
+
+@init_single_worker
+@bind_fixed_schema
+class SameNameTableMainScan(_SameNameTableScan):
+    """``test_same_name_table_scan`` as declared in the ``main`` schema."""
+
+    OWNING_SCHEMA = "main"
+
+    class Meta:
+        """Function metadata."""
+
+        name = FUNCTION_NAME
+        description = "Schema-disambiguation probe; the main-schema table producer"
+        categories = ["generator", "testing"]
+        examples = [
+            FunctionExample(
+                sql="SELECT * FROM example.main.test_same_name_table",
+                description="One row tagged 'main'",
+            ),
+        ]
+
+
+@init_single_worker
+@bind_fixed_schema
+class SameNameTableDataScan(_SameNameTableScan):
+    """``test_same_name_table_scan`` as declared in the ``data`` schema."""
+
+    OWNING_SCHEMA = "data"
+
+    class Meta:
+        """Function metadata."""
+
+        name = FUNCTION_NAME
+        description = "Schema-disambiguation probe; the data-schema table producer"
+        categories = ["generator", "testing"]
+        examples = [
+            FunctionExample(
+                sql="SELECT * FROM example.data.test_same_name_table",
+                description="One row tagged 'data'",
+            ),
+        ]

{vgi_python-0.30.0 → vgi_python-0.31.0}/vgi/_test_fixtures/worker.py

@@ -254,6 +254,10 @@ from vgi._test_fixtures.table.same_name_cached import (
     SameNameDataCached,
     SameNameMainCached,
 )
+from vgi._test_fixtures.table.same_name_schemas import (
+    SameNameTableDataScan,
+    SameNameTableMainScan,
+)
 from vgi._test_fixtures.table.tt_pushdown import (
     _TT_SCHEMA,
     TimeTravelPushdownFunction,
@@ -648,6 +652,7 @@ _EXAMPLE_CATALOG = Catalog(
                 SameNameMainBuffered,
                 SameNameMainAgg,
                 SameNameMainCached,
+                SameNameTableMainScan,
                 ScaleBySettingFunction,
                 SecretFieldFunction,
                 SmartFormatPrefixFunction,
@@ -733,6 +738,17 @@ _EXAMPLE_CATALOG = Catalog(
                     parameter_docs={"n": "Number of rows to generate"},
                 ),
             ],
+            tables=[
+                # Schema-disambiguation probe (table dispatch): same registered
+                # table name as the -schema table below, backed by this
+                # schema's own scan-function implementation — see
+                # same_name_schemas.py.
+                Table(
+                    name="test_same_name_table",
+                    function=SameNameTableMainScan,
+                    comment="Schema-disambiguation probe; the main-schema table",
+                ),
+            ],
         ),
         Schema(
             name="data",
@@ -747,8 +763,17 @@ _EXAMPLE_CATALOG = Catalog(
                 SameNameDataBuffered,
                 SameNameDataAgg,
                 SameNameDataCached,
+                SameNameTableDataScan,
             ],
             tables=[
+                # Schema-disambiguation probe (table dispatch): same registered
+                # table name as the main-schema table above, backed by this
+                # schema's own scan-function implementation.
+                Table(
+                    name="test_same_name_table",
+                    function=SameNameTableDataScan,
+                    comment="Schema-disambiguation probe; the data-schema table",
+                ),
                 # Function-backed table: schema derived via bind()
                 Table(
                     name="large_sequence",
@@ -1577,11 +1602,13 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                         function_name="sequence",
                         positional_arguments=[pa.scalar(50)],
                         named_arguments={},
+                        schema_name="main",
                     ),
                     ScanBranch(
                         function_name="sequence",
                         positional_arguments=[pa.scalar(50)],
                         named_arguments={},
+                        schema_name="main",
                     ),
                 ],
                 required_extensions=[],
@@ -1598,11 +1625,13 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                         function_name="split_sequence",
                         positional_arguments=[],
                         named_arguments={"n": pa.scalar(30), "splits": pa.scalar(6)},
+                        schema_name="main",
                     ),
                     ScanBranch(
                         function_name="sequence",
                         positional_arguments=[pa.scalar(20)],
                         named_arguments={},
+                        schema_name="main",
                     ),
                 ],
                 required_extensions=[],
@@ -1619,12 +1648,14 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                         positional_arguments=[pa.scalar(100)],
                         named_arguments={},
                         branch_filter="n < 50",
+                        schema_name="main",
                     ),
                     ScanBranch(
                         function_name="sequence",
                         positional_arguments=[pa.scalar(100)],
                         named_arguments={},
                         branch_filter="n >= 50",
+                        schema_name="main",
                     ),
                 ],
                 required_extensions=[],
@@ -1641,11 +1672,15 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                         function_name="sequence",
                         positional_arguments=[pa.scalar(50)],
                         named_arguments={},
+                        schema_name="main",
                     ),
                     ScanBranch(
                         function_name="read_parquet",
                         positional_arguments=[pa.scalar(f"{_BRANCH_DIR}/vgi_hetero_branch.parquet", pa.string())],
                         named_arguments={},
+                        # read_parquet is a native DuckDB function delegated straight
+                        # through — it has no VGI-side schema of its own to report.
+                        schema_name=None,
                     ),
                 ],
                 required_extensions=[],
@@ -1684,6 +1719,9 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                             # non-null count moves.
                             "nullstr": pa.scalar("row_2", pa.string()),
                         },
+                        # Format branch, not a function branch — schema_name is
+                        # function-branch-only and doesn't apply here.
+                        schema_name=None,
                     ),
                 ],
                 required_extensions=[],
@@ -1701,11 +1739,15 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                         function_name="sequence",
                         positional_arguments=[pa.scalar(50)],
                         named_arguments={},
+                        schema_name="main",
                     ),
                     ScanBranch(
                         function_name="iceberg_scan",
                         positional_arguments=[pa.scalar(f"{_BRANCH_DIR}/vgi_iceberg_branch", pa.string())],
                         named_arguments={},
+                        # iceberg_scan is a native DuckDB function delegated
+                        # straight through — no VGI-side schema of its own.
+                        schema_name=None,
                     ),
                 ],
                 required_extensions=["iceberg"],
@@ -1729,12 +1771,14 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                         positional_arguments=[pa.scalar(10)],
                         named_arguments={},
                         writable=True,
+                        schema_name="main",
                     ),
                     ScanBranch(
                         function_name="sequence",
                         positional_arguments=[pa.scalar(10)],
                         named_arguments={},
                         writable=True,
+                        schema_name="main",
                     ),
                 ],
                 required_extensions=[],
@@ -1751,11 +1795,15 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                         function_name="sequence",
                         positional_arguments=[pa.scalar(50)],
                         named_arguments={},
+                        schema_name="main",
                     ),
                     ScanBranch(
                         function_name="read_csv_auto",
                         positional_arguments=[pa.scalar(f"{_BRANCH_DIR}/vgi_nopushdown_branch.csv", pa.string())],
                         named_arguments={},
+                        # read_csv_auto is a native DuckDB function delegated
+                        # straight through — no VGI-side schema of its own.
+                        schema_name=None,
                     ),
                 ],
                 required_extensions=[],
@@ -1773,16 +1821,19 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                         function_name="read_parquet",
                         positional_arguments=[pa.scalar(f"{_BRANCH_DIR}/vgi_recon_a_b.parquet", pa.string())],
                         named_arguments={},
+                        schema_name=None,
                     ),
                     ScanBranch(
                         function_name="read_parquet",
                         positional_arguments=[pa.scalar(f"{_BRANCH_DIR}/vgi_recon_b_a.parquet", pa.string())],
                         named_arguments={},
+                        schema_name=None,
                     ),
                     ScanBranch(
                         function_name="read_parquet",
                         positional_arguments=[pa.scalar(f"{_BRANCH_DIR}/vgi_recon_a_only.parquet", pa.string())],
                         named_arguments={},
+                        schema_name=None,
                     ),
                 ],
                 required_extensions=[],
@@ -1823,6 +1874,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name="versioned_data_scan",
                 positional_arguments=[pa.scalar(version)],
                 named_arguments={},
+                schema_name="main",
             )
 
         # cache_versioned: AT → version arg, same as versioned_data but the scan
@@ -1833,6 +1885,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name="cache_versioned_scan",
                 positional_arguments=[pa.scalar(version)],
                 named_arguments={},
+                schema_name="main",
             )
 
         # Columns-based time-travel + pushdown: resolve AT → version and pass it
@@ -1843,6 +1896,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name="tt_pushdown_cols_scan",
                 positional_arguments=[pa.scalar(version)],
                 named_arguments={},
+                schema_name="main",
             )
 
         # Handle the versioned_constraints table with time travel
@@ -1852,6 +1906,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name="versioned_constraints_scan",
                 positional_arguments=[pa.scalar(version)],
                 named_arguments={},
+                schema_name="main",
             )
 
         # rff_parquet — single-branch native read_parquet delegation.
@@ -1860,6 +1915,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name="read_parquet",
                 positional_arguments=[pa.scalar(f"{_BRANCH_DIR}/rff_seg.parquet", pa.string())],
                 named_arguments={},
+                schema_name=None,
             )
 
         # rff_hive / rff_hive_mixed — native read_parquet over a Hive glob.
@@ -1868,6 +1924,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name="read_parquet",
                 positional_arguments=[pa.scalar(f"{_BRANCH_DIR}/rff_hive/*/*/*.parquet", pa.string())],
                 named_arguments={"hive_partitioning": pa.scalar(True)},
+                schema_name=None,
             )
 
         # Reject AT clause on tables that don't support time travel
@@ -1880,6 +1937,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name="sequence",
                 positional_arguments=[pa.scalar(10)],
                 named_arguments={},
+                schema_name="main",
             )
 
         # Handle "numbers" and "volatile_numbers" — both use sequence(100)
@@ -1888,6 +1946,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name="sequence",
                 positional_arguments=[pa.scalar(100)],
                 named_arguments={},
+                schema_name="main",
             )
 
         # funny_numbers — 123456 rows from sequence; statistics deliberately NOT set on
@@ -1897,6 +1956,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name="sequence",
                 positional_arguments=[pa.scalar(123456)],
                 named_arguments={},
+                schema_name="main",
             )
 
         # Constraint example tables — simple static scan functions
@@ -1923,6 +1983,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name=_static_scan_tables[name.lower()],
                 positional_arguments=[],
                 named_arguments={},
+                schema_name="main",
             )
 
         # Row ID test tables
@@ -1942,6 +2003,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                     "layout": pa.scalar(opts["layout"]),
                     "row_id_type": pa.scalar(opts["row_id_type"]),
                 },
+                schema_name="main",
             )
 
         # Late-materialization tables → late_materialization scan function.
@@ -1957,6 +2019,7 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
                 function_name="late_materialization",
                 positional_arguments=[pa.scalar(1000)],
                 named_arguments=late_mat_tables[name.lower()],
+                schema_name="main",
             )
 
         return super().table_scan_function_get(