vgi-python 0.11.1__tar.gz → 0.13.0__tar.gz

{vgi_python-0.11.1 → vgi_python-0.13.0}/PKG-INFO

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

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

{vgi_python-0.11.1 → vgi_python-0.13.0}/tests/landing/describe.expected.json

@@ -3,7 +3,7 @@
     {
       "attach_options": [],
       "counts": {
-        "functions": 162,
+        "functions": 165,
         "schemas": 2,
         "tables": 44,
         "views": 3
@@ -14,6 +14,7 @@
       "name": "example",
       "schemas": [
         {
+          "doc": "Example tables backed by functions",
           "functions": [],
           "name": "data",
           "tables": [
@@ -248,6 +249,7 @@
           ]
         },
         {
+          "doc": "Example functions for testing VGI",
           "functions": [
             {
               "args": [
@@ -1114,6 +1116,49 @@
               "returns": "string",
               "type": "scalar"
             },
+            {
+              "args": [
+                {
+                  "desc": "Value to clamp",
+                  "name": "val",
+                  "type": "ANY"
+                },
+                {
+                  "default": "0",
+                  "desc": "Lower bound (inclusive)",
+                  "name": "lo",
+                  "named": true,
+                  "type": "int64"
+                },
+                {
+                  "default": "100",
+                  "desc": "Upper bound (inclusive)",
+                  "name": "hi",
+                  "named": true,
+                  "type": "int64"
+                }
+              ],
+              "doc": "Clamp a value between lo and hi (defaults: 0..100)",
+              "name": "vgi_clamp",
+              "type": "scalar"
+            },
+            {
+              "args": [
+                {
+                  "desc": "First factor",
+                  "name": "x",
+                  "type": "ANY"
+                },
+                {
+                  "desc": "Second factor",
+                  "name": "y",
+                  "type": "ANY"
+                }
+              ],
+              "doc": "Multiply two values",
+              "name": "vgi_multiply",
+              "type": "scalar"
+            },
             {
               "args": [
                 {
@@ -2206,12 +2251,6 @@
               "name": "struct_settings",
               "type": "table"
             },
-            {
-              "args": [],
-              "doc": "Distributed sum using simple callback API",
-              "name": "sum_all_columns_simple_distributed",
-              "type": "table_in_out"
-            },
             {
               "args": [],
               "doc": "Generates 10000 integers from 0 to 9999",
@@ -2361,6 +2400,18 @@
               "name": "versioned_data_scan",
               "type": "table"
             },
+            {
+              "args": [
+                {
+                  "desc": "Number of rows to generate",
+                  "name": "n",
+                  "type": "ANY"
+                }
+              ],
+              "doc": "Table macro returning range of values",
+              "name": "vgi_range_table",
+              "type": "table"
+            },
             {
               "args": [],
               "doc": "buffer_input variant using batch_index to reconstruct order",
@@ -2610,6 +2661,12 @@
               "doc": "Computes column-wise sums across all batches",
               "name": "sum_all_columns",
               "type": "table_in_out"
+            },
+            {
+              "args": [],
+              "doc": "Distributed sum using simple callback API",
+              "name": "sum_all_columns_simple_distributed",
+              "type": "table_in_out"
             }
           ],
           "name": "main",

vgi_python-0.13.0/tests/landing/describe.schema.json

@@ -0,0 +1,402 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://query.farm/vgi/describe.schema.json",
+  "title": "VGI worker describe.json (landing contract)",
+  "description": "Validates GET {prefix}/describe.json. See docs/http-landing-contract.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "landing_schema_version",
+    "worker",
+    "server_id",
+    "oauth",
+    "cupola_base",
+    "catalogs"
+  ],
+  "properties": {
+    "landing_schema_version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "worker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "doc",
+        "version",
+        "lang"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "doc": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        },
+        "lang": {
+          "enum": [
+            "python",
+            "go",
+            "rust",
+            "typescript",
+            "java"
+          ]
+        }
+      }
+    },
+    "server_id": {
+      "type": "string"
+    },
+    "oauth": {
+      "type": "boolean"
+    },
+    "cupola_base": {
+      "type": "string",
+      "format": "uri"
+    },
+    "catalogs": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/catalog"
+      }
+    }
+  },
+  "$defs": {
+    "catalog": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "implementation_version",
+        "data_version_spec",
+        "data_versions",
+        "attach_options",
+        "tags",
+        "counts",
+        "schemas"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "implementation_version": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "data_version_spec": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "data_versions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/dataVersion"
+          }
+        },
+        "attach_options": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/attachOption"
+          }
+        },
+        "tags": {
+          "$ref": "#/$defs/tags"
+        },
+        "counts": {
+          "$ref": "#/$defs/counts"
+        },
+        "schemas": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/schema"
+          }
+        }
+      }
+    },
+    "dataVersion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "spec"
+      ],
+      "properties": {
+        "spec": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        }
+      }
+    },
+    "attachOption": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "type",
+        "default",
+        "description"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        },
+        "default": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    },
+    "tags": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "title": {
+          "type": "string"
+        },
+        "doc_md": {
+          "type": "string"
+        },
+        "source_url": {
+          "type": "string"
+        },
+        "license": {
+          "type": "string"
+        },
+        "author": {
+          "type": "string"
+        },
+        "copyright": {
+          "type": "string"
+        },
+        "support_contact": {
+          "type": "string"
+        },
+        "support_policy_url": {
+          "type": "string"
+        },
+        "keywords": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "counts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemas",
+        "tables",
+        "views",
+        "functions"
+      ],
+      "properties": {
+        "schemas": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "tables": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "views": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "functions": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "tables",
+        "views",
+        "functions"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "doc": {
+          "type": "string",
+          "description": "Schema comment/description (optional, may be Markdown)"
+        },
+        "tables": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/table"
+          }
+        },
+        "views": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/view"
+          }
+        },
+        "functions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/function"
+          }
+        }
+      }
+    },
+    "table": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "cols",
+        "comment"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "cols": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "comment": {
+          "type": "string"
+        }
+      }
+    },
+    "view": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "cols",
+        "comment",
+        "def"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "cols": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "comment": {
+          "type": "string"
+        },
+        "def": {
+          "type": "string"
+        }
+      }
+    },
+    "function": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "type",
+        "doc",
+        "args"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "type": {
+          "enum": [
+            "scalar",
+            "table",
+            "aggregate",
+            "table_in_out"
+          ]
+        },
+        "doc": {
+          "type": "string"
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/arg"
+          }
+        },
+        "returns": {
+          "type": "string"
+        }
+      }
+    },
+    "arg": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "type"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        },
+        "named": {
+          "type": "boolean"
+        },
+        "default": {
+          "type": "string"
+        },
+        "desc": {
+          "type": "string"
+        }
+      }
+    },
+    "columns": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "columns"
+      ],
+      "properties": {
+        "columns": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "name",
+              "type"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "comment": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

{vgi_python-0.11.1 → vgi_python-0.13.0}/uv.lock

@@ -2228,7 +2228,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.11.1"
+version = "0.13.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

{vgi_python-0.11.1 → vgi_python-0.13.0}/vgi/http/describe_json.py

@@ -17,6 +17,7 @@ See ``~/Development/vgi/docs/http-landing-contract.md`` for the normative spec.
 
 from __future__ import annotations
 
+import contextlib
 import json
 import logging
 from importlib.metadata import version as _pkg_version
@@ -37,6 +38,8 @@ from vgi.catalog.catalog_interface import (
     CatalogInterface,
     FunctionInfo,
     FunctionType,
+    MacroInfo,
+    MacroType,
     SchemaObjectType,
     TableInfo,
     ViewInfo,
@@ -190,6 +193,68 @@ def _function_args(fn: FunctionInfo) -> list[dict[str, Any]]:
     return args
 
 
+def _macro_display_type(m: MacroInfo) -> str:
+    # A scalar macro is invoked exactly like a scalar function in SQL, and a
+    # table macro like a table function; surface them in the same buckets so the
+    # landing page lists a catalog's full callable surface (VGI workers commonly
+    # expose their "functions" as declarative macros — see vgi-volcanos).
+    return "scalar" if m.macro_type == MacroType.SCALAR else "table"
+
+
+def _macro_args(m: MacroInfo) -> list[dict[str, Any]]:
+    # Defaulted parameters are optional and callable by name in DuckDB, so we
+    # present them as named args (with their default); the rest are positional.
+    defaults: dict[str, Any] = {}
+    if m.parameter_default_values is not None:
+        batch = m.parameter_default_values
+        for col_name in batch.schema.names:
+            with contextlib.suppress(Exception):
+                defaults[col_name] = batch.column(col_name)[0].as_py()
+
+    raw = m.arguments_schema
+    if raw is None:
+        schema = None
+    elif isinstance(raw, pa.Schema):
+        # In-process catalog interfaces hand back a live schema; only the
+        # serialized wire form is IPC bytes.
+        schema = raw
+    else:
+        schema = _read_schema(bytes(raw))
+    fields = list(schema) if schema is not None else None
+
+    args: list[dict[str, Any]] = []
+    names = [f.name for f in fields] if fields is not None else list(m.parameters)
+    field_by_name = {f.name: f for f in fields} if fields is not None else {}
+    for name in names:
+        field = field_by_name.get(name)
+        # Macro parameters are untyped unless a typed default pins them; show
+        # ANY rather than the Arrow null placeholder.
+        if field is not None and not pa.types.is_null(field.type):
+            arg: dict[str, Any] = {"name": name, "type": str(field.type)}
+        else:
+            arg = {"name": name, "type": "ANY"}
+        doc = _meta(field, VGI_DOC_KEY) if field is not None else None
+        if doc:
+            arg["desc"] = doc
+        if name in defaults:
+            arg["named"] = True
+            try:
+                arg["default"] = json.dumps(defaults[name])
+            except Exception:  # noqa: BLE001
+                arg["default"] = str(defaults[name])
+        args.append(arg)
+    return args
+
+
+def _macro_to_dict(m: MacroInfo) -> dict[str, Any]:
+    return {
+        "name": m.name,
+        "type": _macro_display_type(m),
+        "doc": m.comment or "",
+        "args": _macro_args(m),
+    }
+
+
 # ---------------------------------------------------------------------------
 # Catalog contents
 # ---------------------------------------------------------------------------
@@ -230,6 +295,9 @@ def _build_schemas(
             SchemaObjectType.AGGREGATE_FUNCTION,
         ):
             funcs_raw.extend(_schema_contents(iface, attach_opaque_data, si.name, kind))
+        macros_raw: list[MacroInfo] = []
+        for kind in (SchemaObjectType.SCALAR_MACRO, SchemaObjectType.TABLE_MACRO):
+            macros_raw.extend(_schema_contents(iface, attach_opaque_data, si.name, kind))
 
         tables = []
         for t in sorted(tables_raw, key=lambda x: x.name):
@@ -257,10 +325,17 @@ def _build_schemas(
                 "args": _function_args(fn),
                 **({"returns": r} if (r := _function_returns(fn)) else {}),
             }
-            for fn in sorted(funcs_raw, key=lambda f: (f.function_type.value, f.name))
+            for fn in funcs_raw
         ]
-
-        schemas.append({"name": si.name, "tables": tables, "views": views, "functions": functions})
+        functions.extend(_macro_to_dict(m) for m in macros_raw)
+        # Deterministic ordering across functions + macros (both fold into the
+        # same scalar/table/aggregate/table_in_out buckets on the landing page).
+        functions.sort(key=lambda d: (d["type"], d["name"]))
+
+        schema_entry: dict[str, Any] = {"name": si.name, "tables": tables, "views": views, "functions": functions}
+        if si.comment:
+            schema_entry["doc"] = si.comment
+        schemas.append(schema_entry)
         totals["schemas"] += 1
         totals["tables"] += len(tables)
         totals["views"] += len(views)