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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.8.2
+Version: 0.8.4
 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.4}/pyproject.toml

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

{vgi_python-0.8.2 → vgi_python-0.8.4}/tests/catalog/test_declarative.py

@@ -1207,6 +1207,20 @@ class TestCatalogDescriptor:
         catalog = Catalog(name="myapp", schemas=[main, analytics])
         assert len(catalog.schemas) == 2
 
+    def test_catalog_source_url_defaults_to_none(self) -> None:
+        """Catalog source_url is None unless set."""
+        catalog = Catalog(name="myapp", schemas=[Schema(name="main")])
+        assert catalog.source_url is None
+
+    def test_catalog_source_url_settable(self) -> None:
+        """Catalog source_url can advertise the repo/docs homepage."""
+        catalog = Catalog(
+            name="myapp",
+            schemas=[Schema(name="main")],
+            source_url="https://github.com/example/myapp",
+        )
+        assert catalog.source_url == "https://github.com/example/myapp"
+
 
 class TestCatalogValidation:
     """Tests for Catalog validation."""
@@ -1311,6 +1325,25 @@ class TestReadOnlyCatalogWithCatalog:
         infos = catalog_interface.catalogs()
         assert [i.name for i in infos] == ["testapp"]
 
+    def test_catalogs_omits_source_url_when_unset(self, catalog_interface: ReadOnlyCatalogInterface) -> None:
+        """catalogs() yields source_url=None when the Catalog doesn't set one."""
+        infos = catalog_interface.catalogs()
+        assert infos[0].source_url is None
+
+    def test_catalogs_serializes_source_url(self, users_table: Table) -> None:
+        """catalogs() surfaces the Catalog.source_url into CatalogInfo."""
+
+        class SourcedCatalog(ReadOnlyCatalogInterface):
+            catalog = Catalog(
+                name="sourced",
+                default_schema="main",
+                schemas=[Schema(name="main", tables=[users_table])],
+                source_url="https://github.com/example/sourced",
+            )
+
+        infos = SourcedCatalog().catalogs()
+        assert infos[0].source_url == "https://github.com/example/sourced"
+
     def test_catalog_attach(self, catalog_interface: ReadOnlyCatalogInterface) -> None:
         """catalog_attach returns result with correct defaults."""
         result = catalog_interface.catalog_attach(

{vgi_python-0.8.2 → vgi_python-0.8.4}/tests/catalog/test_example_worker_catalog.py

@@ -78,6 +78,13 @@ class TestExampleWorkerCatalog:
         catalogs = client.catalogs()
         assert "example" in [c.name for c in catalogs]
 
+    def test_catalogs_advertises_source_url(self) -> None:
+        """The declarative catalog's source_url round-trips through discovery."""
+        client = Client(EXAMPLE_WORKER)
+        catalogs = client.catalogs()
+        example = next(c for c in catalogs if c.name == "example")
+        assert example.source_url == "https://github.com/query-farm/vgi-python"
+
     def test_catalog_attach_works(self) -> None:
         """Can attach to the 'example' catalog."""
         client = Client(EXAMPLE_WORKER)

{vgi_python-0.8.2 → vgi_python-0.8.4}/tests/test_metadata.py

@@ -613,3 +613,118 @@ class TestFunctionTypeInference:
 
         meta = resolve_metadata(TestFunc)
         assert meta.function_type == CatalogFunctionType.TABLE
+
+
+class TestFunctionTags:
+    """A worker can attach arbitrary free-form tags to a function's metadata.
+
+    These flow ``Meta.tags`` -> ``ResolvedMetadata.tags`` -> ``FunctionInfo.tags``
+    -> DuckDB's per-function ``tags`` map, which is what the ``vgi-lint-check``
+    metadata linter reads (e.g. VGI307 requires ``vgi.columns_md`` on a
+    dynamic-schema table function).
+    """
+
+    def test_meta_tags_resolved(self) -> None:
+        """Arbitrary Meta.tags land on ResolvedMetadata.tags verbatim."""
+
+        class TaggedFunction(TableInOutFunction):  # type: ignore[type-arg]
+            class Meta:
+                name = "tagged_func"
+                tags = {
+                    "vgi.columns_md": "| col | type |\n| --- | --- |\n| id | BIGINT |",
+                    "custom.team": "data",
+                }
+
+            data: TableInput = Arg[TableInput](0, doc="Input table")  # type: ignore[assignment]
+
+        meta = resolve_metadata(TaggedFunction)
+        assert meta.tags == {
+            "vgi.columns_md": "| col | type |\n| --- | --- |\n| id | BIGINT |",
+            "custom.team": "data",
+        }
+
+    def test_tags_survive_arrow_roundtrip(self) -> None:
+        """Function tags survive the metadata Arrow wire roundtrip (map column)."""
+
+        class TaggedFunction(TableInOutFunction):  # type: ignore[type-arg]
+            class Meta:
+                name = "tagged_func"
+                tags = {"vgi.columns_md": "| col |", "k": "v"}
+
+            data: TableInput = Arg[TableInput](0, doc="Input table")  # type: ignore[assignment]
+
+        restored = arrow_to_functions(functions_to_arrow([TaggedFunction]))[0]
+        assert restored.tags == {"vgi.columns_md": "| col |", "k": "v"}
+
+    def test_tags_and_examples_are_independent(self) -> None:
+        """Worker tags do not clobber the structured examples, and vice versa.
+
+        ``examples`` is its own structured channel (serialized to the
+        ``examples`` struct column / ``FunctionInfo.examples``); it is never
+        folded into the ``tags`` map. A worker that *also* sets a
+        ``vgi.example_queries`` tag (the tag-encoded examples convention the
+        linter understands) keeps both — the tag is preserved untouched and the
+        structured examples remain separate.
+        """
+
+        class BothFunction(TableInOutFunction):  # type: ignore[type-arg]
+            class Meta:
+                name = "both_func"
+                examples = ["SELECT * FROM both_func((SELECT 1))"]
+                tags = {
+                    "vgi.example_queries": '[{"description":"x","sql":"SELECT tag"}]',
+                    "vgi.columns_md": "| col |",
+                }
+
+            data: TableInput = Arg[TableInput](0, doc="Input table")  # type: ignore[assignment]
+
+        meta = resolve_metadata(BothFunction)
+        # Worker-provided tags untouched (example_queries tag not derived, not dropped).
+        assert meta.tags == {
+            "vgi.example_queries": '[{"description":"x","sql":"SELECT tag"}]',
+            "vgi.columns_md": "| col |",
+        }
+        # Structured examples live independently and are not merged into tags.
+        assert [ex.sql for ex in meta.examples] == ["SELECT * FROM both_func((SELECT 1))"]
+
+    def test_tags_flow_into_function_info(self) -> None:
+        """Tags reach ``FunctionInfo.tags`` (catalog -> DuckDB -> linter path).
+
+        Also asserts that the structured ``examples`` and the worker-set
+        ``vgi.example_queries`` tag coexist on ``FunctionInfo`` without either
+        clobbering the other.
+        """
+        from vgi.catalog.catalog_interface import (
+            FunctionInfo,
+            ReadOnlyCatalogInterface,
+        )
+        from vgi.table_function import TableFunctionGenerator
+
+        class DynamicTable(TableFunctionGenerator):  # type: ignore[type-arg]
+            class Meta:
+                name = "dynamic_table"
+                examples = ["SELECT * FROM dynamic_table()"]
+                tags = {
+                    "vgi.columns_md": "| col | type |\n| --- | --- |\n| id | BIGINT |",
+                    "vgi.example_queries": '[{"description":"x","sql":"SELECT 1"}]',
+                    "custom.team": "data",
+                }
+
+            FIXED_SCHEMA = pa.schema([pa.field("id", pa.int64())])
+
+            def process(self, params):  # type: ignore[no-untyped-def]
+                yield pa.record_batch({"id": [1]})
+
+        class Cat(ReadOnlyCatalogInterface):
+            catalog_name = "functions"
+            functions = [DynamicTable]
+
+        info = Cat()._function_to_info(DynamicTable, "main")
+        assert isinstance(info, FunctionInfo)
+        assert info.tags == {
+            "vgi.columns_md": "| col | type |\n| --- | --- |\n| id | BIGINT |",
+            "vgi.example_queries": '[{"description":"x","sql":"SELECT 1"}]',
+            "custom.team": "data",
+        }
+        # Structured examples are carried separately from the tag-encoded ones.
+        assert [ex.sql for ex in info.examples] == ["SELECT * FROM dynamic_table()"]

vgi_python-0.8.4/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.4}/uv.lock

@@ -2250,7 +2250,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.8.2"
+version = "0.8.4"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

{vgi_python-0.8.2 → vgi_python-0.8.4}/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.4}/vgi/_test_fixtures/table/_common.py

@@ -61,7 +61,7 @@ class CountBatchArgs:
     """
 
     count: Annotated[int, Arg(0, doc="Number of rows to generate", ge=0)]
-    batch_size: Annotated[int, Arg("batch_size", default=1000, doc="Batch size for output", ge=1)]
+    batch_size: Annotated[int, Arg("batch_size", default=2048, doc="Batch size for output", ge=1)]
 
 
 @dataclass(slots=True, frozen=True)
@@ -91,7 +91,7 @@ class _BaseSequenceFunction(TableFunctionGenerator[Any, CountdownState]):
     NUMPY_DTYPE: ClassVar[type[np.generic]] = np.int64
     STATS_ARROW_TYPE: ClassVar[pa.DataType] = pa.int64()
     STATS_COLUMN_NAME: ClassVar[str] = "n"
-    BATCH_SIZE_FALLBACK: ClassVar[int] = 1000
+    BATCH_SIZE_FALLBACK: ClassVar[int] = 2048
 
     @classmethod
     def initial_state(cls, params: ProcessParams[Any]) -> CountdownState:

{vgi_python-0.8.2 → vgi_python-0.8.4}/vgi/_test_fixtures/worker.py

@@ -320,6 +320,7 @@ _EXAMPLE_CATALOG = Catalog(
     default_schema="main",
     comment="Example VGI catalog for testing",
     tags={"source": "vgi-fixture-worker", "version": "1"},
+    source_url="https://github.com/query-farm/vgi-python",
     schemas=[
         Schema(
             name="main",

{vgi_python-0.8.2 → vgi_python-0.8.4}/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.2 → vgi_python-0.8.4}/vgi/catalog/catalog_interface.py

@@ -2319,6 +2319,7 @@ class ReadOnlyCatalogInterface(CatalogInterface):
                 implementation_version=None,
                 data_version_spec=None,
                 attach_option_specs=[spec.serialize() for spec in self.attach_option_specs],
+                source_url=self.catalog.source_url if self.catalog is not None else None,
             )
         ]
 

{vgi_python-0.8.2 → vgi_python-0.8.4}/vgi/catalog/descriptors.py

@@ -873,6 +873,10 @@ class Catalog:
         schemas: Sequence of Schema objects defining the catalog contents.
         comment: Optional comment describing the catalog.
         tags: Optional key-value tags associated with the catalog.
+        source_url: Where this worker's code lives — repo, build, or docs
+            homepage. ``None`` (the default) when the worker doesn't advertise
+            a source location. Surfaced via the ``catalog_catalogs()`` discovery
+            record (``CatalogInfo.source_url``).
 
     """
 
@@ -881,6 +885,7 @@ class Catalog:
     schemas: Sequence[Schema] = ()
     comment: str | None = None
     tags: dict[str, str] = field(default_factory=dict)
+    source_url: str | None = None
 
     def __post_init__(self) -> None:
         """Validate catalog configuration."""