vgi-python 0.19.0__tar.gz → 0.21.0__tar.gz

{vgi_python-0.19.0 → vgi_python-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.19.0
+Version: 0.21.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.19.0 → vgi_python-0.21.0}/pyproject.toml

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

{vgi_python-0.19.0 → vgi_python-0.21.0}/tests/catalog/test_serialization.py

@@ -1275,16 +1275,22 @@ class TestScanBranchSerialization:
         assert restored.branches[1].function_name == "iceberg_scan"
         assert restored.required_extensions == ["iceberg", "httpfs"]
 
-    def test_scan_branches_result_empty_branches_rejected(self) -> None:
-        """Empty branches list is rejected at deserialize — workers must return >=1 branch."""
-        import pytest
-
+    def test_scan_branches_result_empty_branches_tolerated(self) -> None:
+        """Empty branches list round-trips cleanly.
+
+        Lenient producers (the Rust/Go/Java SDKs, tolerated by the DuckDB C++
+        client) omit the IPC stream for an empty nested list, so a strict
+        consumer must accept a zero-branch result rather than raising — otherwise
+        the Cedar proxy (the only strict Python consumer in the path) fails
+        closed on a legitimate response.
+        """
         from vgi.catalog import ScanBranchesResult
 
         empty = ScanBranchesResult(branches=[], required_extensions=[])
         batch, _ = deserialize_record_batch(empty.serialize())
-        with pytest.raises(ValueError, match="branches list must not be empty"):
-            ScanBranchesResult.deserialize(batch)
+        restored = ScanBranchesResult.deserialize(batch)
+        assert restored.branches == []
+        assert restored.required_extensions == []
 
 
 class TestSecretTypeSpecSerialization:

{vgi_python-0.19.0 → vgi_python-0.21.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.1.0"
+    assert CLIENT_PROTOCOL_VERSION == "1.2.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.1.0 client at dispatch."""
+    """A worker enforcing 99.0.0 must reject the 1.2.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.1.0) is older than the worker (99.0.0).
+    # Directional hint: the client (1.2.0) is older than the worker (99.0.0).
     assert "upgrade the VGI extension/client" in message

{vgi_python-0.19.0 → vgi_python-0.21.0}/tests/landing/describe.expected.json

@@ -3,7 +3,7 @@
     {
       "attach_options": [],
       "counts": {
-        "functions": 209,
+        "functions": 217,
         "schemas": 2,
         "tables": 59,
         "views": 3
@@ -16,6 +16,19 @@
         {
           "doc": "Example tables backed by functions",
           "functions": [
+            {
+              "args": [
+                {
+                  "desc": "Integer value to accumulate",
+                  "name": "value",
+                  "type": "int64"
+                }
+              ],
+              "doc": "Schema-disambiguation probe; the data-schema aggregate",
+              "name": "test_same_name_agg",
+              "returns": "string",
+              "type": "aggregate"
+            },
             {
               "args": [
                 {
@@ -28,6 +41,24 @@
               "name": "test_same_name_bind",
               "returns": "string",
               "type": "scalar"
+            },
+            {
+              "args": [],
+              "doc": "Schema-disambiguation probe; the data-schema cacheable producer",
+              "name": "test_same_name_cached",
+              "type": "table"
+            },
+            {
+              "args": [],
+              "doc": "Schema-disambiguation probe; the data-schema table-in-out",
+              "name": "test_same_name_transform",
+              "type": "table"
+            },
+            {
+              "args": [],
+              "doc": "Schema-disambiguation probe; the data-schema buffered function",
+              "name": "test_same_name_buffered",
+              "type": "table_in_out"
             }
           ],
           "name": "data",
@@ -371,6 +402,19 @@
               "returns": "null",
               "type": "aggregate"
             },
+            {
+              "args": [
+                {
+                  "desc": "Integer value to accumulate",
+                  "name": "value",
+                  "type": "int64"
+                }
+              ],
+              "doc": "Schema-disambiguation probe; the main-schema aggregate",
+              "name": "test_same_name_agg",
+              "returns": "string",
+              "type": "aggregate"
+            },
             {
               "args": [
                 {
@@ -2884,6 +2928,18 @@
               "name": "ten_thousand",
               "type": "table"
             },
+            {
+              "args": [],
+              "doc": "Schema-disambiguation probe; the main-schema cacheable producer",
+              "name": "test_same_name_cached",
+              "type": "table"
+            },
+            {
+              "args": [],
+              "doc": "Schema-disambiguation probe; the main-schema table-in-out",
+              "name": "test_same_name_transform",
+              "type": "table"
+            },
             {
               "args": [
                 {
@@ -3314,6 +3370,12 @@
               "doc": "Distributed sum using the buffered (Sink+Combine+Source) model",
               "name": "sum_all_columns_simple_distributed",
               "type": "table_in_out"
+            },
+            {
+              "args": [],
+              "doc": "Schema-disambiguation probe; the main-schema buffered function",
+              "name": "test_same_name_buffered",
+              "type": "table_in_out"
             }
           ],
           "name": "main",

{vgi_python-0.19.0 → vgi_python-0.21.0}/tests/test_protocol_classes.py

@@ -1149,3 +1149,61 @@ class TestAnyArrow:
         assert obj.data.value == {"key": "value"}
         assert obj.data.position == "data"
         assert obj.data.name == "data"
+
+
+class TestBindCallWireFormat:
+    """The embedded ``bind_call`` must serialize as an opaque binary IPC blob.
+
+    Every non-Python VGI implementation (the DuckDB C++ client, the Rust/Go/Java
+    SDKs) encodes ``bind_call`` as ``Bytes`` — an IPC-serialized ``BindRequest``
+    (Rust: ``ipc::read_batch(&dto.bind_call.0)``). If Python serializes it as an
+    inline Arrow *struct* instead, those workers reject the request with
+    "expected Binary array". This regression-anchors the ``bind_call`` field
+    being ``Annotated[BindRequest, ArrowType(pa.binary())]`` on every request
+    that carries one, so the Cedar proxy's re-serialized bind stays wire-
+    compatible with a non-Python backend.
+    """
+
+    @staticmethod
+    def _bind_call_arrow_type(obj: object) -> str:
+        batch = pa.ipc.open_stream(obj.serialize_to_bytes()).read_next_batch()  # type: ignore[attr-defined]
+        return str(dict((f.name, f.type) for f in batch.schema)["bind_call"])
+
+    def _make_bind(self) -> object:
+        """Build a minimal ``BindRequest`` to embed as ``bind_call``."""
+        from vgi.protocol import BindRequest, FunctionType
+
+        return BindRequest(
+            function_name="f",
+            arguments=Arguments(positional=[], named=None),
+            function_type=FunctionType.TABLE,
+        )
+
+    def test_init_request_bind_call_is_binary(self) -> None:
+        """``InitRequest.bind_call`` serializes as binary and round-trips."""
+        from vgi.protocol import InitRequest
+
+        ir = InitRequest(bind_call=self._make_bind(), output_schema=pa.schema([pa.field("x", pa.int64())]))
+        assert self._bind_call_arrow_type(ir) == "binary"
+        # round-trips back into a BindRequest
+        restored = InitRequest.deserialize_from_bytes(ir.serialize_to_bytes())
+        assert restored.bind_call.function_name == "f"
+
+    def test_table_function_requests_bind_call_is_binary(self) -> None:
+        """The ``table_function_*`` requests also serialize ``bind_call`` as binary."""
+        from vgi.protocol import (
+            TableFunctionCardinalityRequest,
+            TableFunctionDynamicToStringRequest,
+            TableFunctionStatisticsRequest,
+        )
+
+        cases = [
+            (TableFunctionCardinalityRequest, {}),
+            (TableFunctionStatisticsRequest, {}),
+            (TableFunctionDynamicToStringRequest, {"global_execution_id": b"exec"}),
+        ]
+        for cls, extra in cases:
+            obj = cls(bind_call=self._make_bind(), **extra)
+            assert self._bind_call_arrow_type(obj) == "binary", cls.__name__
+            restored = cls.deserialize_from_bytes(obj.serialize_to_bytes())
+            assert restored.bind_call.function_name == "f", cls.__name__

{vgi_python-0.19.0 → vgi_python-0.21.0}/uv.lock

@@ -2228,7 +2228,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.19.0"
+version = "0.21.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

{vgi_python-0.19.0 → vgi_python-0.21.0}/vgi/_test_fixtures/aggregate/__init__.py

@@ -32,6 +32,7 @@ from vgi._test_fixtures.aggregate.dynamic import (
 from vgi._test_fixtures.aggregate.generic import GenericSumFunction
 from vgi._test_fixtures.aggregate.listagg import ListAggFunction
 from vgi._test_fixtures.aggregate.percentile import PercentileFunction
+from vgi._test_fixtures.aggregate.same_name import SameNameDataAgg, SameNameMainAgg
 from vgi._test_fixtures.aggregate.secret_typed import SecretTypedSumFunction
 from vgi._test_fixtures.aggregate.streaming import StreamingSumFunction
 from vgi._test_fixtures.aggregate.varargs import SumAllFunction
@@ -45,6 +46,8 @@ from vgi._test_fixtures.aggregate.window import (
 __all__ = [
     "AvgFunction",
     "CountFunction",
+    "SameNameDataAgg",
+    "SameNameMainAgg",
     "DynamicAggregateFunction",
     "DynamicMLAggregateFunction",
     "GenericSumFunction",

vgi_python-0.21.0/vgi/_test_fixtures/aggregate/same_name.py

@@ -0,0 +1,139 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Same-name-in-two-schemas *aggregate* fixtures.
+
+The third member of the schema-disambiguation family, after
+:mod:`vgi._test_fixtures.scalar.same_name` (scalar) and
+:mod:`vgi._test_fixtures.table_in_out_same_name` (table-in-out + buffering).
+
+Aggregates are the widest surface of the three. Every aggregate RPC —
+``aggregate_update`` / ``_combine`` / ``_finalize`` / ``_destructor``, the four
+window calls, and the three streaming calls — resolves the function through the
+worker's single ``_resolve_aggregate`` entry point, which had no schema to work
+with: none of those request types carried one, not even ``AggregateBindRequest``.
+So an aggregate name declared in two schemas resolved to whichever the by-name
+lookup found first.
+
+Both classes register under ``test_same_name_agg``, in the ``main`` and ``data``
+schemas of the ``example`` catalog. Each returns a VARCHAR tagged with its own
+schema *and* the aggregated value, so a mis-routed call reads as the wrong tag
+rather than a plausible answer, and a call that mis-routes only partway (bind to
+one implementation, update/finalize to another) still shows up — the tag is
+stamped at ``finalize`` while the accumulation happens in ``update``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated
+
+import pyarrow as pa
+from vgi_rpc import ArrowSerializableDataclass, ArrowType
+
+from vgi.aggregate_function import AggregateFunction
+from vgi.arguments import Param, Returns
+from vgi.metadata import (
+    DistinctDependence,
+    FunctionExample,
+    NullHandling,
+    OrderDependence,
+)
+from vgi.table_function import ProcessParams
+
+# Deliberately identical in both schemas — the collision is the point.
+FUNCTION_NAME = "test_same_name_agg"
+
+
+@dataclass(kw_only=True)
+class SameNameAggState(ArrowSerializableDataclass):
+    """Running total for one group."""
+
+    total: Annotated[int, ArrowType(pa.int64())] = 0
+
+
+class _SameNameAgg(AggregateFunction[SameNameAggState]):
+    """Shared body; each subclass supplies the schema it is declared in."""
+
+    #: Schema this implementation is registered into — the tag it stamps.
+    OWNING_SCHEMA: str = ""
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[None]) -> SameNameAggState:
+        """Start each group at zero."""
+        return SameNameAggState()
+
+    @classmethod
+    def update(
+        cls,
+        states: dict[int, SameNameAggState],
+        group_ids: pa.Int64Array,
+        value: Annotated[pa.Int64Array, Param(doc="Integer value to accumulate")],
+    ) -> None:
+        """Accumulate each row's value into its group."""
+        for gid, v in zip(group_ids.to_pylist(), value.to_pylist(), strict=True):
+            if v is None or gid is None:
+                continue
+            states[gid] = SameNameAggState(total=states[gid].total + v)
+
+    @classmethod
+    def combine(
+        cls,
+        source: SameNameAggState,
+        target: SameNameAggState,
+        params: ProcessParams[None],
+    ) -> SameNameAggState:
+        """Merge two partial states."""
+        return SameNameAggState(total=source.total + target.total)
+
+    @classmethod
+    def finalize(
+        cls,
+        group_ids: pa.Int64Array,
+        states: dict[int, SameNameAggState],
+        params: ProcessParams[None],
+    ) -> Annotated[pa.RecordBatch, Returns(pa.string())]:
+        """Tag each group's total with the owning schema."""
+        results = [f"{cls.OWNING_SCHEMA}:{states[gid.as_py()].total}" for gid in group_ids]
+        return pa.record_batch({"result": pa.array(results, type=pa.string())})
+
+
+class SameNameMainAgg(_SameNameAgg):
+    """``test_same_name_agg`` as declared in the ``main`` schema."""
+
+    OWNING_SCHEMA = "main"
+
+    class Meta:
+        """Function metadata."""
+
+        name = FUNCTION_NAME
+        description = "Schema-disambiguation probe; the main-schema aggregate"
+        null_handling = NullHandling.SPECIAL
+        order_dependent = OrderDependence.NOT_ORDER_DEPENDENT
+        distinct_dependent = DistinctDependence.NOT_DISTINCT_DEPENDENT
+        examples = [
+            FunctionExample(
+                sql="SELECT example.main.test_same_name_agg(n) FROM range(3) t(n)",
+                description="Returns 'main:3'",
+            ),
+        ]
+
+
+class SameNameDataAgg(_SameNameAgg):
+    """``test_same_name_agg`` as declared in the ``data`` schema."""
+
+    OWNING_SCHEMA = "data"
+
+    class Meta:
+        """Function metadata."""
+
+        name = FUNCTION_NAME
+        description = "Schema-disambiguation probe; the data-schema aggregate"
+        null_handling = NullHandling.SPECIAL
+        order_dependent = OrderDependence.NOT_ORDER_DEPENDENT
+        distinct_dependent = DistinctDependence.NOT_DISTINCT_DEPENDENT
+        examples = [
+            FunctionExample(
+                sql="SELECT example.data.test_same_name_agg(n) FROM range(3) t(n)",
+                description="Returns 'data:3'",
+            ),
+        ]

{vgi_python-0.19.0 → vgi_python-0.21.0}/vgi/_test_fixtures/http_server.py

@@ -330,13 +330,23 @@ def main() -> None:
 
             authenticate = _optional_bearer
 
-        from vgi.worker import _get_vgi_version
-
         # Match vgi-fixture-worker (subprocess transport): always serve the
         # base ExampleWorker plus the projection_repro, schema_reconcile,
         # and accumulate fixture catalogs. Add the writable catalog when its
-        # extra is installed.
-        worker_classes: list[type] = [ExampleWorker, ProjReproWorker, SchemaReconcileWorker, AccumulateWorker]
+        # extra is installed. The twin_a/twin_b catalogs (same worker, one
+        # function name colliding across two catalogs) back
+        # scalar/same_name_catalogs.test — catalog-qualified dispatch.
+        from vgi._test_fixtures.twin_catalogs import TwinAWorker, TwinBWorker
+        from vgi.worker import _get_vgi_version
+
+        worker_classes: list[type] = [
+            ExampleWorker,
+            ProjReproWorker,
+            SchemaReconcileWorker,
+            AccumulateWorker,
+            TwinAWorker,
+            TwinBWorker,
+        ]
         try:
             from vgi._test_fixtures.writable.worker import WritableWorker
         except ImportError:

vgi_python-0.21.0/vgi/_test_fixtures/table/same_name_cached.py

@@ -0,0 +1,131 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Cacheable same-name-in-two-schemas producer fixtures.
+
+The result-cache member of the schema-disambiguation family (see
+``scalar/same_name.py``, ``table_in_out_same_name.py``, ``aggregate/same_name.py``).
+Those probe *dispatch*; this one probes the *result cache*, a distinct layer.
+
+``test_same_name_cached`` is a one-row producer table function that advertises
+``vgi.cache.ttl`` and is registered in BOTH the ``main`` and ``data`` schemas of
+the ``example`` catalog. Each schema's implementation emits a single row tagged
+with its own schema name.
+
+The result cache keyed on catalog + auth + function name with no schema
+dimension, so the two implementations produced byte-identical cache keys and one
+schema's memoized rows cross-served the other — the caching-layer twin of the
+``(schema, name)`` dispatch bug. The tag makes a cross-serve visible:
+``example.data.test_same_name_cached()`` would return a ``main`` row. With the
+schema in the key, each schema gets its own entry (so ``vgi_result_cache()``
+holds two rows for the one function name) and returns its own tag. Driven by
+``cache/same_name_schemas.test``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar, cast
+
+import pyarrow as pa
+from vgi_rpc import ArrowSerializableDataclass
+from vgi_rpc.rpc import OutputCollector
+
+from vgi.cache_control import CacheControl
+from vgi.metadata import FunctionExample
+from vgi.protocol import VgiOutputCollector
+from vgi.schema_utils import schema
+from vgi.table_function import (
+    ProcessParams,
+    TableFunctionGenerator,
+    bind_fixed_schema,
+    init_single_worker,
+)
+
+FUNCTION_NAME = "test_same_name_cached"
+
+# Long enough that the TTL never lapses mid-test.
+_TTL_SECONDS = 300
+
+
+@dataclass(slots=True, frozen=True)
+class _CachedArgs:
+    """Arguments for the cacheable same-name producer (none)."""
+
+
+@dataclass(kw_only=True)
+class _CachedState(ArrowSerializableDataclass):
+    """One-shot emit latch for the single output row."""
+
+    done: bool = False
+
+
+class _SameNameCached(TableFunctionGenerator[_CachedArgs, _CachedState]):
+    """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 = _CachedArgs
+    FIXED_SCHEMA: ClassVar[pa.Schema] = schema(tag=pa.string())
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[_CachedArgs]) -> _CachedState:
+        """Fresh latch per (real, cache-missing) invocation."""
+        return _CachedState()
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[_CachedArgs],
+        state: _CachedState,
+        out: OutputCollector,
+    ) -> None:
+        """Emit the single schema-tagged row once, advertising a cache TTL."""
+        if state.done:
+            out.finish()
+            return
+        batch = pa.RecordBatch.from_pydict({"tag": [cls.OWNING_SCHEMA]}, schema=params.output_schema)
+        cast(VgiOutputCollector, out).emit(batch, cache_control=CacheControl(ttl=_TTL_SECONDS))
+        state.done = True
+
+
+@init_single_worker
+@bind_fixed_schema
+class SameNameMainCached(_SameNameCached):
+    """``test_same_name_cached`` as declared in the ``main`` schema."""
+
+    OWNING_SCHEMA = "main"
+
+    class Meta:
+        """Function metadata."""
+
+        name = FUNCTION_NAME
+        description = "Schema-disambiguation probe; the main-schema cacheable producer"
+        categories = ["generator", "cache", "testing"]
+        examples = [
+            FunctionExample(
+                sql="SELECT * FROM example.main.test_same_name_cached()",
+                description="One cacheable row tagged 'main'",
+            ),
+        ]
+
+
+@init_single_worker
+@bind_fixed_schema
+class SameNameDataCached(_SameNameCached):
+    """``test_same_name_cached`` as declared in the ``data`` schema."""
+
+    OWNING_SCHEMA = "data"
+
+    class Meta:
+        """Function metadata."""
+
+        name = FUNCTION_NAME
+        description = "Schema-disambiguation probe; the data-schema cacheable producer"
+        categories = ["generator", "cache", "testing"]
+        examples = [
+            FunctionExample(
+                sql="SELECT * FROM example.data.test_same_name_cached()",
+                description="One cacheable row tagged 'data'",
+            ),
+        ]