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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.11.1"
+version = "0.12.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.12.0}/tests/landing/describe.expected.json

@@ -3,7 +3,7 @@
     {
       "attach_options": [],
       "counts": {
-        "functions": 162,
+        "functions": 165,
         "schemas": 2,
         "tables": 44,
         "views": 3
@@ -1114,6 +1114,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 +2249,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 +2398,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 +2659,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.11.1 → vgi_python-0.12.0}/uv.lock

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

{vgi_python-0.11.1 → vgi_python-0.12.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,8 +325,12 @@ 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
         ]
+        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"]))
 
         schemas.append({"name": si.name, "tables": tables, "views": views, "functions": functions})
         totals["schemas"] += 1

{vgi_python-0.11.1 → vgi_python-0.12.0}/vgi/http/landing.html

@@ -73,6 +73,12 @@
   .cat-card .cc-title { display: flex; align-items: center; gap: 9px; font-size: 18px; font-weight: 650; letter-spacing: -0.01em; }
   .cat-card .cc-title .ic { width: 19px; height: 19px; color: var(--accent); }
   .cat-card .cc-doc { color: var(--muted); font-size: 13.5px; margin-top: 5px; }
+  .cat-card .cc-doc .md-h { font-size: 14px; font-weight: 650; color: var(--ink); margin: 8px 0 4px; }
+  .cat-card .cc-doc .md-p { margin: 4px 0; }
+  .cat-card .cc-doc .md-p:first-child { margin-top: 0; }
+  .cat-card .cc-doc .md-ul { margin: 4px 0; padding-left: 18px; }
+  .cat-card .cc-doc code { font-family: var(--mono); background: var(--chip); padding: 1px 5px; border-radius: 4px; font-size: .92em; }
+  .cat-card .cc-doc a { color: var(--accent); }
   .badges { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 13px; }
   .badge { display: inline-flex; align-items: center; gap: 6px; font-size: 12.5px; padding: 5px 11px; border: 1px solid var(--line-strong); border-radius: 8px; text-decoration: none; color: var(--ink); background: var(--panel); }
   .badge:hover { border-color: var(--accent); color: var(--accent); }
@@ -190,10 +196,17 @@
   .t-name, .fn-name { font-family: var(--mono); font-size: 12.5px; font-weight: 550; }
   .t-meta { color: var(--muted); font-size: 11.5px; font-family: var(--mono); font-variant-numeric: tabular-nums; flex: none; }
   .fn-sig { color: var(--muted); font-size: 12px; font-family: var(--mono); flex: none; }
-  .t-comment, .fn-doc { color: var(--muted); font-size: 12.5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; margin-left: auto; text-align: right; }
+  .fn-doc { color: var(--muted); font-size: 12.5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; margin-left: auto; text-align: right; }
 
   /* level 4: body inset */
   .t-body, .fn-body { padding: 9px 13px 12px; background: color-mix(in srgb, var(--kc) 4%, var(--bg)); border-radius: 0 0 var(--row-radius) var(--row-radius); }
+  .t-desc { color: var(--ink); font-size: 12.5px; line-height: 1.5; margin: 0 0 11px; }
+  .t-desc .md-h { font-size: 13px; font-weight: 650; margin: 8px 0 4px; }
+  .t-desc .md-p { margin: 4px 0; }
+  .t-desc .md-p:first-child { margin-top: 0; }
+  .t-desc .md-ul { margin: 4px 0; padding-left: 18px; }
+  .t-desc code { font-family: var(--mono); background: var(--chip); padding: 1px 5px; border-radius: 4px; font-size: .92em; }
+  .t-desc a { color: var(--accent); }
   .args-label { font-size: 10.5px; letter-spacing: .06em; text-transform: uppercase; color: var(--muted); font-weight: 700; margin: 0 0 6px; }
   .cols { display: flex; flex-direction: column; gap: 6px; }
   .col-item { border: 1px solid color-mix(in srgb, var(--kc) 22%, var(--line)); border-radius: 7px; padding: 7px 10px; background: color-mix(in srgb, var(--kc) 4%, var(--panel)); }
@@ -225,7 +238,7 @@
 </style>
 </head>
 <body>
-<!-- vgi-landing-asset v1 -->
+<!-- vgi-landing-asset v2 -->
 
 <a class="skip" href="#contents">Skip to contents</a>
 
@@ -312,6 +325,55 @@ const serviceUrl = origin + basePath;
 const esc = s => String(s).replace(/[&<>"]/g, c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));
 const sqlHi = s => esc(s).replace(/\b(SELECT|FROM|WHERE|GROUP BY|ORDER BY|INTERVAL|AND|OR|AS|JOIN|ON|YEAR)\b/g, m=>'<span class="kw">'+m+'</span>');
 
+function mdToHtml(src){
+  if(!src) return '';
+  var lines = String(src).replace(/\r\n?/g,'\n').split('\n'), out=[], i=0;
+  function inl(t){
+    t = esc(t);
+    t = t.replace(/`([^`]+)`/g,'<code>$1</code>');
+    t = t.replace(/\*\*([^*]+)\*\*/g,'<strong>$1</strong>');
+    t = t.replace(/(^|[^*])\*([^*]+)\*/g,'$1<em>$2</em>');
+    t = t.replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g,'<a href="$2" target="_blank" rel="noopener">$1</a>');
+    return t;
+  }
+  while(i<lines.length){
+    var ln=lines[i];
+    if(/^\s*$/.test(ln)){ i++; continue; }
+    var h=ln.match(/^(#{1,6})\s+(.*)$/);
+    if(h){ var lv=Math.min(h[1].length,6); out.push('<h'+lv+' class="md-h">'+inl(h[2])+'</h'+lv+'>'); i++; continue; }
+    if(/^\s*[-*+]\s+/.test(ln)){
+      var items=[];
+      while(i<lines.length && /^\s*[-*+]\s+/.test(lines[i])){ items.push('<li>'+inl(lines[i].replace(/^\s*[-*+]\s+/,''))+'</li>'); i++; }
+      out.push('<ul class="md-ul">'+items.join('')+'</ul>'); continue;
+    }
+    var para=[ln]; i++;
+    while(i<lines.length && !/^\s*$/.test(lines[i]) && !/^(#{1,6}\s|\s*[-*+]\s)/.test(lines[i])){ para.push(lines[i]); i++; }
+    out.push('<p class="md-p">'+inl(para.join(' '))+'</p>');
+  }
+  return out.join('');
+}
+var _DDB_TYPES = {int8:'TINYINT',int16:'SMALLINT',int32:'INTEGER',int64:'BIGINT',
+  uint8:'UTINYINT',uint16:'USMALLINT',uint32:'UINTEGER',uint64:'UBIGINT',
+  halffloat:'FLOAT',float:'FLOAT',float32:'FLOAT',double:'DOUBLE',float64:'DOUBLE',
+  bool:'BOOLEAN',boolean:'BOOLEAN',string:'VARCHAR',large_string:'VARCHAR',utf8:'VARCHAR',large_utf8:'VARCHAR',
+  binary:'BLOB',large_binary:'BLOB',date32:'DATE','date32[day]':'DATE',date64:'DATE',null:'NULL',
+  month_day_nano_interval:'INTERVAL'};
+function duckdbType(t){
+  if(!t) return t; t=String(t); var lt=t.toLowerCase();
+  if(_DDB_TYPES[lt]) return _DDB_TYPES[lt];
+  var d=t.match(/^dictionary<values=([^,>]+)/i); if(d) return duckdbType(d[1].trim());
+  var l=t.match(/^(?:large_)?list<(?:item:\s*)?(.+)>$/i); if(l) return duckdbType(l[1].trim())+'[]';
+  if(/^fixed_size_binary/i.test(t)) return 'BLOB';
+  var ts=t.match(/^timestamp\[([^,\]]+)(?:,\s*tz=([^\]]+))?\]$/i); if(ts) return ts[2]?'TIMESTAMPTZ':'TIMESTAMP';
+  if(/^time(32|64)\[/i.test(t)) return 'TIME';
+  if(/^duration\[/i.test(t)) return 'INTERVAL';
+  var dec=t.match(/^decimal(?:128|256)\((\d+),\s*(\d+)\)$/i); if(dec) return 'DECIMAL('+dec[1]+','+dec[2]+')';
+  if(/^struct</i.test(t)) return 'STRUCT';
+  if(/^map</i.test(t)) return 'MAP';
+  return t;
+}
+
+
 // ── identity pill ────────────────────────────────────────────────────────────────
 function renderIdentity(){
   if (!describe.oauth) return;
@@ -377,7 +439,7 @@ function renderCatCard(){
     ? '<div class="cc-by">'+[t.author?'by '+esc(t.author):'', t.copyright?esc(t.copyright):''].filter(Boolean).join(' · ')+'</div>' : '';
   document.getElementById('cat-card').innerHTML =
     '<div class="cc-title">'+icon('catalog')+esc(t.title || c.name)+'</div>' +
-    (t.doc_md ? '<div class="cc-doc">'+esc(t.doc_md)+'</div>' : '') +
+    (t.doc_md ? '<div class="cc-doc">'+mdToHtml(t.doc_md)+'</div>' : '') +
     (badges ? '<div class="badges">'+badges+'</div>' : '') + kw + by;
 }
 
@@ -482,9 +544,9 @@ function tableRow(catName, s, t, kind){       // kind: 'table' | 'view'
   const kcls = kind==='view' ? ' view k-view' : '';
   return '<details class="tbl'+kcls+'" data-name="'+esc(t.name.toLowerCase())+'" data-kind="'+kind+'" data-catalog="'+esc(catName)+'" data-schema="'+esc(s.name)+'" data-table="'+esc(t.name)+'">'+
     '<summary>'+icon('caret','tri')+icon(iconName,'row-icon')+
-      '<span class="t-name">'+esc(t.name)+'</span><span class="t-meta">'+t.cols+' cols</span>'+
-      (t.comment? '<span class="t-comment">'+esc(t.comment)+'</span>':'')+'</summary>'+
+      '<span class="t-name">'+esc(t.name)+'</span><span class="t-meta">'+t.cols+' cols</span></summary>'+
     '<div class="t-body">'+
+      (t.comment ? '<div class="t-desc">'+mdToHtml(t.comment)+'</div>' : '')+
       (kind==='view' && t.def ? '<div class="args-label">Definition</div><pre class="view-sql">'+sqlHi(t.def)+'</pre>' : '')+
       '<div class="args-label">Columns</div><div class="cols"><div class="skeleton">Loading columns…</div></div></div></details>';
 }
@@ -497,7 +559,7 @@ function argCard(a){
   const def = (a.default!==undefined && a.default!==null) ? '<span class="arg-def">default '+esc(a.default)+'</span>' : '';
   const desc = a.desc ? esc(a.desc) : '';
   const meta = (desc||def) ? '<div class="col-comment">'+desc+(desc&&def?' · ':'')+def+'</div>' : '';
-  return '<div class="col-item"><div class="col"><span class="col-name">'+esc(a.name)+(a.named?'<span class="arg-kind"> :=</span>':'')+'</span><span class="col-type">'+esc(a.type)+'</span></div>'+meta+'</div>';
+  return '<div class="col-item"><div class="col"><span class="col-name">'+esc(a.name)+(a.named?'<span class="arg-kind"> :=</span>':'')+'</span><span class="col-type">'+esc(duckdbType(a.type))+'</span></div>'+meta+'</div>';
 }
 function fnRow(f, iconName){
   const pos = f.args.filter(a=>!a.named), named = f.args.filter(a=>a.named);
@@ -563,7 +625,7 @@ document.getElementById('catalogs').addEventListener('toggle', e=>{
   const body = d.querySelector('.cols');
   fetchColumns(d.dataset.catalog, d.dataset.schema, d.dataset.table).then(info=>{
     body.innerHTML = info.columns.map(col=>
-      '<div class="col-item"><div class="col"><span class="col-name">'+esc(col.name)+'</span><span class="col-type">'+esc(col.type)+'</span></div>'+
+      '<div class="col-item"><div class="col"><span class="col-name">'+esc(col.name)+'</span><span class="col-type">'+esc(duckdbType(col.type))+'</span></div>'+
       (col.comment? '<div class="col-comment">'+esc(col.comment)+'</div>':'')+'</div>').join('');
   });
 }, true);
@@ -604,9 +666,7 @@ document.getElementById('footer').innerHTML =
   '<a href="'+prefix+'/describe">RPC API</a><span class="dot">·</span>'+
   '<a href="https://github.com/query-farm">Source</a><span class="dot">·</span>'+
   '<a href="https://query.farm">Query.Farm</a>'+
-  '<div class="foot-meta">vgi-rpc (<code>'+esc(describe.worker.lang)+'</code>) · v'+esc(describe.worker.version)+' · <code>'+esc(describe.server_id)+'</code></div>'+
-  '<div class="foot-meta">landing_schema_version '+describe.landing_schema_version+
-  ' · shared page, identical across Python / Go / Rust / TypeScript / Java</div>';
+  '<div class="foot-meta">vgi-rpc (<code>'+esc(describe.worker.lang)+'</code>) · v'+esc(describe.worker.version)+' · <code>'+esc(describe.server_id)+'</code></div>';
 }
 
 function renderAll(){ renderCatBar(); renderCatCard(); renderConnect(); updateCupola(); renderContents(); }