vgi-python 0.9.0__tar.gz → 0.11.0__tar.gz

{vgi_python-0.9.0 → vgi_python-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.9.0
+Version: 0.11.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
@@ -162,13 +162,14 @@ Requires-Dist: httpx>=0.24
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.21.0
+Requires-Dist: vgi-rpc>=0.23.0
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'
 Provides-Extra: dev
 Requires-Dist: azure-identity>=1.16.0; extra == 'dev'
 Requires-Dist: duckdb>=1.5.3; extra == 'dev'
+Requires-Dist: jsonschema; extra == 'dev'
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: numpy>=2.4.1; extra == 'dev'
 Requires-Dist: pyarrow-stubs; extra == 'dev'

{vgi_python-0.9.0 → vgi_python-0.11.0}/packages/vgi-fixtures/pyproject.toml

@@ -38,6 +38,7 @@ dependencies = ["vgi-python[test-fixtures-writable]", "vgi-python[duckdb]"]
 
 [project.scripts]
 vgi-fixture-worker = "vgi._test_fixtures.worker:main"
+vgi-fixture-companion-worker = "vgi._test_fixtures.companion:main"
 vgi-fixture-http = "vgi._test_fixtures.http_server:main"
 vgi-fixture-versioned-worker = "vgi._test_fixtures.versioned:main"
 vgi-fixture-versioned-tables-worker = "vgi._test_fixtures.versioned_tables:main"

{vgi_python-0.9.0 → vgi_python-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.9.0"
+version = "0.11.0"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [
@@ -40,7 +40,7 @@ dependencies = [
     "pyarrow",
     "typer>=0.9",
     "platformdirs",
-    "vgi-rpc>=0.21.0",
+    "vgi-rpc>=0.23.0",
     "httpx>=0.24",
 ]
 
@@ -82,6 +82,7 @@ dev = [
     # (a vgi-rpc dependency) in the shared `docstring_parser` namespace,
     # non-deterministically breaking imports. tests/test_docstrings.py runs it
     # in an isolated env via `uvx pydoclint` instead.
+    "jsonschema",
     "pytest",
     "pytest-cov",
     "pytest-examples",

{vgi_python-0.9.0 → vgi_python-0.11.0}/tests/catalog/test_declarative.py

@@ -41,8 +41,10 @@ from vgi.catalog import (
     View,
     ViewInfo,
 )
+from vgi.invocation import BindResponse
 from vgi.schema_utils import schema
 from vgi.table_function import (
+    BindParams,
     ProcessParams,
     TableFunctionGenerator,
     bind_fixed_schema,
@@ -81,6 +83,31 @@ class UsersFunction(TableFunctionGenerator[EmptyArgs]):
         out.finish()
 
 
+@init_single_worker
+class SecretLookupFunction(TableFunctionGenerator[EmptyArgs]):
+    """Backing function whose ``on_bind`` performs a two-phase secret lookup.
+
+    This exercises the bug where ``Table(function=...)`` schema derivation took
+    the empty secret-scope-request schema instead of retrying the bind.
+    """
+
+    class Meta:  # noqa: D106
+        name = "secret_scan"
+        description = "Backing function that looks up a secret at bind time"
+
+    FIXED_SCHEMA: ClassVar[pa.Schema] = schema({"id": pa.int64(), "name": pa.string()})
+
+    @classmethod
+    def on_bind(cls, params: BindParams[EmptyArgs]) -> BindResponse:  # noqa: D102
+        params.secrets.get("some_secret")  # unresolved -> registers a two-phase lookup
+        return BindResponse(output_schema=cls.FIXED_SCHEMA)
+
+    @classmethod
+    def process(cls, params: ProcessParams[EmptyArgs], state: None, out: OutputCollector) -> None:  # noqa: D102
+        out.emit(pa.RecordBatch.from_pydict({"id": [1], "name": ["x"]}, schema=params.output_schema))
+        out.finish()
+
+
 @init_single_worker
 @bind_fixed_schema
 class EventsFunction(TableFunctionGenerator[EmptyArgs]):
@@ -186,6 +213,18 @@ class TestTableWithFunction:
         assert resolved.field(0).name == "id"
         assert resolved.field(1).name == "name"
 
+    def test_function_backed_table_derives_schema_despite_secret_lookup(self) -> None:
+        """A backing function that calls secrets.get() in on_bind still yields its schema.
+
+        Regression: on_bind's two-phase secret lookup makes the first bind return an
+        empty secret-scope-request schema; schema derivation must retry with resolved
+        secrets rather than adopt the empty schema (which produced 0-column tables).
+        """
+        table = Table(name="things", function=SecretLookupFunction)
+        resolved = table.resolved_columns
+        assert [f.name for f in resolved] == ["id", "name"]
+        assert len(resolved) == 2
+
     def test_table_function_backed_with_constraints(self) -> None:
         """Function-backed table can have constraints validated."""
         table = Table(
@@ -336,7 +375,6 @@ class TestTableWithFunction:
         from typing import Any as _Any
 
         from vgi.invocation import BindResponse
-        from vgi.table_function import BindParams
 
         @init_single_worker
         class _ManualBindFn(TableFunctionGenerator[EmptyArgs]):

{vgi_python-0.9.0 → vgi_python-0.11.0}/tests/catalog/test_serialization.py

@@ -1110,7 +1110,7 @@ class TestArrowSchemaCorrectness:
     def test_catalog_attach_result_schema(self) -> None:
         """Verify CatalogAttachResult Arrow schema."""
         schema = CatalogAttachResult.ARROW_SCHEMA
-        assert len(schema) == 14
+        assert len(schema) == 15
         assert schema.field("attach_opaque_data").type == pa.binary()
         assert schema.field("supports_transactions").type == pa.bool_()
         assert schema.field("supports_time_travel").type == pa.bool_()
@@ -1120,6 +1120,7 @@ class TestArrowSchemaCorrectness:
         assert schema.field("default_schema").type == pa.string()
         assert schema.field("settings").type == pa.list_(pa.binary())
         assert schema.field("secret_types").type == pa.list_(pa.binary())
+        assert schema.field("attach_catalogs").type == pa.list_(pa.binary())
         assert schema.field("resolved_data_version").type == pa.string()
         assert schema.field("resolved_implementation_version").type == pa.string()
 

vgi_python-0.11.0/tests/conformance/test_const_param_enforcement.py

@@ -0,0 +1,69 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Conformance test: ConstParam value constraints are enforced at bind.
+
+A ``ConstParam`` may declare ``choices``/``ge``/``le``/``gt``/``lt``/``pattern``.
+Those are surfaced for agent discovery (via ``vgi_function_arguments()``) AND
+must be enforced: a const value that violates a declared constraint fails at
+bind with ``ArgumentValidationError``, rather than silently reaching
+``compute()``. This mirrors the legacy ``Arg`` descriptor path.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import pyarrow as pa
+import pytest
+
+from vgi.arguments import Arguments, ArgumentValidationError, ConstParam, Param, Returns
+from vgi.protocol import BindRequest, FunctionType
+from vgi.scalar_function import BindResult, ScalarFunction
+
+
+class _Measure(ScalarFunction):
+    class Meta:
+        name = "measure"
+
+    @classmethod
+    def on_bind(cls, params: object) -> BindResult:
+        return BindResult(pa.string())
+
+    @classmethod
+    def compute(
+        cls,
+        unit: Annotated[str, ConstParam("Output unit", choices=["mm", "cm", "m"])],
+        precision: Annotated[int, ConstParam("Decimals", ge=0, le=10)],
+        value: Annotated[pa.DoubleArray, Param(doc="Value")],
+    ) -> Annotated[pa.StringArray, Returns()]:
+        return pa.array([str(value)], type=pa.string())
+
+
+def _bind(unit: str, precision: int) -> None:
+    _Measure.bind(
+        BindRequest(
+            function_name="measure",
+            arguments=Arguments(positional=(pa.scalar(unit), pa.scalar(precision))),
+            function_type=FunctionType.SCALAR,
+            input_schema=pa.schema([("value", pa.float64())]),
+        )
+    )
+
+
+def test_valid_const_values_bind() -> None:
+    """A const value inside every declared constraint binds cleanly."""
+    _bind("cm", 2)
+
+
+def test_choice_violation_raises_at_bind() -> None:
+    """A const value outside the choice set fails at bind."""
+    with pytest.raises(ArgumentValidationError) as exc:
+        _bind("xx", 2)
+    assert "unit" in str(exc.value)
+
+
+def test_range_violation_raises_at_bind() -> None:
+    """A const value outside the numeric range fails at bind."""
+    with pytest.raises(ArgumentValidationError) as exc:
+        _bind("cm", 99)
+    assert "precision" in str(exc.value)

vgi_python-0.11.0/tests/conformance/test_container.py

@@ -0,0 +1,17 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Conformance stub for ``vgi/test/sql/integration/container/``."""
+
+from __future__ import annotations
+
+from tests.conformance._stub import skip_area
+
+skip_area(
+    "container",
+    [
+        "errors.test",
+        "shared_http.test",
+        "shared_tcp.test",
+        "sklearn_smoke.test",
+    ],
+)

vgi_python-0.11.0/tests/conformance/test_copy_from.py

@@ -0,0 +1,16 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Conformance stub for ``vgi/test/sql/integration/copy_from/``."""
+
+from __future__ import annotations
+
+from tests.conformance._stub import skip_area
+
+skip_area(
+    "copy_from",
+    [
+        "basic.test",
+        "options.test",
+        "secrets.test",
+    ],
+)

vgi_python-0.11.0/tests/conformance/test_copy_to.py

@@ -0,0 +1,21 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Conformance stub for ``vgi/test/sql/integration/copy_to/``."""
+
+from __future__ import annotations
+
+from tests.conformance._stub import skip_area
+
+skip_area(
+    "copy_to",
+    [
+        "basic.test",
+        "failure.test",
+        "options.test",
+        "ordered.test",
+        "parallel.test",
+        "secrets.test",
+        "tmp_file.test",
+        "types.test",
+    ],
+)

vgi_python-0.11.0/tests/conformance/test_github.py

@@ -0,0 +1,15 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Conformance stub for ``vgi/test/sql/integration/github/``."""
+
+from __future__ import annotations
+
+from tests.conformance._stub import skip_area
+
+skip_area(
+    "github",
+    [
+        "download.test",
+        "errors.test",
+    ],
+)

{vgi_python-0.9.0 → vgi_python-0.11.0}/tests/conformance/test_secret.py

@@ -9,10 +9,13 @@ from tests.conformance._stub import skip_area
 skip_area(
     "secret",
     [
+        "secret_aggregate.test",
+        "secret_function_backed_table.test",
         "secret_no_secret.test",
         "secret_registration.test",
         "secret_scalar.test",
         "secret_scoped.test",
         "secret_table_function.test",
+        "secret_table_in_out.test",
     ],
 )

vgi_python-0.11.0/tests/landing/_checker.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Landing-page conformance checker for VGI workers (all languages).
+
+Drives a running worker's HTTP landing surface and asserts it conforms to the
+contract in ``docs/http-landing-contract.md``:
+
+* ``GET {prefix}/describe.json`` validates against ``describe.schema.json`` and
+  (optionally) equals a **normalized golden** — the cross-language equality guard.
+* ``GET {prefix}/`` serves the pinned shared ``landing.html`` (asset marker), and
+  ``?format=json`` returns a JSON status.
+* ``GET {prefix}/describe/{catalog}/{schema}/{table}.json`` returns valid columns.
+
+Usage:
+    run_landing_conformance.py --url http://localhost:8790 [--golden fixtures/describe.expected.json]
+    run_landing_conformance.py --url http://localhost:8790 --golden fixtures/describe.expected.json --update
+
+Exit code is non-zero on any failure. ``--update`` (re)writes the golden from the
+live worker (reviewers inspect the diff).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+import urllib.request
+
+import jsonschema
+
+_HERE = pathlib.Path(__file__).resolve().parent
+DEFAULT_SCHEMA = _HERE / "describe.schema.json"
+ASSET_MARKER = "vgi-landing-asset v"
+
+# Fields dropped before comparing to a golden (volatile or language-specific).
+_VOLATILE_TOP = ("server_id", "worker", "oauth")
+
+
+def _get(url: str, accept: str = "application/json") -> tuple[int, bytes, str]:
+    req = urllib.request.Request(url, headers={"Accept": accept})
+    try:
+        with urllib.request.urlopen(req) as resp:  # noqa: S310 — trusted local URL
+            return resp.status, resp.read(), resp.headers.get("Content-Type", "")
+    except urllib.error.HTTPError as exc:  # type: ignore[attr-defined]
+        return exc.code, exc.read(), exc.headers.get("Content-Type", "")
+
+
+def normalize(doc: dict) -> dict:
+    """Strip volatile/language-specific fields so goldens compare across languages."""
+    return {k: v for k, v in doc.items() if k not in _VOLATILE_TOP}
+
+
+def _canonical(doc: dict) -> str:
+    return json.dumps(doc, indent=2, sort_keys=True, ensure_ascii=False)
+
+
+def check(
+    base_url: str,
+    *,
+    schema_path: pathlib.Path = DEFAULT_SCHEMA,
+    golden_path: pathlib.Path | None = None,
+) -> list[str]:
+    """Return a list of failure strings (empty == conformant)."""
+    base = base_url.rstrip("/")
+    fails: list[str] = []
+    schema = json.loads(schema_path.read_text())
+    columns_schema = {**schema, **schema["$defs"]["columns"]}
+
+    # 1) describe.json — schema-valid.
+    status, body, _ = _get(f"{base}/describe.json")
+    if status != 200:
+        return [f"GET /describe.json returned HTTP {status}"]
+    doc = json.loads(body)
+    try:
+        jsonschema.validate(doc, schema)
+    except jsonschema.ValidationError as exc:
+        fails.append(f"describe.json schema violation: {exc.message} at {list(exc.absolute_path)}")
+
+    # 2) GET / serves the pinned shared page; ?format=json is a JSON status.
+    status, html, ctype = _get(f"{base}/", accept="text/html")
+    if status != 200 or "text/html" not in ctype:
+        fails.append(f"GET / (Accept: text/html) returned HTTP {status} {ctype!r}")
+    elif ASSET_MARKER not in html.decode("utf-8", "replace"):
+        fails.append(f"GET / did not serve the pinned landing.html (missing {ASSET_MARKER!r} marker)")
+    status, jbody, _ = _get(f"{base}/?format=json")
+    try:
+        assert json.loads(jbody).get("status") == "ok"
+    except Exception:  # noqa: BLE001
+        fails.append("GET /?format=json did not return a JSON status object")
+
+    # 3) Lazy column endpoints — validate one table + one view per schema.
+    for cat in doc.get("catalogs", []):
+        for sch in cat.get("schemas", []):
+            samples = (sch.get("tables") or [])[:1] + (sch.get("views") or [])[:1]
+            for obj in samples:
+                cstatus, cbody, _ = _get(f"{base}/describe/{cat['name']}/{sch['name']}/{obj['name']}.json")
+                if cstatus != 200:
+                    fails.append(f"columns {cat['name']}/{sch['name']}/{obj['name']} -> HTTP {cstatus}")
+                    continue
+                try:
+                    jsonschema.validate(json.loads(cbody), columns_schema)
+                except jsonschema.ValidationError as exc:
+                    fails.append(f"columns {sch['name']}.{obj['name']} schema violation: {exc.message}")
+
+    # 4) Golden diff (cross-language equality).
+    if golden_path is not None:
+        got = _canonical(normalize(doc))
+        want = golden_path.read_text() if golden_path.exists() else None
+        if want is None:
+            fails.append(f"golden {golden_path} does not exist (run with --update)")
+        elif got.strip() != want.strip():
+            fails.append(f"describe.json does not match golden {golden_path.name} (normalized diff)")
+
+    return fails
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--url", required=True, help="Worker base URL, e.g. http://localhost:8790")
+    ap.add_argument("--schema", type=pathlib.Path, default=DEFAULT_SCHEMA)
+    ap.add_argument("--golden", type=pathlib.Path, default=None)
+    ap.add_argument("--update", action="store_true", help="Write the normalized golden from the live worker")
+    args = ap.parse_args()
+
+    if args.update:
+        if args.golden is None:
+            ap.error("--update requires --golden")
+        _, body, _ = _get(f"{args.url.rstrip('/')}/describe.json")
+        args.golden.parent.mkdir(parents=True, exist_ok=True)
+        args.golden.write_text(_canonical(normalize(json.loads(body))) + "\n")
+        print(f"wrote golden {args.golden}")
+        return 0
+
+    fails = check(args.url, schema_path=args.schema, golden_path=args.golden)
+    if fails:
+        print(f"FAIL ({len(fails)}):")
+        for f in fails:
+            print(f"  - {f}")
+        return 1
+    print("PASS: landing conformance OK")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())