vgi-python 0.8.1__py3-none-any.whl → 0.8.3__py3-none-any.whl

vgi/__init__.py

@@ -39,6 +39,7 @@ from vgi.arguments import (
     Param,
     Returns,
     TableInput,
+    TaggedUnion,
 )
 from vgi.auth import AuthContext, CallContext
 from vgi.metadata import (
@@ -143,6 +144,7 @@ __all__ = [
     "TableInOutGenerator",
     "TableInput",
     "TableInputValidationError",
+    "TaggedUnion",
     "TypeMismatchError",
     "Worker",
     "functions_to_arrow",

vgi/_test_fixtures/bad_enum.py

@@ -0,0 +1,72 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Fixture worker that deliberately advertises an unrecognized enum value.
+
+This fixture exercises the C++ extension's *wire-enum validation* end-to-end:
+the catalog-metadata parser (``ParseFunctionInfo`` in
+``vgi/src/vgi_catalog_api.cpp``) must reject an enum string it does not
+recognize with a loud ``IOException`` rather than silently falling back to a
+default. A silent fallback would run with behavior inconsistent with what the
+worker declared (e.g. treating a ``SPECIAL`` null-handling function as
+``DEFAULT``).
+
+The trick is entirely Python-side and needs no extension rebuild. The normal
+metadata path can only ever emit valid enum names because the values come from
+typed Python ``Enum`` members. To get a bogus string onto the wire we override
+:meth:`ExampleCatalog._function_to_info` for one scalar function (``double``)
+and swap its ``null_handling`` for :class:`_BogusNullHandling.WEIRD` — a real
+``Enum`` member whose ``.name`` is ``"WEIRD"``. The vgi-rpc serializer converts
+any ``Enum`` field to ``value.name`` (see ``ArrowSerializableDataclass``), so
+``"WEIRD"`` lands in the ``null_handling`` Arrow column and the C++ parser
+trips on it the moment the ``double`` function's metadata is loaded.
+
+Otherwise this is a drop-in replacement for ``vgi-fixture-worker``: every other
+function and the catalog are inherited unchanged from :class:`ExampleWorker`,
+so any function except ``double`` still resolves normally.
+
+Registered as the ``vgi-fixture-bad-enum-worker`` entry point.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from enum import Enum
+
+from vgi._test_fixtures.worker import ExampleCatalog, ExampleWorker
+from vgi.catalog.catalog_interface import FunctionInfo
+
+# The scalar function whose null_handling we corrupt. Tests reference this name
+# to force the broken metadata onto the parse path.
+BAD_ENUM_FUNCTION = "double"
+
+
+class _BogusNullHandling(Enum):
+    """An enum member whose ``.name`` is a value the C++ parser cannot map."""
+
+    WEIRD = "WEIRD"
+
+
+class BadEnumCatalog(ExampleCatalog):
+    """ExampleCatalog that advertises a bogus null_handling for one function."""
+
+    def _function_to_info(self, func_cls: type, schema_name: str) -> FunctionInfo:
+        info = super()._function_to_info(func_cls, schema_name)
+        if info.name == BAD_ENUM_FUNCTION and info.null_handling is not None:
+            # FunctionInfo is frozen; replace() returns a corrupted copy.
+            return replace(info, null_handling=_BogusNullHandling.WEIRD)  # type: ignore[arg-type]
+        return info
+
+
+class BadEnumWorker(ExampleWorker):
+    """ExampleWorker that serves the example catalog with one bad enum value."""
+
+    catalog_interface = BadEnumCatalog
+
+
+def main() -> None:
+    """Run the bad-enum fixture worker process."""
+    BadEnumWorker.main()
+
+
+if __name__ == "__main__":
+    main()

vgi/_test_fixtures/narrow_bind/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Narrow-bind reproducer fixture.
+
+Exposes a catalog whose virtual table advertises *more* columns in its
+listing (``catalog_schema_contents_tables`` / ``catalog_table_get``) than
+its scan function returns from ``on_bind``. A client that trusts the bind
+``output_schema`` without checking it against the planned catalog columns
+indexes past the end of the worker's narrower batch in
+``ArrowTableFunction::ArrowToDuckDB`` and SIGSEGVs. The fix makes the
+client fail closed at bind with a clear ``BinderException``.
+
+Driven by ``test/sql/integration/narrow_bind_mismatch.test`` in
+``~/Development/vgi``.
+"""

vgi/_test_fixtures/narrow_bind/worker.py

@@ -0,0 +1,237 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Narrow-bind reproducer worker.
+
+Two virtual tables, each backed by a table function:
+
+  * ``mismatch`` — advertises columns ``{id, val}`` in its catalog listing
+    but its scan function ``narrow_scan`` binds to ``{id}`` only. This is
+    the inconsistency that used to segfault the client at scan time
+    (``ArrowTableFunction::ArrowToDuckDB`` walking off the end of the
+    worker's 1-column batch). The client must now refuse it at bind with a
+    clear ``BinderException``.
+
+  * ``consistent`` — advertises ``{id, val}`` and its scan function
+    ``wide_scan`` binds to ``{id, val}``. Positive control: this must keep
+    working unchanged.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated, Any
+
+import pyarrow as pa
+from vgi_rpc import ArrowSerializableDataclass
+from vgi_rpc.rpc import OutputCollector
+
+from vgi import Worker
+from vgi.arguments import Arg
+from vgi.catalog import Catalog, Schema
+from vgi.catalog.catalog_interface import (
+    AttachOpaqueData,
+    ReadOnlyCatalogInterface,
+    ScanFunctionResult,
+    SchemaInfo,
+    SchemaObjectType,
+    SerializedSchema,
+    TableInfo,
+    TransactionOpaqueData,
+)
+from vgi.function import Function
+from vgi.invocation import BindResponse
+from vgi.table_function import (
+    BindParams,
+    ProcessParams,
+    TableFunctionGenerator,
+    init_single_worker,
+)
+
+CATALOG_NAME = "narrow_bind"
+
+# What the catalog advertises for both tables: two columns.
+_TABLE_SCHEMA: pa.Schema = pa.schema([pa.field("id", pa.int64()), pa.field("val", pa.int64())])
+# What the narrow scan function actually binds to: one column.
+_NARROW_BIND_SCHEMA: pa.Schema = pa.schema([pa.field("id", pa.int64())])
+
+
+@dataclass(kw_only=True)
+class _State(ArrowSerializableDataclass):
+    done: bool = False
+
+
+@dataclass(frozen=True)
+class _Args:
+    count: Annotated[int, Arg(0, doc="rows", ge=0)]
+
+
+@init_single_worker
+class NarrowScan(TableFunctionGenerator[_Args, _State]):
+    """Binds to a NARROWER schema than the catalog advertises (the bug)."""
+
+    class Meta:
+        name = "narrow_scan"
+        description = "bind reports a narrower schema than the table advertises"
+
+    @classmethod
+    def on_bind(cls, params: BindParams[_Args]) -> BindResponse:
+        return BindResponse(output_schema=_NARROW_BIND_SCHEMA)
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[_Args]) -> _State:
+        return _State()
+
+    @classmethod
+    def process(cls, params: ProcessParams[_Args], state: _State, out: OutputCollector) -> None:
+        if state.done:
+            out.finish()
+            return
+        state.done = True
+        out.emit(pa.RecordBatch.from_pydict({"id": [0, 1, 2]}, schema=params.output_schema))
+
+
+@init_single_worker
+class WideScan(TableFunctionGenerator[_Args, _State]):
+    """Binds to the full advertised schema (positive control — must work)."""
+
+    class Meta:
+        name = "wide_scan"
+        description = "bind matches the table's advertised schema"
+
+    @classmethod
+    def on_bind(cls, params: BindParams[_Args]) -> BindResponse:
+        return BindResponse(output_schema=_TABLE_SCHEMA)
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[_Args]) -> _State:
+        return _State()
+
+    @classmethod
+    def process(cls, params: ProcessParams[_Args], state: _State, out: OutputCollector) -> None:
+        if state.done:
+            out.finish()
+            return
+        state.done = True
+        out.emit(pa.RecordBatch.from_pydict({"id": [0, 1, 2], "val": [10, 20, 30]}, schema=params.output_schema))
+
+
+_FUNCTIONS: list[type[Function]] = [NarrowScan, WideScan]
+
+_CATALOG = Catalog(
+    name=CATALOG_NAME,
+    default_schema="main",
+    schemas=[
+        Schema(
+            name="main",
+            comment="narrow-bind reproducer catalog",
+            functions=list(_FUNCTIONS),
+            tables=[],
+        ),
+    ],
+)
+
+
+def _serialize_schema(s: pa.Schema) -> bytes:
+    sink = pa.BufferOutputStream()
+    with pa.ipc.new_stream(sink, s):
+        pass
+    return sink.getvalue().to_pybytes()
+
+
+# table name -> scan function name. Both advertise _TABLE_SCHEMA (2 cols).
+_TABLE_FUNCTIONS = {
+    "mismatch": "narrow_scan",
+    "consistent": "wide_scan",
+}
+
+
+class NarrowBindCatalog(ReadOnlyCatalogInterface):
+    catalog = _CATALOG
+    catalog_name = CATALOG_NAME
+
+    def _info(self, table_name: str) -> TableInfo:
+        return TableInfo(
+            comment=f"narrow-bind reproducer table -> {_TABLE_FUNCTIONS[table_name]}",
+            tags={},
+            name=table_name,
+            schema_name="main",
+            columns=SerializedSchema(_serialize_schema(_TABLE_SCHEMA)),
+            not_null_constraints=[],
+            unique_constraints=[],
+            check_constraints=[],
+        )
+
+    def schemas(
+        self, *, attach_opaque_data: AttachOpaqueData, transaction_opaque_data: TransactionOpaqueData | None
+    ) -> list[SchemaInfo]:
+        infos = super().schemas(attach_opaque_data=attach_opaque_data, transaction_opaque_data=transaction_opaque_data)
+        for i, info in enumerate(infos):
+            if info.name == "main":
+                infos[i] = SchemaInfo(
+                    attach_opaque_data=info.attach_opaque_data,
+                    name=info.name,
+                    comment=info.comment,
+                    tags=info.tags,
+                    estimated_object_count={
+                        **(info.estimated_object_count or {}),
+                        "table": len(_TABLE_FUNCTIONS),
+                    },
+                )
+        return infos
+
+    def schema_contents(
+        self,
+        *,
+        attach_opaque_data: AttachOpaqueData,
+        transaction_opaque_data: TransactionOpaqueData | None,
+        name: str,
+        type: Any,
+    ) -> Any:
+        if name.lower() == "main" and type == SchemaObjectType.TABLE:
+            return [self._info(table_name) for table_name in _TABLE_FUNCTIONS]
+        return super().schema_contents(
+            attach_opaque_data=attach_opaque_data, transaction_opaque_data=transaction_opaque_data, name=name, type=type
+        )
+
+    def table_get(
+        self,
+        *,
+        attach_opaque_data: AttachOpaqueData,
+        transaction_opaque_data: TransactionOpaqueData | None,
+        schema_name: str,
+        name: str,
+        at_unit: str | None = None,
+        at_value: str | None = None,
+    ) -> TableInfo | None:
+        if schema_name.lower() != "main":
+            return None
+        if name in _TABLE_FUNCTIONS:
+            return self._info(name)
+        return None
+
+    def table_scan_function_get(
+        self,
+        *,
+        attach_opaque_data: AttachOpaqueData,
+        transaction_opaque_data: TransactionOpaqueData | None,
+        schema_name: str,
+        name: str,
+        at_unit: str | None,
+        at_value: str | None,
+    ) -> ScanFunctionResult:
+        fn = _TABLE_FUNCTIONS.get(name)
+        if fn is None:
+            raise ValueError(f"unknown narrow-bind reproducer table: {name}")
+        return ScanFunctionResult(
+            function_name=fn,
+            positional_arguments=[pa.scalar(3, type=pa.int64())],
+            named_arguments={},
+            required_extensions=[],
+        )
+
+
+class NarrowBindWorker(Worker):
+    catalog_interface = NarrowBindCatalog
+    catalog_name = CATALOG_NAME
+    catalog = _CATALOG
+    functions = list(_FUNCTIONS)

vgi/_test_fixtures/scalar/__init__.py

@@ -52,6 +52,7 @@ from vgi._test_fixtures.scalar.null_handling import (
 from vgi._test_fixtures.scalar.random_demo import (
     BernoulliFunction,
     HashSeedFunction,
+    QuerySeedFunction,
     RandomBytesFunction,
     RandomIntFunction,
 )
@@ -102,6 +103,7 @@ __all__ = [
     "PairTypeIntIntFunction",
     "PairTypeIntStrFunction",
     "PairTypeStrStrFunction",
+    "QuerySeedFunction",
     "RandomBytesFunction",
     "RandomIntFunction",
     "ReturnSecretValueFunction",

vgi/_test_fixtures/scalar/random_demo.py

@@ -136,6 +136,50 @@ class HashSeedFunction(ScalarFunction):
         return pa.array([seed + i for i in range(_length)], type=pa.int64())
 
 
+class QuerySeedFunction(ScalarFunction):
+    """Adds a per-query-stable seed to each input value.
+
+    Demonstrates ``FunctionStability.CONSISTENT_WITHIN_QUERY`` — the only
+    fixture that emits this stability variant. Semantically the value is fixed
+    for the duration of a single query but may differ across queries (like
+    ``now()``). DuckDB has no behavioral consumer that this fixture asserts; it
+    exists so the wire path for the third stability value stays exercised and
+    so other-language workers must specify it.
+
+    Example:
+        SQL:    SELECT query_seed(value) FROM data
+
+    """
+
+    class Meta:
+        """Function metadata."""
+
+        name = "query_seed"
+        description = "Add a per-query-stable seed to each value (demonstrates CONSISTENT_WITHIN_QUERY stability)"
+        stability = FunctionStability.CONSISTENT_WITHIN_QUERY
+        examples = [
+            FunctionExample(
+                sql="SELECT query_seed(value) FROM data",
+                description="Offset each value by a seed that is constant within a query",
+            ),
+        ]
+
+    @classmethod
+    def compute(
+        cls,
+        value: Annotated[pa.Int64Array, Param(doc="Value to offset")],
+    ) -> Annotated[pa.Int64Array, Returns()]:
+        """Add a fixed per-query offset to each value.
+
+        The offset is deterministic here (a constant) so SQL tests have a
+        stable expected output; the stability flag is what is under test, not
+        the numeric result.
+        """
+        import pyarrow.compute as pc
+
+        return pc.add(value, 1000)
+
+
 class RandomBytesFunction(ScalarFunction):
     """Generates deterministic pseudo-random binary blobs from a seed."""
 

vgi/_test_fixtures/table/__init__.py

@@ -82,6 +82,7 @@ from vgi._test_fixtures.table.pairs import (
 from vgi._test_fixtures.table.partition_columns import (
     CountryPartitionedSalesFunction,
     DisjointRangePartitionedFunction,
+    OverlappingRangePartitionedFunction,
     PartitionedWithExplicitOverrideFunction,
     RegionYearPartitionedFunction,
 )
@@ -182,6 +183,7 @@ __all__ = [
     "NestedSequenceFunction",
     "NonMonotoneBatchIndexFunction",
     "OrderEchoFunction",
+    "OverlappingRangePartitionedFunction",
     "PartitionedBatchIndexFunction",
     "PartitionedBatchIndexMarkedFunction",
     "PartitionedFixedOrderFunction",

vgi/_test_fixtures/table/partition_columns.py

@@ -33,6 +33,11 @@ Fixtures:
   disjoint integer range. Verifies the wire path; DuckDB falls back to
   ``HASH_GROUP_BY`` for GROUP BY queries against it.
 
+* :class:`OverlappingRangePartitionedFunction` — declares
+  ``OVERLAPPING_PARTITIONS`` (the only fixture that does). Consecutive
+  chunks share ``key`` values. Wire-level only; DuckDB falls back to
+  ``HASH_GROUP_BY``.
+
 All fixtures use the in-memory state pattern (no work-queue / no
 stream_state) — they're simpler than the v1 partitioned_batch_index
 since the v2 plan is about correctness of the partition contract,
@@ -470,3 +475,99 @@ class DisjointRangePartitionedFunction(TableFunctionGenerator[_DisjointArgs, _Di
         )
         out.emit(batch)
         state.current_idx = rpp
+
+
+# =============================================================================
+# OVERLAPPING_PARTITIONS — wire-level only
+# =============================================================================
+
+
+@dataclass(slots=True, frozen=True)
+class _OverlappingArgs:
+    """Arguments for ``overlapping_range_partitioned``."""
+
+    partitions: Annotated[int, Arg(0, doc="Number of overlapping partitions", ge=1)]
+    rows_per_partition: Annotated[int, Arg("rows_per_partition", default=10, doc="Rows per partition", ge=1)]
+
+
+@dataclass(kw_only=True)
+class _OverlappingState(ArrowSerializableDataclass):
+    current_partition_idx: int = -1
+    current_idx: int = 0
+    started: bool = False
+
+
+@bind_fixed_schema
+@_cardinality_from_count
+class OverlappingRangePartitionedFunction(TableFunctionGenerator[_OverlappingArgs, _OverlappingState]):
+    """Per-chunk *overlapping* integer ranges on ``key``.
+
+    Each chunk N emits ``key`` values in ``[N*500, N*500 + rows)``. With the
+    default ``rows_per_partition`` of 10 the ranges are disjoint, but callers
+    pass ``rows_per_partition > 500`` to make consecutive chunks overlap on
+    ``key`` — distinguishing this from
+    :class:`DisjointRangePartitionedFunction`.
+
+    Declares ``OVERLAPPING_PARTITIONS``. Like DISJOINT, DuckDB has no consumer
+    for OVERLAPPING today, so GROUP BY queries fall back to ``HASH_GROUP_BY``;
+    the value's purpose here is to keep the wire path (declaration, per-batch
+    min/max metadata, C++ extraction → ``get_partition_info``) exercised so
+    other-language workers must specify it. This is the only fixture that emits
+    ``OVERLAPPING_PARTITIONS``.
+    """
+
+    FIXED_SCHEMA: ClassVar[pa.Schema] = pa.schema(
+        [
+            partition_field("key", pa.int64()),
+            pa.field("value", pa.int64()),
+        ]
+    )
+
+    class Meta:
+        name = "overlapping_range_partitioned"
+        description = (
+            "Overlapping per-chunk integer ranges on ``key``. Declares "
+            "OVERLAPPING_PARTITIONS (wire-level only; DuckDB falls back to "
+            "HASH_GROUP_BY for now)."
+        )
+        categories = ["generator", "partitioning", "testing"]
+        partition_kind = PartitionKind.OVERLAPPING_PARTITIONS
+
+    @classmethod
+    def on_init(cls, params: InitParams[_OverlappingArgs]) -> GlobalInitResponse:
+        items = [struct.pack(_QUEUE_ITEM_FMT, i) for i in range(params.args.partitions)]
+        params.storage.queue_push(items)
+        return GlobalInitResponse()
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[_OverlappingArgs]) -> _OverlappingState:
+        return _OverlappingState()
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[_OverlappingArgs],
+        state: _OverlappingState,
+        out: OutputCollector,
+    ) -> None:
+        if not state.started or state.current_idx >= params.args.rows_per_partition:
+            item = params.storage.queue_pop()
+            if item is None:
+                out.finish()
+                return
+            (state.current_partition_idx,) = struct.unpack(_QUEUE_ITEM_FMT, item)
+            state.current_idx = 0
+            state.started = True
+
+        rpp = params.args.rows_per_partition
+        # Stride of 500 (< rpp when callers want overlap) makes consecutive
+        # chunks share key values.
+        base = state.current_partition_idx * 500
+        keys = [base + i for i in range(rpp)]
+        values = [state.current_partition_idx * 10 + i for i in range(rpp)]
+        batch = pa.RecordBatch.from_pydict(
+            {"key": keys, "value": values},
+            schema=cls.FIXED_SCHEMA,
+        )
+        out.emit(batch)
+        state.current_idx = rpp

vgi/_test_fixtures/worker.py

@@ -86,6 +86,7 @@ from vgi._test_fixtures.scalar import (
     PairTypeIntIntFunction,
     PairTypeIntStrFunction,
     PairTypeStrStrFunction,
+    QuerySeedFunction,
     RandomBytesFunction,
     RandomIntFunction,
     ReturnSecretValueFunction,
@@ -146,6 +147,7 @@ from vgi._test_fixtures.table import (
     NestedSequenceFunction,
     NonMonotoneBatchIndexFunction,
     OrderEchoFunction,
+    OverlappingRangePartitionedFunction,
     PartitionedBatchIndexFunction,
     PartitionedBatchIndexMarkedFunction,
     PartitionedFixedOrderFunction,
@@ -385,6 +387,7 @@ _EXAMPLE_CATALOG = Catalog(
                 # — see vgi/_test_fixtures/table/partition_columns.py.
                 CountryPartitionedSalesFunction,
                 DisjointRangePartitionedFunction,
+                OverlappingRangePartitionedFunction,
                 PartitionedWithExplicitOverrideFunction,
                 RegionYearPartitionedFunction,
                 # Deliberately-broken batch_index fixtures (see
@@ -457,6 +460,7 @@ _EXAMPLE_CATALOG = Catalog(
                 PairTypeIntIntFunction,
                 PairTypeIntStrFunction,
                 PairTypeStrStrFunction,
+                QuerySeedFunction,
                 RandomBytesFunction,
                 RandomIntFunction,
                 ReturnSecretValueFunction,
@@ -1621,11 +1625,18 @@ def main() -> None:
     extra is also installed.
     """
     from vgi._test_fixtures.accumulate.worker import AccumulateWorker
+    from vgi._test_fixtures.narrow_bind.worker import NarrowBindWorker
     from vgi._test_fixtures.projection_repro.worker import ProjReproWorker
     from vgi._test_fixtures.schema_reconcile.worker import SchemaReconcileWorker
     from vgi.meta_worker import MetaWorker
 
-    workers: list[type] = [ExampleWorker, ProjReproWorker, SchemaReconcileWorker, AccumulateWorker]
+    workers: list[type] = [
+        ExampleWorker,
+        ProjReproWorker,
+        SchemaReconcileWorker,
+        AccumulateWorker,
+        NarrowBindWorker,
+    ]
     try:
         from vgi._test_fixtures.writable.worker import WritableWorker
     except ImportError:

vgi/aggregate_function.py

@@ -337,6 +337,22 @@ class AggregateFunction[TState: ArrowSerializableDataclass](vgi.function.Functio
         The ``states`` dict is pre-populated with ``initial_state()`` for
         all new group_ids. ``group_ids`` is parallel to each column array.
 
+        IMPORTANT — reassign to persist. Treat state as immutable: to record
+        a change you MUST write it back with ``states[gid] = new_state``. The
+        framework only persists a group whose entry you *assigned* during this
+        call (plus groups already saved from an earlier batch). Mutating the
+        existing object in place — e.g. ``states[gid].items.append(x)`` — is
+        NOT detected for a group first seen in this batch, so its data is
+        silently dropped and ``finalize()`` sees only ``initial_state()``. This
+        bites single-group / single-batch aggregates hardest. Do::
+
+            s = states[gid]
+            states[gid] = MyState(items=s.items + new_items)  # reassign
+
+        not::
+
+            states[gid].items.extend(new_items)  # in-place: may be lost
+
         """
         ...
 

vgi/arguments.py

@@ -159,6 +159,7 @@ __all__ = [
     "PYTHON_TO_ARROW",
     "Returns",
     "TableInput",
+    "TaggedUnion",
     "TypeBoundPredicate",
     "OutputLength",
     "Setting",
@@ -168,6 +169,58 @@ __all__ = [
 ]
 
 
+@dataclass(frozen=True, slots=True)
+class TaggedUnion:
+    """A decoded union-typed argument: which member is set (``tag``) and its ``value``.
+
+    DuckDB ``UNION`` / Arrow union arguments are *tagged*: the discriminator
+    (which member is present) lives in the Arrow ``UnionScalar.type_code``, not
+    in the member value. Plain ``Scalar.as_py()`` returns only the member value
+    and drops that tag, so union arguments are decoded into this wrapper
+    instead — ``tag`` is the active member's field name and ``value`` is its
+    Python value.
+
+    Example::
+
+        config: Annotated[TaggedUnion, Arg("config", arrow_type=pa.sparse_union([...]))]
+        ...
+        cfg = params.args.config            # TaggedUnion(tag=..., value=...)
+        if cfg.tag == "random_forest_classifier":
+            grid = cfg.value                # the member struct, as a dict
+
+    """
+
+    tag: str | None
+    value: Any
+
+
+def _scalar_to_py(scalar: "Scalar[Any]") -> Any:
+    """Convert an argument scalar to a Python value, preserving union tags.
+
+    Identical to ``scalar.as_py()`` for every type except unions: a
+    ``UnionScalar`` is decoded to a [`TaggedUnion`][] so the member
+    discriminator (which ``as_py()`` discards) is retained.
+
+    Args:
+        scalar: The argument scalar to convert.
+
+    Returns:
+        ``scalar.as_py()`` for non-union scalars; a [`TaggedUnion`][] for unions.
+
+    """
+    if isinstance(scalar, pa.UnionScalar):
+        # Map the active ``type_code`` to its member field name via the union
+        # type's parallel ``type_codes`` / ``field()``. (``type_code`` is coerced
+        # to int — it is an integer at runtime regardless of the stub's typing.)
+        union_type = scalar.type
+        type_codes = list(union_type.type_codes)
+        code = int(scalar.type_code)
+        tag = union_type.field(type_codes.index(code)).name if code in type_codes else None
+        inner = scalar.value
+        return TaggedUnion(tag=tag, value=inner.as_py() if inner is not None else None)
+    return scalar.as_py()
+
+
 class TableInput:
     """Sentinel type for table input parameters in table-in-out functions.
 
@@ -377,7 +430,7 @@ class Arguments:
             else:
                 raise TypeError(f"Argument '{key}': expected {type}, got {scalar.type}")
 
-        return scalar.as_py()
+        return _scalar_to_py(scalar)
 
     def get_varargs(
         self,
@@ -410,7 +463,7 @@ class Arguments:
             if type is not None and scalar.type != type:
                 raise TypeError(f"Argument {i}: expected {type}, got {scalar.type}")
 
-            values.append(scalar.as_py())
+            values.append(_scalar_to_py(scalar))
 
         return tuple(values)
 

{vgi_python-0.8.1.dist-info → vgi_python-0.8.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.8.1
+Version: 0.8.3
 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
@@ -162,7 +162,7 @@ Requires-Dist: httpx>=0.24
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.20.4
+Requires-Dist: vgi-rpc>=0.20.5
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

{vgi_python-0.8.1.dist-info → vgi_python-0.8.3.dist-info}/RECORD

@@ -1,9 +1,9 @@
-vgi/__init__.py,sha256=RHimcHtz9s4swAt2q3qFTYBFGWSIpqi9ZXonaaqwuPk,3378
+vgi/__init__.py,sha256=PRtFvXxhHEbY_0KVhyXIbGigZDYKHzMS-4gp0p6IJSQ,3414
 vgi/_duckdb.py,sha256=YB5D7N3Bwg_xP6X8a5QlumtlAovSej1A1Go5XlNGVko,2162
 vgi/_storage_profile.py,sha256=VkTsXojuE0tHEzurmteQSAiL1vI3CZSgYkL6D_h8GvE,5061
-vgi/aggregate_function.py,sha256=s4u7F3nCNXQw-U0XoEoAh86P9LfXv63MCbTuvZZYWZE,24377
+vgi/aggregate_function.py,sha256=vn9TjQEHxAKJl_xzQOzdj5TY_6LplcZjv06JkQMnUyo,25184
 vgi/argument_spec.py,sha256=fVO17BDDfjnTMUrRoILNr2oFLTl4KKedMObFUk2GRrI,17072
-vgi/arguments.py,sha256=cnM9qsHlnUsyufSGVvQoCB4RjJGF1YfjExl1FMUlnJc,64940
+vgi/arguments.py,sha256=02tIMGIR_cRS73u-bsgpFERxhje-rnTokjBgGsm9pQA,67019
 vgi/auth.py,sha256=3HD2zM-Mt0Ie-_HT5RorpND1OusUw2CPROjPNs7rgbo,1478
 vgi/exceptions.py,sha256=oX_sZc9xGWi7Xf8cJQf89fX19i3ocDEj_V_76GINgBQ,7294
 vgi/function.py,sha256=SLXA3qErHIsDsn4R0nm56z83Kcw12SMZMYXnPnCzhZg,8520
@@ -30,6 +30,7 @@ vgi/table_in_out_function.py,sha256=Ouv02ubP-XsRdByIR0ZSagi6VbZfQ8G1e5QWpqlLqvY,
 vgi/worker.py,sha256=SGZsOpER_Aew6CDhyi6I8jchigTJJuL7pyV-E-Rz100,195818
 vgi/_test_fixtures/__init__.py,sha256=xQq-QQLk8USQ6TZHsPiPcZldNNUdcJ2gToXMPGzScLI,444
 vgi/_test_fixtures/attach_options.py,sha256=YtNk1krDdKLnNVtX9yGkgS8XyzdOI0oXtNDbAV73Phg,11091
+vgi/_test_fixtures/bad_enum.py,sha256=lIVemVWTM1JVOHut47Q71Czw-sEiMjfFiyZ15NDaWAk,2910
 vgi/_test_fixtures/bad_protocol.py,sha256=L8kxafWZ-4Sd73F6EpCRo1kWVC-09qzof6OYRXazS_8,2495
 vgi/_test_fixtures/cancellable.py,sha256=hetTRLyT4kkazPNcxAdfzj0pYzEmegMksamJbR0w3Ho,12151
 vgi/_test_fixtures/catalog.py,sha256=CL6E52_vKr_kgGckT0vQO65uUWBSP518Ulfl8nmSey8,28004
@@ -40,7 +41,7 @@ vgi/_test_fixtures/simple_writable.py,sha256=CGmDBUY8kthauEm8eJN2lV72cJ9_TRxOAQC
 vgi/_test_fixtures/table_in_out.py,sha256=7QckA3NJhYAYuSctcwZLul5yOM2V3KWvLuG_33K0B_w,50459
 vgi/_test_fixtures/versioned.py,sha256=Itm-x_Zt9WDwLGT4Dl4VzU5GtFF4HkcaJEqg9ErB8As,5784
 vgi/_test_fixtures/versioned_tables.py,sha256=KRllGGRrwH8JUtqH-tLHT1JL09rKN-EcEYZVeQdbaLs,22112
-vgi/_test_fixtures/worker.py,sha256=hFbvCxbW01A6WD1GNqEBFRJiUGodRS8PWDdUwAyEhPQ,70883
+vgi/_test_fixtures/worker.py,sha256=JPTVPONIoWL9VXN8mINoJH6_Puy1Byj5VOg_fsbw8ws,71171
 vgi/_test_fixtures/accumulate/__init__.py,sha256=4hYT8jqRoVHSjV9TB7v0Z1CMJtdLuPaDWSz4J2fvMDs,868
 vgi/_test_fixtures/accumulate/worker.py,sha256=yal9m-GjKNKUdLOLtwkCyFkeHVv_nnpUjh8amwueT48,30163
 vgi/_test_fixtures/aggregate/__init__.py,sha256=tjCVKdCuHlIAZL7uDi-o_q82oMieXsAyoKExesr-7a0,2156
@@ -53,21 +54,23 @@ vgi/_test_fixtures/aggregate/percentile.py,sha256=S2bm9_BVFrkgxFNoYT7Sz06KQGFDIt
 vgi/_test_fixtures/aggregate/streaming.py,sha256=yMY819ttLFUzE6ffFXTSdWtBfUcOjfhEYVMqtjUY-dY,7840
 vgi/_test_fixtures/aggregate/varargs.py,sha256=Wi3mp5q-qHiZqzgqtqtL_0zSO-AR-8qbXssdLGAfEkM,2742
 vgi/_test_fixtures/aggregate/window.py,sha256=AmIkUCAlDAFVo3tQHuVQTnexYCMJl4MC0gEvbEpcyQ0,13713
+vgi/_test_fixtures/narrow_bind/__init__.py,sha256=NNHq6rwmxlCgOpMrLskDwjCyOA7GXSxBEfB_mOTYEgc,667
+vgi/_test_fixtures/narrow_bind/worker.py,sha256=dEBmtnSpefSTxMV32B_1R5EBpJgzqEtTmLtiG9rGIFM,7430
 vgi/_test_fixtures/projection_repro/__init__.py,sha256=9CoNsJJbBlR1qqLrL76TkyEk6bNsRZgv_uluj8RTFwY,177
 vgi/_test_fixtures/projection_repro/worker.py,sha256=ypW4fAVOn5FFnrQJCVl_s722SF-ZKiZ-aUEpPFhy7rQ,15598
-vgi/_test_fixtures/scalar/__init__.py,sha256=d2lCvfDbu_bI8Y081nBdg0QtimG8-_nMiO65ZO3zBb0,3637
+vgi/_test_fixtures/scalar/__init__.py,sha256=phgPD2CRm85KHeTpk9tIKGNrPPrxUlHKfWKVDn-BE7c,3685
 vgi/_test_fixtures/scalar/_common.py,sha256=rI2hJS-bq9wYGzDh73qy1abYktJLjvmN4mNlSEoxhtk,2664
 vgi/_test_fixtures/scalar/arithmetic.py,sha256=Bl6KQ1iMhe3USIRlV7eRU957I4R6dTidb00VXGTwM7M,10538
 vgi/_test_fixtures/scalar/binary.py,sha256=sfQR-RdNv4PP_9q77Zii3BCmI7RTz_OQQERFYp_9dTk,4121
 vgi/_test_fixtures/scalar/formatting.py,sha256=Ingqu4q2xjdhRpM5pYv-a8J-oMkVPeOllaBUbN4nIH0,5342
 vgi/_test_fixtures/scalar/geo.py,sha256=aciYyzXHauKphdr0Gm4KO_40_c-mnXPBEeHsfnpMULM,9480
 vgi/_test_fixtures/scalar/null_handling.py,sha256=ED0kJ1XfWPCcv7TzmiJX7tI1GysEPlLULjMgAzrwYcI,3834
-vgi/_test_fixtures/scalar/random_demo.py,sha256=83HMDfksBhk5BMoNc8ZK4E3fGyn-En4ETBVtIb-jeSE,5906
+vgi/_test_fixtures/scalar/random_demo.py,sha256=_4R8ePfI2x2o8lolEbFRatN1VFitLb5zhZjRLcEJHPo,7482
 vgi/_test_fixtures/scalar/settings_secrets.py,sha256=ZOGkGY0CoD3ous_ij0--ss5byB4mbE2vVstmn5Aoj0I,5519
 vgi/_test_fixtures/scalar/type_info.py,sha256=2WeTxakT-_tcWybPfkCrAHVAMOadFN3tb8E3_EmqIyw,6304
 vgi/_test_fixtures/schema_reconcile/__init__.py,sha256=rCCtM5bd67-PTPeIYg9SCJaKUSglA6YeXsedQBEUlmA,1324
 vgi/_test_fixtures/schema_reconcile/worker.py,sha256=qkGRdKvI2AKItenlribd3cvUfvWUwPbAc2WrW7_7Ijc,23570
-vgi/_test_fixtures/table/__init__.py,sha256=JiXHTTsdNOS5Lj-ctiTxGaktkuF7COVtoSf0vR3zQRM,7287
+vgi/_test_fixtures/table/__init__.py,sha256=PndeOVcsqi17XLwn0VnmPabjw3tFUfvOQFtETMOCjaU,7371
 vgi/_test_fixtures/table/_common.py,sha256=tO18gShWidcKcdHYn1FIEXDWzC2SwGsVMnA84r9Y3qs,5961
 vgi/_test_fixtures/table/batch_index.py,sha256=P5ds0xgikuEQanSEWVWKMLbdvIzUeJraI-GuSoPdb6U,11641
 vgi/_test_fixtures/table/batch_index_broken.py,sha256=kZOGrLL7ZW1rmwPmNEYRmiF_vqIfHsfXioq5vKPWHk0,7314
@@ -78,7 +81,7 @@ vgi/_test_fixtures/table/make_series.py,sha256=K-G_YNq25Kb7I5bp6XK4rCZzwMYNTxgKH
 vgi/_test_fixtures/table/misc.py,sha256=71WOIFqk5ntnEIqsG-57rZ9DY7ShQqMKHi7yluNAlM4,16250
 vgi/_test_fixtures/table/order_modes.py,sha256=FU6CoHCK61VyDdFVbl_MnlgZKGINsDsTwDmv3uD8590,6214
 vgi/_test_fixtures/table/pairs.py,sha256=idkRTbcLHGOAHG_L0n4QGG0_cuFLrArxFjhIFQKe3Iw,14875
-vgi/_test_fixtures/table/partition_columns.py,sha256=WBo3dTgY2ZPqATSR8S2yHijgHdjBN6rkrPH28igwqAY,17271
+vgi/_test_fixtures/table/partition_columns.py,sha256=X3zJIo7P-7-FxHovYKE_reBRugU43H7Msnz4JOxMpJ0,21191
 vgi/_test_fixtures/table/partition_columns_broken.py,sha256=r4u2Kx5XfUtVeRc-1BRW-kVychJyrrYGdYYuvZnm1MM,11265
 vgi/_test_fixtures/table/profiling_example.py,sha256=Rt3fgKxJhr7Q8QQRss2-OV13wh2mDXNZjnXW9sBMokQ,6754
 vgi/_test_fixtures/table/required_filters.py,sha256=RqWVofNCZtaS5wS3TM4ycaZffCk_n0TFOl_B4hU04Vc,7156
@@ -119,8 +122,8 @@ vgi/transactor/_duckdb_compat.py,sha256=sXVZ9JLKAQyGR1BjWczSwdQEavtr-TcZPoVZZnTr
 vgi/transactor/client.py,sha256=7DTeMksogsw6ANjQjGOPpKYrV76rg4_kGjktMJf54jg,4486
 vgi/transactor/protocol.py,sha256=Mtmll3CdrLFL1B4NY4NZUTO_yi3PT0qhvMQnzapuBWU,4780
 vgi/transactor/server.py,sha256=WpIqjzy2Mebw17Jui4-w7vyGEo9pD-pEZJG-3Ob1Sk8,29705
-vgi_python-0.8.1.dist-info/METADATA,sha256=imB597Wed-YEoEFF7ko_Nz0UagDGIUddc9JQBGoMjuk,24725
-vgi_python-0.8.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-vgi_python-0.8.1.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
-vgi_python-0.8.1.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
-vgi_python-0.8.1.dist-info/RECORD,,
+vgi_python-0.8.3.dist-info/METADATA,sha256=1IObmLQGq14cxyOL9Q-3rdWmX5HR9y9br2CJf7az7R0,24725
+vgi_python-0.8.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+vgi_python-0.8.3.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
+vgi_python-0.8.3.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
+vgi_python-0.8.3.dist-info/RECORD,,