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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.31.0"
+version = "0.31.1"
 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.1}/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.1}/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.1}/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.1}/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())),