vgi-python 0.31.0__tar.gz → 0.31.2__tar.gz

{vgi_python-0.31.0 → vgi_python-0.31.2}/PKG-INFO

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

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

{vgi_python-0.31.0 → vgi_python-0.31.2}/tests/test_metadata.py

@@ -64,6 +64,32 @@ class TestResolveMetadata:
         assert meta.categories == ["transform", "utility"]
         assert meta.max_workers == 4
 
+    def test_comment_defaults_to_none(self) -> None:
+        """Meta.comment is unset by default -- unlike description, no docstring fallback."""
+
+        class UndocumentedCommentFunction(TableInOutFunction):  # type: ignore[type-arg]
+            """A function with only a docstring, no Meta.comment."""
+
+            data: TableInput = Arg[TableInput](0, doc="Input table")  # type: ignore[assignment]
+
+        meta = UndocumentedCommentFunction.get_metadata()
+        assert meta.comment is None
+
+    def test_function_with_comment(self) -> None:
+        """Meta.comment is a short operator-facing note, distinct from description."""
+
+        class DeprecatedFunction(TableInOutFunction):  # type: ignore[type-arg]
+            class Meta:
+                name = "deprecated_func"
+                description = "Does the thing"
+                comment = "deprecated, use deprecated_func_v2 instead"
+
+            data: TableInput = Arg[TableInput](0, doc="Input table")  # type: ignore[assignment]
+
+        meta = DeprecatedFunction.get_metadata()
+        assert meta.description == "Does the thing"
+        assert meta.comment == "deprecated, use deprecated_func_v2 instead"
+
     def test_name_auto_generation(self) -> None:
         """Function name is auto-generated from class name."""
 
@@ -727,3 +753,45 @@ class TestFunctionTags:
         }
         # Structured examples are carried separately from the tag-encoded ones.
         assert [ex.sql for ex in info.examples] == ["SELECT * FROM dynamic_table()"]
+
+    def test_comment_flows_into_function_info(self) -> None:
+        """Meta.comment reaches FunctionInfo.comment (the field every other catalog object already has)."""
+        from vgi.catalog.catalog_interface import (
+            FunctionInfo,
+            ReadOnlyCatalogInterface,
+        )
+        from vgi.table_function import ProcessParams, TableFunctionGenerator
+
+        class CommentedTable(TableFunctionGenerator):  # type: ignore[type-arg]
+            class Meta:
+                name = "commented_table"
+                comment = "internal — do not call directly"
+
+            FIXED_SCHEMA = pa.schema([pa.field("id", pa.int64())])
+
+            @classmethod
+            def process(cls, params: ProcessParams[Any], state: None, out: OutputCollector) -> None:
+                out.emit(pa.record_batch({"id": [1]}))
+                out.finish()
+
+        class UncommentedTable(TableFunctionGenerator):  # type: ignore[type-arg]
+            class Meta:
+                name = "uncommented_table"
+
+            FIXED_SCHEMA = pa.schema([pa.field("id", pa.int64())])
+
+            @classmethod
+            def process(cls, params: ProcessParams[Any], state: None, out: OutputCollector) -> None:
+                out.emit(pa.record_batch({"id": [1]}))
+                out.finish()
+
+        class Cat(ReadOnlyCatalogInterface):
+            catalog_name = "functions"
+            functions = [CommentedTable, UncommentedTable]
+
+        commented_info = Cat()._function_to_info(CommentedTable, "main")
+        assert isinstance(commented_info, FunctionInfo)
+        assert commented_info.comment == "internal — do not call directly"
+
+        uncommented_info = Cat()._function_to_info(UncommentedTable, "main")
+        assert uncommented_info.comment is None

{vgi_python-0.31.0 → vgi_python-0.31.2}/tests/test_setting_secret_annotations.py

@@ -237,6 +237,68 @@ class TestTableFunctionSettingAnnotations:
         assert "details" in table.schema.names  # verbose mode adds details column
         assert table.column("greeting").to_pylist() == ["Hola", "Hola", "Hola"]
 
+    def test_secret_delivers_dict_of_scalars(self, fixture_worker: str) -> None:
+        """SecretDemoFunction (table function) receives a client-supplied secret.
+
+        Regression for `Client.table_function` hardcoding `secrets=None` on
+        the wire — the same `vgi_example` secret shape already proven to work
+        for `ReturnSecretValueFunction` (scalar) above, now exercised through
+        the table-function path instead.
+        """
+        from vgi.client import Client
+
+        # SecretDemoFunction resolves via `params.secrets.of_type("vgi_example")`
+        # (not the `Secret()`-annotation path `test_secret_delivers_dict_of_scalars`
+        # above uses), which filters on the secret payload's OWN `type` field —
+        # so, unlike that test's arbitrary `"type": "test"`, this one must be
+        # `"type": "vgi_example"` to match.
+        secret_value = {"type": "vgi_example", "provider": "config", "secret_string": "s3cr3t"}
+
+        with Client(fixture_worker) as client:
+            outputs = list(
+                client.table_function(
+                    function_name="secret_demo",
+                    schema_name="main",
+                    secrets={"vgi_example": secret_value},
+                )
+            )
+
+        table = pa.Table.from_batches(outputs)
+        assert dict(zip(table.column("key").to_pylist(), table.column("value").to_pylist(), strict=True)) == {
+            "type": "vgi_example",
+            "provider": "config",
+            "secret_string": "s3cr3t",
+        }
+
+    def test_secret_delivers_to_table_in_out_function(self, fixture_worker: str) -> None:
+        """SecretInOutFunction receives a client-supplied secret.
+
+        Regression for `Client.table_in_out_function` hardcoding `secrets=None`
+        on the wire — the fixture (`secret_in_out`) already existed but had no
+        test exercising it end to end, which is exactly how the bug went
+        unnoticed.
+        """
+        from vgi.client import Client
+
+        # Same `of_type("vgi_example")` resolution as SecretDemoFunction above —
+        # the payload's own `type` field must equal the requested secret_type.
+        secret_value = {"type": "vgi_example", "provider": "config", "secret_string": "s3cr3t"}
+        batch = pa.RecordBatch.from_pydict({"n": [1, 2]})
+
+        with Client(fixture_worker) as client:
+            outputs = list(
+                client.table_in_out_function(
+                    function_name="secret_in_out",
+                    schema_name="main",
+                    input=iter([batch]),
+                    secrets={"vgi_example": secret_value},
+                )
+            )
+
+        table = pa.Table.from_batches(outputs)
+        assert table.column("n").to_pylist() == [1, 2]
+        assert table.column("secret_string").to_pylist() == ["s3cr3t", "s3cr3t"]
+
 
 # ---------------------------------------------------------------------------
 # Tests for auto-population of Meta.required_settings/required_secrets

{vgi_python-0.31.0 → vgi_python-0.31.2}/uv.lock

@@ -2569,7 +2569,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.31.0"
+version = "0.31.2"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

{vgi_python-0.31.0 → vgi_python-0.31.2}/vgi/_test_fixtures/scalar/arithmetic.py

@@ -37,6 +37,10 @@ class MultiplyFunction(ScalarFunction):
 
         name = "multiply"
         description = "Multiplies a value by a constant factor"
+        # Meta.comment fixture: a short operator-facing note distinct from
+        # `description` — exercised by test_multiply_function_comment and
+        # the C++ integration test function_arguments.test.
+        comment = "fixture function for scalar bind-parameter tests"
         examples = [
             FunctionExample(
                 sql="SELECT multiply(price, 2) FROM products",

{vgi_python-0.31.0 → vgi_python-0.31.2}/vgi/catalog/catalog_interface.py

@@ -649,8 +649,11 @@ class FunctionInfo(CatalogSchemaObject, ArrowSerializableDataclass):
         null_handling: Scalar function behavior field (None for non-scalar
             functions).
         description: Intrinsic documentation from function metadata
-            (``Meta.description``). The user-settable ``comment`` (via COMMENT ON
-            FUNCTION) is inherited from the base object.
+            (``Meta.description``). ``comment`` (inherited from the base
+            object) is a separate, shorter operator-facing note from
+            ``Meta.comment`` — e.g. "deprecated, use v2". Both are static:
+            there is no ``COMMENT ON FUNCTION`` RPC, unlike tables/views,
+            whose ``comment`` is dynamically settable.
         examples: Usage examples for the function.
         categories: Category labels for the function.
         projection_pushdown: Table-function capability (None for scalar
@@ -3389,7 +3392,7 @@ class ReadOnlyCatalogInterface(CatalogInterface):
             function_type=func_type,
             arguments=args_bytes,
             output_schema=output_bytes,
-            comment=None,  # Functions don't use comment; use description instead
+            comment=meta.comment,  # Static, Meta-declared only — see Meta.comment
             tags=meta.tags,
             # Scalar/aggregate function behavior fields
             stability=meta.stability if is_scalar else None,

{vgi_python-0.31.0 → vgi_python-0.31.2}/vgi/client/client.py

@@ -2014,6 +2014,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
         projection_ids: list[int] | None = None,
         pushdown_filters: bytes | None = None,
         settings: dict[str, Any] | None = None,
+        secrets: dict[str, Any] | None = None,
         transaction_opaque_data: bytes | None = None,
         parent_row_callback: Callable[[list[int]], None] | None = None,
         has_finalize: bool = True,
@@ -2043,6 +2044,8 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 to push down to the function.
             settings: Optional dictionary of settings/pragmas to
                 pass to the function.
+            secrets: Optional dictionary of secret name to value pairs.
+                Values can be simple scalars or dicts (for struct-typed secrets).
             transaction_opaque_data: Optional unique identifier for the DuckDB transaction.
             parent_row_callback: Optional callback invoked once per yielded
                 output batch (before finalize), immediately before the yield,
@@ -2108,7 +2111,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                     function_type=FunctionType.TABLE,
                     input_schema=input_schema,
                     settings=settings,
-                    secrets=None,
+                    secrets=secrets,
                     transaction_opaque_data=transaction_opaque_data,
                     projection_ids=projection_ids,
                     pushdown_filters_batch=pushdown_filters_batch,
@@ -2173,6 +2176,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
         projection_ids: list[int] | None = None,
         pushdown_filters: bytes | None = None,
         settings: dict[str, Any] | None = None,
+        secrets: dict[str, Any] | None = None,
         transaction_opaque_data: bytes | None = None,
         copy_to: CopyToContext | None = None,
         input_schema: pa.Schema | None = None,
@@ -2215,6 +2219,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             projection_ids: Optional column indices for projection.
             pushdown_filters: Optional serialized filter predicates.
             settings: Optional settings/pragmas to pass to the function.
+            secrets: Optional dictionary of secret name to value pairs.
             transaction_opaque_data: Optional DuckDB transaction identifier.
             copy_to: Optional [`CopyToContext`][] marking this sink as a
                 ``COPY ... TO`` write. A ``CopyToFunction`` returns no finalize
@@ -2261,7 +2266,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 function_type=FunctionType.TABLE_BUFFERING,
                 input_schema=input_schema,
                 settings=settings,
-                secrets=None,
+                secrets=secrets,
                 transaction_opaque_data=transaction_opaque_data,
                 copy_to=copy_to,
             )
@@ -2422,6 +2427,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
         projection_ids: list[int] | None = None,
         pushdown_filters: bytes | None = None,
         settings: dict[str, Any] | None = None,
+        secrets: dict[str, Any] | None = None,
         transaction_opaque_data: bytes | None = None,
         target_split_bytes: int | None = None,
         min_splits: int | None = None,
@@ -2460,6 +2466,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             pushdown_filters: Optional byte string of filter predicates,
                 same wire format as :meth:`table_function`'s.
             settings: Optional dictionary of settings/pragmas.
+            secrets: Optional dictionary of secret name to value pairs.
             transaction_opaque_data: Optional transaction identifier.
             target_split_bytes: Requested split size — the primary sizing
                 lever; the client can't see per-split cost and will treat
@@ -2499,7 +2506,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 arguments=arguments,
                 function_type=FunctionType.TABLE,
                 settings=settings,
-                secrets=None,
+                secrets=secrets,
                 transaction_opaque_data=transaction_opaque_data,
             )
             bind_response = self._do_bind(self._primary.proxy, bind_request, None)
@@ -2542,6 +2549,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
         projection_ids: list[int] | None = None,
         pushdown_filters: bytes | None = None,
         settings: dict[str, Any] | None = None,
+        secrets: dict[str, Any] | None = None,
         transaction_opaque_data: bytes | None = None,
         copy_from: CopyFromContext | None = None,
         split_tokens: list[bytes] | None = None,
@@ -2577,6 +2585,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 to push down to the function.
             settings: Optional dictionary of settings/pragmas to
                 pass to the function.
+            secrets: Optional dictionary of secret name to value pairs.
             transaction_opaque_data: Optional unique identifier for the DuckDB transaction.
             copy_from: Optional [`CopyFromContext`][] marking this scan as a
                 ``COPY ... FROM`` read. Prefer :meth:`copy_from`, which builds
@@ -2640,7 +2649,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 function_type=FunctionType.TABLE,
                 input_schema=None,
                 settings=settings,
-                secrets=None,
+                secrets=secrets,
                 transaction_opaque_data=transaction_opaque_data,
                 projection_ids=projection_ids,
                 pushdown_filters_batch=pushdown_filters_batch,
@@ -2678,6 +2687,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
         projection_ids: list[int] | None = None,
         pushdown_filters: bytes | None = None,
         settings: dict[str, Any] | None = None,
+        secrets: dict[str, Any] | None = None,
         transaction_opaque_data: bytes | None = None,
         resume_token: bytes | None = None,
     ) -> ResumableTableScan:
@@ -2703,6 +2713,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 pushdown). ``None`` selects all columns.
             pushdown_filters: Optional serialized filter-pushdown payload.
             settings: Optional DuckDB settings to apply for the scan.
+            secrets: Optional dictionary of secret name to value pairs.
             transaction_opaque_data: Optional catalog transaction handle.
             resume_token: Continuation token from a prior batch to resume from;
                 must be paired with the same ``function_name``/projection/
@@ -2737,7 +2748,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 function_type=FunctionType.TABLE,
                 input_schema=None,
                 settings=settings,
-                secrets=None,
+                secrets=secrets,
                 transaction_opaque_data=transaction_opaque_data,
             )
             bind_response = self._do_bind(self._primary.proxy, bind_request, None)

{vgi_python-0.31.0 → vgi_python-0.31.2}/vgi/metadata.py

@@ -360,6 +360,12 @@ class ResolvedMetadata:
         function_type: The [`CatalogFunctionType`][] (scalar, table, aggregate,
             or table-buffering).
         description: Human-readable description of the function.
+        comment: Short operator-facing note (e.g. "deprecated, use v2" or
+            "internal — do not call directly"), distinct from `description`'s
+            intrinsic documentation. Mirrors the `comment` every other catalog
+            object (table/view/schema) already carries — functions only had
+            `description` until now. Static (Meta-declared) only; there is no
+            `COMMENT ON FUNCTION` RPC to change it at runtime.
         examples: SQL usage examples for the function.
         categories: Classification/category labels.
         tags: Free-form key/value metadata tags.
@@ -430,6 +436,7 @@ class ResolvedMetadata:
 
     # Documentation
     description: str = ""
+    comment: str | None = None
     examples: list[FunctionExample] = field(default_factory=list)
     categories: list[str] = field(default_factory=list)
     tags: dict[str, str] = field(default_factory=dict)
@@ -518,6 +525,7 @@ class ResolvedMetadata:
             "class_name": self.class_name,
             "function_type": self.function_type.name,
             "description": self.description,
+            "comment": self.comment,
             "examples": [ex.to_dict() for ex in self.examples],
             "categories": self.categories,
             "tags": self.tags,
@@ -558,6 +566,7 @@ class ResolvedMetadata:
             class_name=d["class_name"],
             function_type=CatalogFunctionType[d["function_type"]],
             description=d.get("description", ""),
+            comment=d.get("comment"),
             examples=[FunctionExample.from_dict(ex) for ex in d.get("examples", [])],
             categories=d.get("categories", []),
             tags=dict(d.get("tags", {})),
@@ -962,6 +971,7 @@ _VALID_META_ATTRIBUTES: frozenset[str] = frozenset(
         # Common
         "name",
         "description",
+        "comment",
         "examples",
         "categories",
         "tags",
@@ -1135,6 +1145,10 @@ def resolve_metadata(cls: type) -> ResolvedMetadata:
     if not description and cls.__doc__:
         description = cls.__doc__.strip().split("\n")[0]
 
+    # comment has no docstring fallback (unlike description) — it's a
+    # deliberate operator-facing opt-in, not something to infer.
+    comment = attrs.get("comment")
+
     # Normalize examples
     examples = _normalize_examples(attrs.get("examples", []))
 
@@ -1223,6 +1237,7 @@ def resolve_metadata(cls: type) -> ResolvedMetadata:
         class_name=class_name,
         function_type=function_type,
         description=description,
+        comment=comment,
         examples=examples,
         categories=attrs.get("categories", []),
         tags=dict(attrs.get("tags", {})),
@@ -1399,6 +1414,7 @@ _METADATA_SCHEMA = pa.schema(
         pa.field("class_name", pa.string()),
         pa.field("function_type", pa.string()),
         pa.field("description", pa.string()),
+        pa.field("comment", pa.string(), nullable=True),
         pa.field("examples", pa.list_(_EXAMPLE_STRUCT)),
         pa.field("categories", pa.list_(pa.string())),
         pa.field("tags", pa.map_(pa.string(), pa.string())),