vgi-python 0.8.2__tar.gz → 0.8.3__tar.gz

{vgi_python-0.8.2 → vgi_python-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.8.2
+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

{vgi_python-0.8.2 → vgi_python-0.8.3}/pyproject.toml

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

vgi_python-0.8.3/tests/test_union_argument.py

@@ -0,0 +1,111 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Union-typed argument decoding.
+
+A DuckDB ``UNION`` / Arrow union argument is tagged: the discriminator lives in
+``UnionScalar.type_code``, which plain ``Scalar.as_py()`` discards. ``Arguments``
+decodes such scalars to ``TaggedUnion`` so the active member name is preserved.
+"""
+
+from __future__ import annotations
+
+import pyarrow as pa
+
+from vgi.arguments import Arguments, TaggedUnion
+
+_RF = pa.struct([pa.field("n_estimators", pa.list_(pa.int64())), pa.field("max_depth", pa.list_(pa.int64()))])
+_SVC = pa.struct([pa.field("C", pa.list_(pa.float64())), pa.field("kernel", pa.list_(pa.string()))])
+
+
+def _union_scalar(code: int, members: dict) -> pa.UnionScalar:
+    """Build a one-element sparse-union scalar with named members, active = ``code``."""
+    arr = pa.UnionArray.from_sparse(
+        pa.array([code], type=pa.int8()),
+        [
+            pa.array([members.get("random_forest_classifier")], type=_RF),
+            pa.array([members.get("svc")], type=_SVC),
+        ],
+        field_names=["random_forest_classifier", "svc"],
+        type_codes=[0, 1],
+    )
+    return arr[0]
+
+
+def test_union_arg_preserves_tag() -> None:
+    """A union argument decodes to a TaggedUnion carrying the active member name."""
+    scalar = _union_scalar(0, {"random_forest_classifier": {"n_estimators": [100, 300], "max_depth": [3, 5]}})
+    got = Arguments(named={"config": scalar}).get("config")
+    assert isinstance(got, TaggedUnion)
+    assert got.tag == "random_forest_classifier"
+    assert got.value == {"n_estimators": [100, 300], "max_depth": [3, 5]}
+
+
+def test_union_arg_other_member() -> None:
+    """The tag reflects whichever union member is set."""
+    scalar = _union_scalar(1, {"svc": {"C": [1.0, 10.0], "kernel": ["rbf", "linear"]}})
+    got = Arguments(named={"config": scalar}).get("config")
+    assert got.tag == "svc"
+    assert got.value == {"C": [1.0, 10.0], "kernel": ["rbf", "linear"]}
+
+
+def test_union_arg_null_payload() -> None:
+    """A null union slot decodes its value to None (the ``inner is None`` branch).
+
+    Note: pyarrow reports ``type_code == 0`` for any null union slot regardless of
+    the codes buffer, so the active member's tag is not recoverable at the scalar
+    level for a null payload — only the value is. (Tag preservation for a
+    non-null payload of a non-zero-code member is covered above and through the
+    batch-level round-trip in the echo integration suite.)
+    """
+    scalar = _union_scalar(1, {"svc": None})
+    got = Arguments(named={"config": scalar}).get("config")
+    assert isinstance(got, TaggedUnion)
+    assert got.value is None
+
+
+def test_union_arg_non_contiguous_type_codes() -> None:
+    """Tag resolution maps via type_codes, not member position.
+
+    Type codes need not be 0,1,2,...; ``_scalar_to_py`` must locate the active
+    member by ``type_codes.index(code)`` rather than treating the code as a
+    positional index.
+    """
+    arr = pa.UnionArray.from_sparse(
+        pa.array([9], type=pa.int8()),
+        [
+            pa.array([{"n_estimators": [1], "max_depth": [2]}], type=_RF),
+            pa.array([{"C": [1.0], "kernel": ["rbf"]}], type=_SVC),
+        ],
+        field_names=["random_forest_classifier", "svc"],
+        type_codes=[5, 9],
+    )
+    got = Arguments(named={"config": arr[0]}).get("config")
+    assert isinstance(got, TaggedUnion)
+    assert got.tag == "svc"
+    assert got.value == {"C": [1.0], "kernel": ["rbf"]}
+
+
+def test_union_arg_dense_union() -> None:
+    """Dense unions (what DuckDB emits) decode the same as sparse."""
+    arr = pa.UnionArray.from_dense(
+        pa.array([1], type=pa.int8()),
+        pa.array([0], type=pa.int32()),
+        [
+            pa.array([], type=_RF),
+            pa.array([{"C": [2.0], "kernel": ["linear"]}], type=_SVC),
+        ],
+        field_names=["random_forest_classifier", "svc"],
+        type_codes=[0, 1],
+    )
+    got = Arguments(named={"config": arr[0]}).get("config")
+    assert isinstance(got, TaggedUnion)
+    assert got.tag == "svc"
+    assert got.value == {"C": [2.0], "kernel": ["linear"]}
+
+
+def test_non_union_args_unchanged() -> None:
+    """Non-union arguments still decode via plain as_py()."""
+    args = Arguments(named={"n": pa.scalar(5), "s": pa.scalar("hi")}, positional=(pa.scalar(1.5),))
+    assert args.get("n") == 5
+    assert args.get("s") == "hi"
+    assert args.get(0) == 1.5

{vgi_python-0.8.2 → vgi_python-0.8.3}/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_python-0.8.2 → vgi_python-0.8.3}/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)