vgi-python 0.33.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

vgi/_test_fixtures/table_in_out.py

@@ -51,7 +51,7 @@ from vgi_rpc import ArrowSerializableDataclass, ArrowType
 from vgi_rpc.log import Level
 from vgi_rpc.rpc import OutputCollector
 
-from vgi.arguments import Arg, Setting, TableInput
+from vgi.arguments import AnyArrow, Arg, Setting, TableInput
 from vgi.cache_control import CacheControl
 from vgi.invocation import BindResponse
 from vgi.metadata import FunctionExample
@@ -94,6 +94,8 @@ __all__ = [
     "GeoEncode3Function",
     "RowSumFunction",
     "BlendedDropFunction",
+    "BlendedAnyFunction",
+    "BlendedAnyVarargsFunction",
     "SubstreamPartialSumFunction",
     "MultiBatchFinishFunction",
     "SumAllColumnsFunction",
@@ -1880,6 +1882,87 @@ class BlendedExplodeFunction(RowTransformFunction[_ExplodeArgs]):
         cast("VgiOutputCollector", out).emit(out_batch, parent_rows=parent_rows)
 
 
+@dataclass(slots=True, frozen=True, kw_only=True)
+class _AnyArgs:
+    """One positional ANY-typed input column."""
+
+    value: Annotated[AnyArrow, Arg(0, doc="Input column of any type (echoed back unchanged)")]
+
+
+class BlendedAnyFunction(RowTransformFunction[_AnyArgs]):
+    """Blended 1->1 echo of a single ANY-typed input column.
+
+    Proves a blended positional arg may be declared ANY: the declared type names
+    no concrete Arrow type, so the client must build the worker's input schema
+    from the type DuckDB actually resolved for the call (a STRUCT built per row,
+    a whole-row struct, a LIST, a plain VARCHAR ...) rather than from the
+    declaration. The output column ``value`` is bound to that resolved input
+    type at bind time and the column is passed through untouched, so a test
+    asserts on DuckDB's own ``typeof(value)`` and on the round-tripped values —
+    nothing here depends on how an SDK happens to render a type name.
+    """
+
+    class Meta:
+        name = "blended_any"
+        description = "Blended 1->1 echo of one ANY-typed input column (output typed from the input)"
+        categories = ["blended", "test"]
+
+    @classmethod
+    def on_bind(cls, params: BindParams[_AnyArgs]) -> BindResponse:
+        input_schema = params.bind_call.input_schema
+        assert input_schema is not None
+        return BindResponse(output_schema=pa.schema([pa.field("value", input_schema.field(0).type)]))
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[_AnyArgs],
+        state: None,
+        batch: pa.RecordBatch,
+        out: OutputCollector,
+    ) -> None:
+        out.emit(pa.record_batch([batch.column(0)], schema=params.output_schema))
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class _AnyVarargsArgs:
+    """N positional ANY-typed input columns, each free to be a different type."""
+
+    values: Annotated[list[AnyArrow], Arg(0, varargs=True, doc="Input columns of any types (echoed back)")]
+
+
+class BlendedAnyVarargsFunction(RowTransformFunction[_AnyVarargsArgs]):
+    """Blended 1->1 echo of N ANY-typed VARARGS input columns.
+
+    The varargs counterpart of ``blended_any``: every runtime column may resolve
+    to a different concrete type, so the client must take each column's type
+    from the call rather than from the (ANY) vararg element type. Output columns
+    are ``col0..colN-1`` — the names the client generates for varargs blended
+    input — each bound to its own resolved input type.
+    """
+
+    class Meta:
+        name = "blended_any_varargs"
+        description = "Blended 1->1 echo of N ANY-typed varargs input columns (col0..colN-1)"
+        categories = ["blended", "test"]
+
+    @classmethod
+    def on_bind(cls, params: BindParams[_AnyVarargsArgs]) -> BindResponse:
+        input_schema = params.bind_call.input_schema
+        assert input_schema is not None
+        return BindResponse(output_schema=pa.schema([pa.field(f"col{i}", f.type) for i, f in enumerate(input_schema)]))
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[_AnyVarargsArgs],
+        state: None,
+        batch: pa.RecordBatch,
+        out: OutputCollector,
+    ) -> None:
+        out.emit(pa.record_batch(cls.input_columns(batch), schema=params.output_schema))
+
+
 class CachedExplodeFunction(RowTransformFunction[_ExplodeArgs]):
     """Cacheable blended 1->N fan-out advertising vgi.cache.per_value.
 

vgi/_test_fixtures/worker.py

@@ -267,6 +267,8 @@ from vgi._test_fixtures.table.tt_pushdown import (
 )
 from vgi._test_fixtures.table_in_out import (
     BatchIndexBufferInputFunction,
+    BlendedAnyFunction,
+    BlendedAnyVarargsFunction,
     BlendedDropFunction,
     BlendedExplodeFunction,
     BufferEmitWideFunction,
@@ -432,6 +434,8 @@ _EXAMPLE_CATALOG = Catalog(
                 GeoEncode3Function,
                 RowSumFunction,
                 BlendedDropFunction,
+                BlendedAnyFunction,
+                BlendedAnyVarargsFunction,
                 BlendedExplodeFunction,
                 CachedExplodeFunction,
                 ProjectableBlendedFunction,

vgi/argument_spec.py

@@ -19,7 +19,8 @@ import warnings
 from collections.abc import Sequence
 from dataclasses import dataclass
 from functools import cache
-from typing import Annotated, Any, get_args, get_origin, get_type_hints
+from types import UnionType
+from typing import Annotated, Any, Union, get_args, get_origin, get_type_hints
 
 import pyarrow as pa
 
@@ -395,14 +396,22 @@ def parameter_default_values_from_specs(
     arrays: list[pa.Array[Any]] = []
     names: list[str] = []
     for spec in default_specs:
-        if pa.types.is_null(spec.arrow_type):
-            raise ValueError(
-                f"Parameter {spec.name!r} has a default but no concrete Arrow type; "
-                "typed defaults require an explicit parameter type"
-            )
         value = spec.default_value
         if isinstance(value, pa.Scalar):
             value = value.as_py()
+        # An ANY-typed parameter (AnyArrow) has no concrete Arrow type, so a
+        # VALUE default cannot be represented. `None` still can: a null-typed
+        # array holds nulls, and it is column PRESENCE, not the value, that
+        # marks a parameter as having a default. Allowing it lets a required
+        # ANY parameter be declared `default=None` so that omitting it reaches
+        # the function's own on_bind() validation — which can name the argument
+        # and show its shape — instead of raising a bare KeyError during
+        # argument parsing, before any user code runs.
+        if pa.types.is_null(spec.arrow_type) and value is not None:
+            raise ValueError(
+                f"Parameter {spec.name!r} has a non-null default but no concrete Arrow type; "
+                "a typed default requires an explicit parameter type (None is allowed)"
+            )
         try:
             arrays.append(pa.array([value], type=spec.arrow_type))
         except (pa.ArrowException, TypeError, ValueError) as exc:
@@ -538,6 +547,30 @@ def _format_range(
     return f"{low}, {high}"
 
 
+def _unwrap_optional(annotation: Any) -> Any:
+    """``T | None`` -> ``T``; anything else unchanged.
+
+    A special marker type (``AnyArrow``, ``TableInput``) is recognised by
+    identity, so an Optional wrapper would hide it — an ``AnyArrow | None``
+    parameter would silently become a NULL-typed one, and DuckDB then cannot
+    cast anything into it. Unwrapping first lets a marker be declared nullable,
+    which is how a REQUIRED ANY argument opts into reaching its function's own
+    ``on_bind()`` validation (with ``default=None``) instead of being rejected
+    during parsing. Mirrors what ``_accepts_none`` already looks for.
+
+    Args:
+        annotation: The declared type of an ``Annotated[T, Arg(...)]`` field.
+
+    Returns:
+        The single non-``None`` member of an optional union, else ``annotation``.
+    """
+    origin = get_origin(annotation)
+    if origin is not Union and origin is not UnionType:
+        return annotation
+    members = [a for a in get_args(annotation) if a is not type(None)]
+    return members[0] if len(members) == 1 else annotation
+
+
 def _constraint_kwargs(arg: Arg[Any]) -> dict[str, Any]:
     """Extract discovery-facing constraint metadata from an [`Arg`][] descriptor.
 
@@ -744,6 +777,7 @@ def _extract_argument_specs(
                 if type_args:
                     infer_type = type_args[0]
 
+            infer_type = _unwrap_optional(infer_type)
             is_table_input = infer_type is TableInput
             is_any_type = infer_type is AnyArrow or infer_type is AnyArrowValue
 
@@ -790,8 +824,8 @@ def _extract_argument_specs(
                 # Check for special types (AnyArrow, TableInput)
                 # Priority: Arg subscript type (Arg[AnyArrow]) > class type hint
                 # Also check _returns_any_arrow_value for Annotated[AnyArrowValue, ...]
-                hint = hints.get(attr_name)
-                type_param = getattr(arg_legacy, "_type_param", None)
+                hint = _unwrap_optional(hints.get(attr_name))
+                type_param = _unwrap_optional(getattr(arg_legacy, "_type_param", None))
                 is_table_input = type_param is TableInput or hint is TableInput
                 is_any_type = (
                     type_param is AnyArrow

{vgi_python-0.33.0.dist-info → vgi_python-0.34.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.33.0
+Version: 0.34.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.33.0.dist-info → vgi_python-0.34.0.dist-info}/RECORD

@@ -2,7 +2,7 @@ vgi/__init__.py,sha256=8uLMNQcNzWjp8VzYtj2u98_Wp8WpB8c_dKlMv67TH0g,5384
 vgi/_duckdb.py,sha256=YB5D7N3Bwg_xP6X8a5QlumtlAovSej1A1Go5XlNGVko,2162
 vgi/_storage_profile.py,sha256=VkTsXojuE0tHEzurmteQSAiL1vI3CZSgYkL6D_h8GvE,5061
 vgi/aggregate_function.py,sha256=v03wBSy2Rrl9F2pMYvu8GnGrTCQrAVm01HXIFNdjnm4,26886
-vgi/argument_spec.py,sha256=_aO3r6LrRrM7ziOQ27i_ouaofXD_2XMHiwhihNVfj0o,32374
+vgi/argument_spec.py,sha256=SADH97VlFu3asI8CWZ_I7XTuSxwqFciFgdupdAf-tkY,34231
 vgi/arguments.py,sha256=ncnC1CS7KN-2rDjSw9vdf1uHqV5ozebet_eZtcq_ujw,72300
 vgi/attach_header.py,sha256=sxpzCOVa5fl_-kQSCZgeUxS5I9Kuv8VCUjAOF5s1pr0,3782
 vgi/auth.py,sha256=TlD5bhdyXnFuAoCnoHMU9ffjewVEnpwO5auIvp9GsCA,2486
@@ -52,12 +52,12 @@ vgi/_test_fixtures/http_server.py,sha256=AviomIEClCEuA9WPgQOzrMtQ484N04rQupK8dWO
 vgi/_test_fixtures/nest_tensor.py,sha256=UjjW9UwipYG3ehQpZOm4hdzsafMyvVc0ZKJCrqiZTPU,24471
 vgi/_test_fixtures/orchard_catalog.py,sha256=8Uv-mKTIgl-OYU9JLgG23owlHGmgniyF2chPoKXGtuI,1643
 vgi/_test_fixtures/simple_writable.py,sha256=OmyENVnsgJmYH0_5sNWMt_Xgj9JoPaOu7uI5_ROZDKg,32020
-vgi/_test_fixtures/table_in_out.py,sha256=Ug-n9wvqT5StT7Sm0OQ1MAmOCQr2jzdcpfneiQCpmJM,89813
+vgi/_test_fixtures/table_in_out.py,sha256=sWTSXwH-BUaSNOQsDmDqlFZxZ5GGtD-_xmysD2g7aV8,93148
 vgi/_test_fixtures/table_in_out_same_name.py,sha256=jdsQNdKn64T54W_TcLB-rhydI69Y0Uzr5n6FU7v9rIU,8649
 vgi/_test_fixtures/twin_catalogs.py,sha256=UFsFuZ_nFpe62HatGnOMru36vk35Xt3Ta1Hkr1aWN9w,4450
 vgi/_test_fixtures/versioned.py,sha256=gnxNejc4cNGPKl_DxJk1SU8Ielj-rwmQYGkiShXzxK4,5786
 vgi/_test_fixtures/versioned_tables.py,sha256=_JHPe6LaiO0x2We28Ion8hh6pSATmHZYvAczB4uwBsA,22272
-vgi/_test_fixtures/worker.py,sha256=5ocHOoa4mksNCTA39LOdvnhDhusam9hVpEb2MQOFSjU,96306
+vgi/_test_fixtures/worker.py,sha256=tAdCcL9x3LwgtY0OG56bapmBCwGZJ-M7paQY9hXjgB8,96440
 vgi/_test_fixtures/accumulate/__init__.py,sha256=4hYT8jqRoVHSjV9TB7v0Z1CMJtdLuPaDWSz4J2fvMDs,868
 vgi/_test_fixtures/accumulate/worker.py,sha256=4a2VaCoOIXPEoJpkNume7FoBlQzs9kRl8b-_ZJMHvnQ,30165
 vgi/_test_fixtures/aggregate/__init__.py,sha256=2GCp80FNrsWFOA2SV3lCffzLjoN5AKwrf57t2YRg8O0,2393
@@ -152,8 +152,8 @@ vgi/transactor/_duckdb_compat.py,sha256=sXVZ9JLKAQyGR1BjWczSwdQEavtr-TcZPoVZZnTr
 vgi/transactor/client.py,sha256=7DTeMksogsw6ANjQjGOPpKYrV76rg4_kGjktMJf54jg,4486
 vgi/transactor/protocol.py,sha256=v59IvrKnuvwOXvn_HEcBAbCzDVcx0akgKN0R1mChXg0,5034
 vgi/transactor/server.py,sha256=nzsZQxJZdgappdYX8okrFIrjFtUbdM_Hhskl1fZ2nDY,32553
-vgi_python-0.33.0.dist-info/METADATA,sha256=RsTar3agbo8sxMrJEFtAFx4Qc-nICjnLZdUMLK83JcA,25617
-vgi_python-0.33.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-vgi_python-0.33.0.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
-vgi_python-0.33.0.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
-vgi_python-0.33.0.dist-info/RECORD,,
+vgi_python-0.34.0.dist-info/METADATA,sha256=4-WKG1yNlJmW1IRUWKY1kssQ_QLYhOrSlZqQs_7dz28,25617
+vgi_python-0.34.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+vgi_python-0.34.0.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
+vgi_python-0.34.0.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
+vgi_python-0.34.0.dist-info/RECORD,,

{vgi_python-0.33.0.dist-info → vgi_python-0.34.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.0
+Generator: hatchling 1.32.3
 Root-Is-Purelib: true
 Tag: py3-none-any