vgi-python 0.33.0__tar.gz → 0.34.1__tar.gz

{vgi_python-0.33.0 → vgi_python-0.34.1}/PKG-INFO

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

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

{vgi_python-0.33.0 → vgi_python-0.34.1}/tests/table_in_out/test_blended_exchange.py

@@ -280,3 +280,73 @@ class TestHasFinalizeSkip:
         assert len(with_finalize) == 1
         assert len(without_finalize) == 1
         assert with_finalize[0].column("i").to_pylist() == without_finalize[0].column("i").to_pylist()
+
+
+class TestBlendedAny:
+    """`blended_any` / `blended_any_varargs`: positional input columns declared ANY.
+
+    An ANY arg names no concrete Arrow type, so the output type can only come from
+    the input schema the client supplies at bind. These drive that over the wire:
+    the same registration must bind to whatever type each call resolves to, and
+    echo the column back untouched (nested types and nulls included).
+    """
+
+    @pytest.mark.parametrize(
+        "array",
+        [
+            pa.array(["a", None, "c"], type=pa.string()),
+            pa.array([1, 2, None], type=pa.int32()),
+            pa.array(
+                [{"message": "lost pkg", "tier": "gold"}, None, {"message": None, "tier": "free"}],
+                type=pa.struct([("message", pa.string()), ("tier", pa.string())]),
+            ),
+            pa.array([[1, 2], [], None], type=pa.list_(pa.int64())),
+        ],
+        ids=["string", "int32", "struct", "list"],
+    )
+    def test_output_is_typed_from_the_input_and_echoed(self, fixture_worker: str, array: pa.Array[Any]) -> None:
+        """One registration, bound per call to the resolved input type."""
+        batch = pa.record_batch({"value": array})
+        bound: list[pa.Schema] = []
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="blended_any",
+                    schema_path=["main"],
+                    input=iter([batch]),
+                    bind_result_callback=lambda r: bound.append(r.output_schema),
+                    has_finalize=False,
+                )
+            )
+
+        assert [s.names for s in bound] == [["value"]]
+        assert bound[0].field("value").type == array.type
+        (out,) = results
+        assert out.column("value").type == array.type
+        # A null struct and a struct with a null field must stay distinct.
+        assert out.column("value").to_pylist() == array.to_pylist()
+
+    def test_varargs_columns_each_keep_their_own_type(self, fixture_worker: str) -> None:
+        """The vararg element type is ANY, so every runtime column types itself."""
+        batch = pa.record_batch(
+            {
+                "col0": pa.array(["a", "b"], type=pa.string()),
+                "col1": pa.array([[1], [2, 3]], type=pa.list_(pa.int32())),
+                "col2": pa.array([{"k": 1.5}, None], type=pa.struct([("k", pa.float64())])),
+            }
+        )
+
+        with Client(fixture_worker) as client:
+            (out,) = list(
+                client.table_in_out_function(
+                    function_name="blended_any_varargs",
+                    schema_path=["main"],
+                    input=iter([batch]),
+                    has_finalize=False,
+                )
+            )
+
+        assert out.schema.names == ["col0", "col1", "col2"]
+        assert out.schema.types == batch.schema.types
+        assert out.to_pylist() == batch.to_pylist()

{vgi_python-0.33.0 → vgi_python-0.34.1}/tests/table_in_out/test_blended_metadata.py

@@ -148,3 +148,43 @@ class TestBlendedFootguns:
 
         with pytest.raises(TypeError, match="at least one positional Arg"):
             resolve_metadata(_NamedOnly)
+
+
+class TestBlendedAnyResolution:
+    """A blended function may declare its positional input column(s) ANY.
+
+    The ANY marker lives on the argument *spec* — the ``vgi_type=any`` field
+    metadata the client reads to learn it must take the column's type from the
+    call rather than from the declaration.
+    """
+
+    def test_any_positional_is_a_blended_input_column(self) -> None:
+        """The ANY arg resolves as a positional input column, not a bind constant."""
+        from vgi._test_fixtures.table_in_out import BlendedAnyFunction
+        from vgi.argument_spec import extract_argument_specs
+
+        m = resolve_metadata(BlendedAnyFunction)
+        assert m.input_from_args is True
+        assert m.has_finalize is False
+        (spec,) = extract_argument_specs(BlendedAnyFunction)
+        assert (spec.name, spec.position, spec.is_any_type, spec.is_varargs) == ("value", 0, True, False)
+
+    def test_any_varargs_is_a_blended_input_column(self) -> None:
+        """The varargs form keeps both markers: ANY element type and varargs."""
+        from vgi._test_fixtures.table_in_out import BlendedAnyVarargsFunction
+        from vgi.argument_spec import extract_argument_specs
+
+        assert resolve_metadata(BlendedAnyVarargsFunction).input_from_args is True
+        (spec,) = extract_argument_specs(BlendedAnyVarargsFunction)
+        assert (spec.name, spec.position, spec.is_any_type, spec.is_varargs) == ("values", 0, True, True)
+
+    def test_any_marker_survives_the_wire_schema(self) -> None:
+        """The client learns the arg is ANY from the serialized arguments schema."""
+        from vgi._test_fixtures.table_in_out import BlendedAnyFunction, BlendedAnyVarargsFunction
+        from vgi.argument_spec import argument_specs_to_schema, extract_argument_specs, schema_to_argument_specs
+
+        for function in (BlendedAnyFunction, BlendedAnyVarargsFunction):
+            specs = extract_argument_specs(function)
+            wire = schema_to_argument_specs(argument_specs_to_schema(specs))
+            assert [s.is_any_type for s in wire] == [True]
+            assert [s.is_varargs for s in wire] == [s.is_varargs for s in specs]

{vgi_python-0.33.0 → vgi_python-0.34.1}/tests/test_argument_spec.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import dataclasses
 from typing import Annotated, Any
 
 import pyarrow as pa
@@ -856,7 +857,7 @@ class TestArgumentConstraints:
         assert defaults.column("label")[0].as_py() is None
 
     def test_typed_default_requires_concrete_parameter_type(self) -> None:
-        """An ANY parameter cannot carry an untyped protocol default."""
+        """An ANY parameter cannot carry an untyped protocol default VALUE."""
         spec = ArgumentSpec(
             name="value",
             position=0,
@@ -865,9 +866,65 @@ class TestArgumentConstraints:
             default_value=1,
         )
 
-        with pytest.raises(ValueError, match="typed defaults require an explicit parameter type"):
+        with pytest.raises(ValueError, match="a typed default requires an explicit parameter type"):
             parameter_default_values_from_specs([spec], require_trailing=True)
 
+    def test_an_any_parameter_may_default_to_none(self) -> None:
+        """`None` IS representable on an ANY parameter — a null array holds nulls.
+
+        It is column presence, not the value, that marks a parameter as having a
+        default, so this costs the protocol nothing. It buys a function the
+        ability to declare a *required* ANY argument with ``default=None`` so
+        that omitting it reaches ``on_bind()``, where the function can name the
+        argument and show its shape, instead of raising a bare ``KeyError``
+        during argument parsing before any user code runs.
+        """
+        spec = ArgumentSpec(
+            name="questions",
+            position="questions",
+            arrow_type=pa.null(),
+            is_any_type=True,
+            default_value=None,
+        )
+
+        defaults = parameter_default_values_from_specs([spec], require_trailing=True)
+
+        assert defaults is not None
+        assert defaults.schema.names == ["questions"]
+        assert defaults.column("questions").type == pa.null()
+        assert defaults.column("questions")[0].as_py() is None
+
+    def test_an_optional_any_argument_is_still_an_any_argument(self) -> None:
+        """``AnyArrow | None`` must stay ANY-typed, not collapse to a NULL column.
+
+        A marker type is recognised by identity, so an Optional wrapper used to
+        hide it: the parameter silently became NULL-typed and DuckDB could then
+        cast nothing into it (`Unimplemented type for cast (STRUCT(...) -> NULL)`).
+        Declaring a REQUIRED ANY argument nullable, with ``default=None``, is how
+        a function gets to reject the missing case in its own ``on_bind()`` with
+        a message naming the argument.
+        """
+
+        @dataclasses.dataclass(slots=True, frozen=True, kw_only=True)
+        class _Args:
+            """Args with a required-but-nullable ANY parameter."""
+
+            payload: Annotated[AnyArrow | None, Arg("payload", default=None)] = None
+
+        class _Fn(TableInOutFunction[_Args]):
+            """A function declaring one optional ANY argument."""
+
+            FunctionArguments = _Args
+
+            class Meta:
+                """Metadata."""
+
+                name = "optional_any"
+
+        (spec,) = [sp for sp in extract_argument_specs(_Fn) if sp.name == "payload"]
+        assert spec.is_any_type, "an optional ANY argument lost its ANY marker"
+        assert pa.types.is_null(spec.arrow_type)
+
     def test_typed_defaults_reject_case_insensitive_duplicate_names(self) -> None:
         """Default-batch field names must identify one signature slot."""
         specs = [

vgi_python-0.34.1/tests/test_import_side_effects.py

@@ -0,0 +1,205 @@
+# Copyright 2026 Query Farm LLC - https://query.farm
+
+"""Importing vgi, and defining functions, must not touch the filesystem.
+
+``Function.storage`` resolves the default SQLite store lazily, on first access.
+``TableFunctionBase.__init_subclass__`` used to defeat that: it detected
+abstract classes with a plain ``getattr`` over ``dir(cls)``, which invoked the
+storage descriptor, which created ``vgi_storage.db`` under the user's state
+directory. Because vgi defines subclasses of its own, a bare ``import vgi`` did
+it — and failed outright wherever that directory was not writable, such as a
+container running as a non-root user whose home belongs to root.
+
+The import checks run in a subprocess with ``HOME`` and the XDG directories
+pointed at an empty temporary directory, because the storage descriptor caches
+its backend per process and the test process has usually resolved it already.
+"""
+
+import os
+import subprocess
+import sys
+from abc import abstractmethod
+from pathlib import Path
+
+import pytest
+
+from vgi.table_function import TableFunctionGenerator
+
+#: Imports every function base class and defines a concrete table function, so
+#: both vgi's own class definitions and a worker's go through __init_subclass__.
+_IMPORT_AND_DEFINE = """
+import pyarrow as pa
+import vgi
+import vgi.aggregate_function
+import vgi.scalar_function
+import vgi.table_in_out_function
+from vgi.invocation import BindResponse
+from vgi.table_function import TableFunctionGenerator
+
+
+class Concrete(TableFunctionGenerator[None, None]):
+    @classmethod
+    def on_bind(cls, params):
+        return BindResponse(output_schema=pa.schema([("n", pa.int64())]))
+
+    @classmethod
+    def process(cls, params, state, out):
+        out.finish()
+
+
+# The direct check, independent of where a platform keeps its state directory:
+# reading through __dict__ does not invoke the descriptor.
+from vgi.function import Function
+
+assert Function.__dict__["storage"]._resolved is None, "storage was resolved during import"
+"""
+
+
+def _isolated_env(home: Path) -> dict[str, str]:
+    """Environment whose every per-user directory lives under ``home``.
+
+    ``VGI_*`` variables are dropped so the default file-backed SQLite store is
+    the one in play; a test run configured with ``VGI_WORKER_SHARED_STORAGE``
+    set to ``memory`` would otherwise pass without the fix.
+    """
+    env = {k: v for k, v in os.environ.items() if not k.startswith(("VGI_", "XDG_"))}
+    env["HOME"] = str(home)
+    for name in ("XDG_STATE_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "XDG_CONFIG_HOME"):
+        env[name] = str(home / name.lower())
+    # platformdirs asks Windows for its folders directly and ignores HOME and
+    # XDG there, but honors these overrides.
+    for name in ("LOCAL_APPDATA", "APPDATA"):
+        env[f"WIN_PD_OVERRIDE_{name}"] = str(home / name.lower())
+    return env
+
+
+def _run(code: str, home: Path) -> subprocess.CompletedProcess[str]:
+    """Run ``code`` in a fresh interpreter with per-user directories under ``home``."""
+    return subprocess.run(
+        [sys.executable, "-c", code],
+        env=_isolated_env(home),
+        capture_output=True,
+        text=True,
+        timeout=120,
+        check=False,
+    )
+
+
+def _files_under(root: Path) -> list[str]:
+    """Every file below ``root``, relative to it."""
+    return sorted(str(p.relative_to(root)) for p in root.rglob("*") if p.is_file())
+
+
+class TestImportWritesNothing:
+    """The storage store is created when it is used, not when vgi is imported."""
+
+    def test_import_and_define_create_no_files(self, tmp_path: Path) -> None:
+        """Importing vgi and defining a function leaves the home directory empty."""
+        result = _run(_IMPORT_AND_DEFINE, tmp_path)
+        assert result.returncode == 0, result.stderr
+        assert _files_under(tmp_path) == []
+
+    @pytest.mark.skipif(
+        sys.platform == "win32" or os.geteuid() == 0,
+        reason="a read-only directory does not stop root, and POSIX modes do not apply on Windows",
+    )
+    def test_import_succeeds_when_home_is_not_writable(self, tmp_path: Path) -> None:
+        """A read-only home — a container's non-root user, say — does not stop the import."""
+        home = tmp_path / "home"
+        home.mkdir()
+        home.chmod(0o555)
+        try:
+            result = _run(_IMPORT_AND_DEFINE, home)
+        finally:
+            home.chmod(0o755)
+        assert result.returncode == 0, result.stderr
+
+    def test_storage_is_still_created_on_first_use(self, tmp_path: Path) -> None:
+        """Laziness, not removal: touching Function.storage still creates the store."""
+        result = _run("from vgi.function import Function\nFunction.storage", tmp_path)
+        assert result.returncode == 0, result.stderr
+        assert any(name.endswith("vgi_storage.db") for name in _files_under(tmp_path))
+
+
+class _NotADataclass:
+    """An argument type a concrete function would be rejected for."""
+
+
+class TestAbstractDetection:
+    """Reading attributes statically must still recognize every kind of abstract member.
+
+    An abstract class skips validation of its argument type; a concrete one is
+    rejected at class creation when that type is not a dataclass. So a class
+    with an invalid argument type is defined successfully only if it is seen as
+    abstract.
+    """
+
+    def test_a_concrete_class_is_validated(self) -> None:
+        """Control: without an abstract member, the invalid argument type is rejected."""
+        with pytest.raises(TypeError, match="must be a dataclass"):
+
+            class Concrete(TableFunctionGenerator[_NotADataclass, None]):
+                @classmethod
+                def on_bind(cls, params):  # type: ignore[no-untyped-def]
+                    raise NotImplementedError
+
+                @classmethod
+                def process(cls, params, state, out):  # type: ignore[no-untyped-def]
+                    raise NotImplementedError
+
+    def test_an_abstract_classmethod_marks_the_class_abstract(self) -> None:
+        """An inherited-concrete class that adds an abstract classmethod skips validation."""
+
+        class WithAbstractClassmethod(TableFunctionGenerator[_NotADataclass, None]):
+            @classmethod
+            def on_bind(cls, params):  # type: ignore[no-untyped-def]
+                raise NotImplementedError
+
+            @classmethod
+            def process(cls, params, state, out):  # type: ignore[no-untyped-def]
+                raise NotImplementedError
+
+            @classmethod
+            @abstractmethod
+            def extra(cls) -> None:
+                """Left for a subclass to implement."""
+
+        assert WithAbstractClassmethod._setting_params == {}
+
+    def test_an_abstract_staticmethod_marks_the_class_abstract(self) -> None:
+        """An abstract staticmethod is recognized through its raw attribute too."""
+
+        class WithAbstractStaticmethod(TableFunctionGenerator[_NotADataclass, None]):
+            @classmethod
+            def on_bind(cls, params):  # type: ignore[no-untyped-def]
+                raise NotImplementedError
+
+            @classmethod
+            def process(cls, params, state, out):  # type: ignore[no-untyped-def]
+                raise NotImplementedError
+
+            @staticmethod
+            @abstractmethod
+            def extra() -> None:
+                """Left for a subclass to implement."""
+
+        assert WithAbstractStaticmethod._setting_params == {}
+
+    def test_an_abstract_property_marks_the_class_abstract(self) -> None:
+        """An abstract property is recognized through its raw attribute too."""
+
+        class WithAbstractProperty(TableFunctionGenerator[_NotADataclass, None]):
+            @classmethod
+            def on_bind(cls, params):  # type: ignore[no-untyped-def]
+                raise NotImplementedError
+
+            @classmethod
+            def process(cls, params, state, out):  # type: ignore[no-untyped-def]
+                raise NotImplementedError
+
+            @property
+            @abstractmethod
+            def extra(self) -> int:
+                """Left for a subclass to implement."""
+
+        assert WithAbstractProperty._setting_params == {}

{vgi_python-0.33.0 → vgi_python-0.34.1}/uv.lock

@@ -2580,7 +2580,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.33.0"
+version = "0.34.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

{vgi_python-0.33.0 → vgi_python-0.34.1}/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_python-0.33.0 → vgi_python-0.34.1}/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_python-0.33.0 → vgi_python-0.34.1}/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 → vgi_python-0.34.1}/vgi/table_function.py

@@ -8,6 +8,7 @@ to `process()` either emits a batch via `out.emit()` or signals completion via `
 
 from __future__ import annotations
 
+import inspect
 import uuid
 from abc import abstractmethod
 from collections.abc import Mapping
@@ -854,8 +855,19 @@ class TableFunctionBase[TArgs](vgi.function.Function):
                             cls.FunctionArguments = type_args[0]
                         break
 
-        # Skip validation for abstract base classes
-        is_abstract = any(getattr(getattr(cls, name, None), "__isabstractmethod__", False) for name in dir(cls))
+        # Skip validation for abstract base classes. Each attribute is read with
+        # getattr_static, which returns the raw class attribute without invoking
+        # descriptors: a plain getattr() here resolved the inherited
+        # `Function.storage` descriptor, whose first access builds the default
+        # SQLite store on disk. Because vgi defines subclasses of its own, that
+        # made `import vgi` alone create a database under the user's state
+        # directory, and fail outright where that directory is not writable (a
+        # container's non-root user, say). The raw attribute answers the same
+        # question: classmethod, staticmethod and property objects all expose
+        # the `__isabstractmethod__` of what they wrap.
+        is_abstract = any(
+            getattr(inspect.getattr_static(cls, name, None), "__isabstractmethod__", False) for name in dir(cls)
+        )
         if is_abstract:
             cls._setting_params = {}
             cls._secret_params = {}