vgi-python 0.16.1__tar.gz → 0.18.0__tar.gz

{vgi_python-0.16.1 → vgi_python-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.16.1
+Version: 0.18.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,7 +162,7 @@ Requires-Dist: httpx>=0.24
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.24.0
+Requires-Dist: vgi-rpc>=0.26.0
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

{vgi_python-0.16.1 → vgi_python-0.18.0}/docs/catalog-interface.md

@@ -307,6 +307,52 @@ class MyReadOnlyCatalog(ReadOnlyCatalogInterface):
 
 ---
 
+## Function Name Scoping
+
+A function name is **not** a global key. The worker resolves a call by the pair
+`(schema, function name)`, so the same name may be declared in more than one
+schema of a catalog, and a schema-qualified call reaches the implementation in
+that schema:
+
+```python test="lint"
+Catalog(
+    name="example",
+    default_schema="main",
+    schemas=[
+        Schema(name="main", functions=[ProdLookup]),   # Meta.name = "lookup"
+        Schema(name="staging", functions=[StagingLookup]),  # Meta.name = "lookup"
+    ],
+)
+```
+
+```sql
+SELECT example.main.lookup(1);     -- ProdLookup
+SELECT example.staging.lookup(1);  -- StagingLookup
+```
+
+The DuckDB extension carries the owning schema on every bind request
+(`BindRequest.schema_name`), taken from the schema entry the function was
+registered into. Two consequences worth knowing:
+
+- **Overloads still work.** Several classes sharing a name *within one schema*
+  are overloads, disambiguated by argument signature as before. Only the
+  cross-schema case is resolved by schema.
+- **Callers without a schema must be unambiguous.** The pure-Python `Client`
+  and the CLI send no schema. If the name is unique across the worker they
+  resolve normally; if two schemas declare it, the worker raises an ambiguity
+  error naming the schemas involved.
+
+Functions declared via the legacy `Worker.functions` list have no schema of
+their own, so they are registered into the catalog's `default_schema` — the
+same schema DuckDB registers them into.
+
+Across **catalogs**, the key is the attachment rather than the name: two
+catalogs served by one worker process (see `vgi.meta_worker.MetaWorker`) may
+each declare `main.lookup`, and each attachment's `attach_opaque_data` routes
+its calls to the right catalog.
+
+---
+
 ## Declarative Catalogs
 
 For most use cases, the declarative catalog API provides a simpler way to define catalogs using Python dataclasses instead of implementing `CatalogInterface` directly.
@@ -483,13 +529,19 @@ class MyWorker(Worker):
 
 To disable the catalog interface entirely:
 
-```python
+```python test="lint"
 class MyWorker(Worker):
     catalog_interface = None
     catalog_name = None  # Required to fully disable
     functions = [...]
 ```
 
+A catalog-less worker is reachable only from the pure-Python [`Client`][], which
+binds by `(schema, function name)` and needs no attachment — its functions
+register into the default `main` schema. It is **not** reachable from DuckDB:
+`ATTACH ... (TYPE vgi)` requires a catalog, and there is no standalone
+call form. If the worker should be usable from SQL, give it a catalog.
+
 ---
 
 ## Client Usage

{vgi_python-0.16.1 → vgi_python-0.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.16.1"
+version = "0.18.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.24.0",
+    "vgi-rpc>=0.26.0",
     "httpx>=0.24",
 ]
 

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/client/test_broken_pipe.py

@@ -40,6 +40,7 @@ class TestClientWorkerExitHandling:
             list(
                 client.table_in_out_function(
                     function_name="test",
+                    schema_name="main",
                     arguments=Arguments(),
                     input=iter([_make_test_batch()]),
                 )
@@ -56,6 +57,7 @@ class TestClientWorkerExitHandling:
             list(
                 client.table_in_out_function(
                     function_name="test",
+                    schema_name="main",
                     arguments=Arguments(),
                     input=iter([_make_test_batch()]),
                 )

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/client/test_worker_debug.py

@@ -68,6 +68,7 @@ class TestStderrInErrorMessages:
             list(
                 client.table_function(
                     function_name="nonexistent",
+                    schema_name="main",
                     arguments=Arguments(),
                 )
             )
@@ -87,6 +88,7 @@ class TestStderrInErrorMessages:
             list(
                 client.table_function(
                     function_name="nonexistent",
+                    schema_name="main",
                     arguments=Arguments(),
                 )
             )
@@ -108,6 +110,7 @@ class TestStderrInErrorMessages:
             list(
                 client.table_in_out_function(
                     function_name="nonexistent",
+                    schema_name="main",
                     input=iter([batch]),
                 )
             )
@@ -126,6 +129,7 @@ class TestStderrInErrorMessages:
             list(
                 client.scalar_function(
                     function_name="nonexistent",
+                    schema_name="main",
                     input=iter([batch]),
                 )
             )

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/conformance/test_function_inventory.py

@@ -178,6 +178,7 @@ def test_scalar_function_end_to_end(attached_example: tuple[str, bytes]) -> None
         out_batches = list(
             client.scalar_function(
                 function_name="double",
+                schema_name="main",
                 arguments=Arguments(positional=(pa.scalar("x"),)),
                 input=iter([input_batch]),
             )
@@ -199,6 +200,7 @@ def test_table_function_end_to_end(attached_example: tuple[str, bytes]) -> None:
         out_batches = list(
             client.table_function(
                 function_name="sequence",
+                schema_name="main",
                 arguments=Arguments(positional=(pa.scalar(5),)),
             )
         )

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/conformance/test_http_client.py

@@ -102,6 +102,7 @@ def test_scalar_function_over_http(http_example_base_url: str) -> None:
         out = list(
             client.scalar_function(
                 function_name="double",
+                schema_name="main",
                 arguments=Arguments(positional=(pa.scalar("x"),)),
                 input=iter([batch]),
             )
@@ -119,6 +120,7 @@ def test_table_function_over_http(http_example_base_url: str) -> None:
         out = list(
             client.table_function(
                 function_name="sequence",
+                schema_name="main",
                 arguments=Arguments(positional=(pa.scalar(5),)),
             )
         )

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/conformance/test_http_external_location.py

@@ -83,6 +83,7 @@ def test_pointer_batch_auto_resolved(demo_storage_base_url: str) -> None:
         out = list(
             client.scalar_function(
                 function_name="random_bytes",
+                schema_name="main",
                 arguments=Arguments(positional=(pa.scalar(seed), pa.scalar(payload_bytes))),
                 input=iter([input_batch]),
             )
@@ -116,6 +117,7 @@ def test_http_client_uses_default_external_config(demo_storage_base_url: str) ->
         list(
             client.scalar_function(
                 function_name="random_bytes",
+                schema_name="main",
                 arguments=Arguments(positional=(pa.scalar(0), pa.scalar(payload_bytes))),
                 input=iter([input_batch]),
             )

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/conformance/test_http_upload_url.py

@@ -85,6 +85,7 @@ def test_oversize_input_auto_externalized(small_request_limit_base_url: str) ->
         out = list(
             client.scalar_function(
                 function_name="double",
+                schema_name="main",
                 arguments=Arguments(positional=(pa.scalar("x"),)),
                 input=iter([input_batch]),
             )
@@ -115,6 +116,7 @@ def test_small_input_not_externalized(small_request_limit_base_url: str) -> None
         out = list(
             client.scalar_function(
                 function_name="double",
+                schema_name="main",
                 arguments=Arguments(positional=(pa.scalar("x"),)),
                 input=iter([input_batch]),
             )

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/conformance/test_protocol_version.py

@@ -32,18 +32,19 @@ CLIENT_PROTOCOL_VERSION = VgiProtocol.protocol_version
 
 def test_client_protocol_version_is_canonical() -> None:
     """Sanity-check the constants this test reasons about haven't drifted apart."""
-    assert CLIENT_PROTOCOL_VERSION == "1.0.0"
+    assert CLIENT_PROTOCOL_VERSION == "1.1.0"
     # The fixture must be a genuine mismatch in the major/minor that the
     # framework compares; a patch-only difference would (correctly) pass.
     assert BAD_PROTOCOL_VERSION.split(".")[:2] != CLIENT_PROTOCOL_VERSION.split(".")[:2]
 
 
 def test_mismatched_worker_protocol_version_raises() -> None:
-    """A worker enforcing 99.0.0 must reject the 1.0.0 client at dispatch."""
+    """A worker enforcing 99.0.0 must reject the 1.1.0 client at dispatch."""
     with Client("vgi-fixture-bad-protocol-worker") as client, pytest.raises(ClientError) as exc_info:
         list(
             client.table_function(
                 function_name="sequence",
+                schema_name="main",
                 arguments=Arguments(positional=(pa.scalar(5),)),
             )
         )
@@ -53,5 +54,5 @@ def test_mismatched_worker_protocol_version_raises() -> None:
     assert "protocol_version mismatch" in message
     assert CLIENT_PROTOCOL_VERSION in message
     assert BAD_PROTOCOL_VERSION in message
-    # Directional hint: the client (1.0.0) is older than the worker (99.0.0).
+    # Directional hint: the client (1.1.0) is older than the worker (99.0.0).
     assert "upgrade the VGI extension/client" in message

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/conformance/test_resumable_scan.py

@@ -50,7 +50,7 @@ def _reference_rows(base_url: str) -> list[int]:
     with Client.from_http(base_url) as client:
         return [
             v
-            for b in client.table_function(function_name="sequence", arguments=_ARGS)
+            for b in client.table_function(function_name="sequence", schema_name="main", arguments=_ARGS)
             for v in b.column("n").to_pylist()
         ]
 
@@ -62,7 +62,7 @@ def test_resumable_scan_matches_table_function(http_base_url: str) -> None:
 
     rows: list[int] = []
     with Client.from_http(http_base_url) as client:
-        cur = client.table_scan_resumable(function_name="sequence", arguments=_ARGS)
+        cur = client.table_scan_resumable(function_name="sequence", schema_name="main", arguments=_ARGS)
         while True:
             batch, _token = cur.next()
             if batch is None:
@@ -81,7 +81,7 @@ def test_resume_on_fresh_client_after_node_hop(http_base_url: str) -> None:
     token: bytes | None = None
     # Read the first few batches, then abandon the connection (as if the LB node died).
     with Client.from_http(http_base_url) as client:
-        cur = client.table_scan_resumable(function_name="sequence", arguments=_ARGS)
+        cur = client.table_scan_resumable(function_name="sequence", schema_name="main", arguments=_ARGS)
         for _ in range(3):
             batch, token = cur.next()
             assert batch is not None
@@ -91,7 +91,9 @@ def test_resume_on_fresh_client_after_node_hop(http_base_url: str) -> None:
 
     # A brand-new client resumes from the serialized token alone.
     with Client.from_http(http_base_url) as client2:
-        cur2 = client2.table_scan_resumable(function_name="sequence", arguments=_ARGS, resume_token=token)
+        cur2 = client2.table_scan_resumable(
+            function_name="sequence", schema_name="main", arguments=_ARGS, resume_token=token
+        )
         while True:
             batch, token = cur2.next()
             if batch is None:
@@ -116,7 +118,7 @@ def test_continue_on_fresh_client_skips_rebind(http_base_url: str) -> None:
     rows: list[int] = []
     token: bytes | None = None
     with Client.from_http(http_base_url) as client:
-        cur = client.table_scan_resumable(function_name="sequence", arguments=_ARGS)
+        cur = client.table_scan_resumable(function_name="sequence", schema_name="main", arguments=_ARGS)
         for _ in range(3):
             batch, token = cur.next()
             assert batch is not None
@@ -153,4 +155,4 @@ def test_resumable_scan_rejected_on_subprocess() -> None:
     client = Client("/nonexistent/worker")  # subprocess transport, never started
     assert client.supports_resumable_scan is False
     with pytest.raises(ResumeUnsupported):
-        client.table_scan_resumable(function_name="sequence", arguments=_ARGS)
+        client.table_scan_resumable(function_name="sequence", schema_name="main", arguments=_ARGS)

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/conformance/test_scalar.py

@@ -23,6 +23,9 @@ skip_area(
         "hash_seed.test",
         "null_handling.test",
         "random_int.test",
+        # Covered on the Python side by tests/test_schema_scoped_functions.py.
+        "same_name_catalogs.test",
+        "same_name_schemas.test",
         "sum_values.test",
         "unnest_tensor.test",
         "upper_case.test",

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/landing/describe.expected.json

@@ -3,7 +3,7 @@
     {
       "attach_options": [],
       "counts": {
-        "functions": 203,
+        "functions": 209,
         "schemas": 2,
         "tables": 59,
         "views": 3
@@ -15,7 +15,21 @@
       "schemas": [
         {
           "doc": "Example tables backed by functions",
-          "functions": [],
+          "functions": [
+            {
+              "args": [
+                {
+                  "desc": "Integer value to tag",
+                  "name": "value",
+                  "type": "int64"
+                }
+              ],
+              "doc": "Schema-disambiguation probe; the data-schema implementation",
+              "name": "test_same_name_bind",
+              "returns": "string",
+              "type": "scalar"
+            }
+          ],
           "name": "data",
           "tables": [
             {
@@ -699,6 +713,19 @@
               "returns": "string",
               "type": "scalar"
             },
+            {
+              "args": [
+                {
+                  "desc": "Positive integer",
+                  "name": "value",
+                  "type": "int64"
+                }
+              ],
+              "doc": "Number of Collatz (3n+1) steps for each integer to reach 1",
+              "name": "collatz_steps",
+              "returns": "int64",
+              "type": "scalar"
+            },
             {
               "args": [
                 {
@@ -908,6 +935,24 @@
               "returns": "double",
               "type": "scalar"
             },
+            {
+              "args": [
+                {
+                  "desc": "String to stretch",
+                  "name": "value",
+                  "type": "string"
+                },
+                {
+                  "desc": "Number of SHA-256 rounds",
+                  "name": "rounds",
+                  "type": "int64"
+                }
+              ],
+              "doc": "Apply SHA-256 `rounds` times (key-stretching); rounds is a const compute knob",
+              "name": "hash_rounds",
+              "returns": "string",
+              "type": "scalar"
+            },
             {
               "args": [
                 {
@@ -1019,6 +1064,19 @@
               "returns": "string",
               "type": "scalar"
             },
+            {
+              "args": [
+                {
+                  "desc": "String value",
+                  "name": "value",
+                  "type": "string"
+                }
+              ],
+              "doc": "Returns the input string unchanged (zero-compute wire probe)",
+              "name": "passthru",
+              "returns": "string",
+              "type": "scalar"
+            },
             {
               "args": [
                 {
@@ -1095,6 +1153,19 @@
               "returns": "string",
               "type": "scalar"
             },
+            {
+              "args": [
+                {
+                  "desc": "String to hash",
+                  "name": "value",
+                  "type": "string"
+                }
+              ],
+              "doc": "Lowercase hex SHA-256 digest of the UTF-8 string",
+              "name": "sha256_hex",
+              "returns": "string",
+              "type": "scalar"
+            },
             {
               "args": [
                 {
@@ -1144,6 +1215,19 @@
               "returns": "null",
               "type": "scalar"
             },
+            {
+              "args": [
+                {
+                  "desc": "Integer value to tag",
+                  "name": "value",
+                  "type": "int64"
+                }
+              ],
+              "doc": "Schema-disambiguation probe; the main-schema implementation",
+              "name": "test_same_name_bind",
+              "returns": "string",
+              "type": "scalar"
+            },
             {
               "args": [
                 {
@@ -1445,25 +1529,6 @@
               "name": "cache_filtered",
               "type": "table"
             },
-            {
-              "args": [
-                {
-                  "desc": "Total number of rows to generate",
-                  "name": "rows",
-                  "type": "int64"
-                },
-                {
-                  "default": "20000",
-                  "desc": "Rows per partition",
-                  "name": "chunk_size",
-                  "named": true,
-                  "type": "int64"
-                }
-              ],
-              "doc": "Parallel batch_index-tagged cacheable sequence; cache serve reassembles order",
-              "name": "cache_interleaved",
-              "type": "table"
-            },
             {
               "args": [
                 {
@@ -1675,7 +1740,7 @@
                   "type": "int64"
                 }
               ],
-              "doc": "Cacheable blended map x -> x*2 (advertises vgi.cache.ttl)",
+              "doc": "Cacheable blended map x -> x*2 (advertises vgi.cache.ttl + per_value)",
               "name": "cached_double",
               "type": "table"
             },
@@ -1685,6 +1750,18 @@
               "name": "cached_echo",
               "type": "table"
             },
+            {
+              "args": [
+                {
+                  "desc": "Fan-out count: emit rows 0..n-1 for this input row",
+                  "name": "n",
+                  "type": "int64"
+                }
+              ],
+              "doc": "Cacheable blended 1->N fan-out (per_value) — 1:0 / 1:1 / 1:N by input",
+              "name": "cached_explode",
+              "type": "table"
+            },
             {
               "args": [
                 {

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/scalar/test_bernoulli_function.py

@@ -22,6 +22,7 @@ class TestBernoulliFunction:
             outputs = list(
                 client.scalar_function(
                     function_name="bernoulli",
+                    schema_name="main",
                     input=iter([batch]),
                 )
             )
@@ -38,6 +39,7 @@ class TestBernoulliFunction:
             outputs = list(
                 client.scalar_function(
                     function_name="bernoulli",
+                    schema_name="main",
                     input=iter([batch]),
                 )
             )

{vgi_python-0.16.1 → vgi_python-0.18.0}/tests/scalar/test_binary_packet_function.py

@@ -30,6 +30,7 @@ class TestBinaryPacketFunction:
             outputs = list(
                 client.scalar_function(
                     function_name="binary_packet",
+                    schema_name="main",
                     input=iter([batch]),
                     arguments=Arguments(positional=(header, config)),
                 )
@@ -56,6 +57,7 @@ class TestBinaryPacketFunction:
             outputs = list(
                 client.scalar_function(
                     function_name="binary_packet",
+                    schema_name="main",
                     input=iter([batch]),
                     arguments=Arguments(positional=(header, config)),
                 )