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

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

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

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

{vgi_python-0.8.4 → vgi_python-0.8.5}/tests/test_argument_spec.py

@@ -12,6 +12,7 @@ import pytest
 from vgi.argument_spec import (
     VGI_ARG_KEY,
     VGI_ARG_NAMED,
+    VGI_DOC_KEY,
     VGI_TYPE_ANY,
     VGI_TYPE_KEY,
     VGI_TYPE_TABLE,
@@ -674,3 +675,50 @@ class TestArgumentSpecRepr:
         )
         result = repr(spec)
         assert "any_type" in result
+
+
+class TestArgumentDoc:
+    """Per-argument description via the vgi_doc field-metadata key."""
+
+    def test_doc_serialized_as_utf8_field_metadata(self) -> None:
+        """A non-empty doc is emitted as the vgi_doc field metadata (UTF-8)."""
+        specs = [ArgumentSpec(name="unit", position=0, arrow_type=pa.utf8(), doc="Source unit, e.g. 'mi'")]
+        schema = argument_specs_to_schema(specs)
+        meta = schema.field("unit").metadata or {}
+        assert meta.get(VGI_DOC_KEY) == b"Source unit, e.g. 'mi'"
+
+    def test_doc_absent_when_empty(self) -> None:
+        """Presence-only: an empty doc emits no vgi_doc key (absent = undocumented)."""
+        specs = [ArgumentSpec(name="x", position=0, arrow_type=pa.int64())]
+        schema = argument_specs_to_schema(specs)
+        meta = schema.field("x").metadata or {}
+        assert VGI_DOC_KEY not in meta
+
+    def test_doc_round_trips(self) -> None:
+        """Doc survives schema -> specs round-trip; missing doc decodes to ''."""
+        specs = [
+            ArgumentSpec(name="a", position=0, arrow_type=pa.int64(), doc="first arg"),
+            ArgumentSpec(name="b", position=1, arrow_type=pa.utf8()),
+        ]
+        out = schema_to_argument_specs(argument_specs_to_schema(specs))
+        by_name = {s.name: s for s in out}
+        assert by_name["a"].doc == "first arg"
+        assert by_name["b"].doc == ""
+
+    def test_doc_unicode_round_trips(self) -> None:
+        """Non-ASCII docs (µ, ≥, em-dash) survive the UTF-8 round-trip."""
+        doc = "value in µm — must be ≥ 1"
+        specs = [ArgumentSpec(name="v", position=0, arrow_type=pa.float64(), doc=doc)]
+        out = schema_to_argument_specs(argument_specs_to_schema(specs))
+        assert out[0].doc == doc
+
+    def test_extract_doc_from_arg(self) -> None:
+        """extract_argument_specs captures the Arg(doc=...) string."""
+
+        class FunctionWithDocs(TableInOutFunction):  # type: ignore[type-arg]
+            unit: str = Arg[str](0, doc="Unit string, e.g. 'mi'")  # type: ignore[assignment]
+            scale: float = Arg[float](1)  # type: ignore[assignment]
+
+        specs = {s.name: s for s in extract_argument_specs(FunctionWithDocs)}
+        assert specs["unit"].doc == "Unit string, e.g. 'mi'"
+        assert specs["scale"].doc == ""

{vgi_python-0.8.4 → vgi_python-0.8.5}/vgi/argument_spec.py

@@ -38,6 +38,7 @@ __all__ = [
     "VGI_VARARGS_TRUE",
     "VGI_CONST_KEY",
     "VGI_CONST_TRUE",
+    "VGI_DOC_KEY",
 ]
 
 # =============================================================================
@@ -61,6 +62,11 @@ VGI_VARARGS_TRUE = b"true"
 VGI_CONST_KEY = b"vgi_const"
 VGI_CONST_TRUE = b"true"
 
+# Key carrying the per-argument description (UTF-8 text). Presence-only: the key
+# is omitted entirely when there is no doc (absent = undocumented). The
+# ``vgi_doc_*`` prefix is reserved for future per-argument doc variants.
+VGI_DOC_KEY = b"vgi_doc"
+
 
 def _argument_spec_sort_key(spec: "ArgumentSpec") -> tuple[int, int | str]:
     """Sort key: positional first (by index), then named (alphabetically)."""
@@ -98,6 +104,9 @@ class ArgumentSpec:
         is_const: True if this argument is constant-folded ([`ConstParam`][]).
             Constant arguments are scalar values known at planning time,
             rather than columnar data processed at runtime.
+        doc: Optional human/agent-facing description of the argument. Surfaced
+            through the catalog as the ``vgi_doc`` Arrow field metadata key
+            (UTF-8); empty string means undocumented.
 
     Note:
         For named arguments, the Python attribute name (``name``) and the SQL
@@ -119,6 +128,7 @@ class ArgumentSpec:
     is_any_type: bool = False
     is_varargs: bool = False
     is_const: bool = False
+    doc: str = ""
 
     def __repr__(self) -> str:
         """Return concise repr showing key attributes."""
@@ -197,6 +207,10 @@ def argument_specs_to_schema(specs: Sequence[ArgumentSpec]) -> pa.Schema:
         if spec.is_const:
             metadata[VGI_CONST_KEY] = VGI_CONST_TRUE
 
+        # Per-argument description (UTF-8; presence-only — omit when empty)
+        if spec.doc:
+            metadata[VGI_DOC_KEY] = spec.doc.encode("utf-8")
+
         # Create field with or without metadata
         field = pa.field(
             spec.name,
@@ -246,6 +260,10 @@ def schema_to_argument_specs(schema: pa.Schema) -> list[ArgumentSpec]:
         # Check const
         is_const = metadata.get(VGI_CONST_KEY) == VGI_CONST_TRUE
 
+        # Per-argument description (UTF-8; absent = undocumented)
+        doc_bytes = metadata.get(VGI_DOC_KEY)
+        doc = doc_bytes.decode("utf-8") if doc_bytes else ""
+
         specs.append(
             ArgumentSpec(
                 name=field.name,
@@ -255,6 +273,7 @@ def schema_to_argument_specs(schema: pa.Schema) -> list[ArgumentSpec]:
                 is_any_type=is_any_type,
                 is_varargs=is_varargs,
                 is_const=is_const,
+                doc=doc,
             )
         )
 
@@ -312,6 +331,7 @@ def extract_argument_specs(
                 is_any_type=param_arg.is_any,
                 is_varargs=param_arg.varargs,
                 is_const=False,
+                doc=param_arg.doc or "",
             )
         )
 
@@ -328,6 +348,7 @@ def extract_argument_specs(
                 is_any_type=const_arg.is_any,
                 is_varargs=const_arg.varargs,
                 is_const=True,
+                doc=const_arg.doc or "",
             )
         )
 
@@ -392,6 +413,7 @@ def extract_argument_specs(
                     is_any_type=is_any_type,
                     is_varargs=arg_instance.varargs,
                     is_const=getattr(arg_instance, "const", False),
+                    doc=getattr(arg_instance, "doc", "") or "",
                 )
             )
 
@@ -466,6 +488,7 @@ def extract_argument_specs(
                         is_any_type=is_any_type,
                         is_varargs=is_varargs,
                         is_const=is_const,
+                        doc=getattr(arg_legacy, "doc", "") or "",
                     )
                 )