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

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

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

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

@@ -3,7 +3,7 @@
     {
       "attach_options": [],
       "counts": {
-        "functions": 203,
+        "functions": 207,
         "schemas": 2,
         "tables": 59,
         "views": 3
@@ -699,6 +699,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 +921,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 +1050,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 +1139,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": [
                 {

{vgi_python-0.16.1 → vgi_python-0.17.0}/uv.lock

@@ -2228,7 +2228,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.16.1"
+version = "0.17.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -2338,7 +2338,7 @@ requires-dist = [
     { name = "vgi-python", extras = ["test-fixtures"], marker = "extra == 'test-fixtures-writable'" },
     { name = "vgi-python", extras = ["test-fixtures", "test-fixtures-writable", "http", "oauth", "otel", "sentry", "azure"], marker = "extra == 'dev'" },
     { name = "vgi-python", extras = ["transactor"], marker = "extra == 'test-fixtures-writable'" },
-    { name = "vgi-rpc", specifier = ">=0.24.0" },
+    { name = "vgi-rpc", specifier = ">=0.26.0" },
     { name = "vgi-rpc", extras = ["conformance", "external", "http", "oauth", "otel", "sentry"], marker = "extra == 'dev'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'http'" },
     { name = "vgi-rpc", extras = ["oauth"], marker = "extra == 'oauth'" },
@@ -2367,7 +2367,7 @@ docs = [
 
 [[package]]
 name = "vgi-rpc"
-version = "0.24.0"
+version = "0.26.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "docstring-parser" },
@@ -2375,9 +2375,9 @@ dependencies = [
     { name = "pywin32", marker = "sys_platform == 'win32'" },
     { name = "tzdata", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/63/53/d24648965748f26008dd71495e0330f536ce69f9ddffac431df25bbd3f78/vgi_rpc-0.24.0.tar.gz", hash = "sha256:dac1fd161c04a473f6c4309e94d18f22c8b1476d140be9a789ed710cf6339956", size = 860740, upload-time = "2026-07-09T21:35:44.26Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b5/51/86d4c4466cf5311e80db28f535c02b92961f3d5160a0aae348112a03f7d5/vgi_rpc-0.26.0.tar.gz", hash = "sha256:c0966c99e087f923b228b2211877a8695bf42052d9cde05ce9a4bf077047cb78", size = 869625, upload-time = "2026-07-21T17:39:12.871Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/13/1c/04654c95249e936bd027bb58abd0a36b3989c28b1e7aba891e9651eb0323/vgi_rpc-0.24.0-py3-none-any.whl", hash = "sha256:46caf719bc27b156cd30115c790e00c3ad67f3238ed51a7dc7dbe4dffe794391", size = 380110, upload-time = "2026-07-09T21:35:42.65Z" },
+    { url = "https://files.pythonhosted.org/packages/57/51/d86efc32aef03d69d197916f9d18d0f3719ebd843424cfb9a782ced041c9/vgi_rpc-0.26.0-py3-none-any.whl", hash = "sha256:2c455edb517831867342ce2f105386b73b1fa23137477916c5e5d7a14b66e0fc", size = 386786, upload-time = "2026-07-21T17:39:11.142Z" },
 ]
 
 [package.optional-dependencies]

{vgi_python-0.16.1 → vgi_python-0.17.0}/vgi/_test_fixtures/scalar/__init__.py

@@ -28,6 +28,12 @@ from vgi._test_fixtures.scalar.arithmetic import (
     MultiplyFunction,
     SumValuesFunction,
 )
+from vgi._test_fixtures.scalar.bench_ladder import (
+    CollatzStepsFunction,
+    HashRoundsFunction,
+    PassthruFunction,
+    Sha256HexFunction,
+)
 from vgi._test_fixtures.scalar.binary import (
     BinaryPacketFunction,
     UpperCaseFunction,
@@ -89,10 +95,14 @@ __all__ = [
     "CachedAddConstScalarFunction",
     "CachedDoubleScalarFunction",
     "CachedLabelScalarFunction",
+    "CollatzStepsFunction",
     "ConcatValuesIntFunction",
     "ConcatValuesStrFunction",
     "ConditionalMessageFunction",
     "DoubleFunction",
+    "HashRoundsFunction",
+    "PassthruFunction",
+    "Sha256HexFunction",
     "FormatNumberDefaultFunction",
     "FormatNumberFullFunction",
     "FormatNumberPrecisionFunction",

vgi_python-0.17.0/vgi/_test_fixtures/scalar/bench_ladder.py

@@ -0,0 +1,134 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Compute-ladder scalar fixtures for the boundary-amortization benchmark.
+
+These span the per-row *compute* axis (near-zero for multiply/upper_case up to
+heavy for iterated hashing) at controlled payload sizes, so a benchmark sweep can
+trace framework overhead as a function of (per-row compute, per-row bytes).
+
+- ``collatz_steps``  Int64 -> Int64, data-dependent CPU work (a Python UDF classic).
+- ``sha256_hex``     Utf8  -> Utf8(64), fixed moderate compute per byte.
+- ``hash_rounds``    Utf8  -> Utf8(64), K rounds of SHA-256 (key-stretching): K is a
+                     clean compute *knob* at a fixed payload — sweep it to walk the
+                     compute axis without changing bytes on the wire.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Annotated
+
+import pyarrow as pa
+
+from vgi.arguments import ConstParam, Param, Returns
+from vgi.metadata import FunctionExample
+from vgi.scalar_function import ScalarFunction
+
+
+class PassthruFunction(ScalarFunction):
+    """Identity: returns the input string unchanged.
+
+    Zero compute — its whole cost is the VGI round-trip (convert in/out + wire),
+    so a payload sweep over it measures the *pure wire cost per byte* with no
+    compute contamination (unlike ``upper_case``, whose work grows with length).
+    """
+
+    class Meta:
+        name = "passthru"
+        description = "Returns the input string unchanged (zero-compute wire probe)"
+
+    @classmethod
+    def compute(
+        cls,
+        value: Annotated[pa.StringArray, Param(doc="String value")],
+    ) -> Annotated[pa.StringArray, Returns()]:
+        return value
+
+
+class CollatzStepsFunction(ScalarFunction):
+    """Collatz sequence length for each integer.
+
+    A textbook Python-UDF workload: an unvectorizable per-row loop whose cost is
+    data-dependent (larger / odd-heavy trajectories take more steps).
+    """
+
+    class Meta:
+        name = "collatz_steps"
+        description = "Number of Collatz (3n+1) steps for each integer to reach 1"
+        examples = [
+            FunctionExample(sql="SELECT collatz_steps(n) FROM range(1000) t(n)", description="Step count per integer"),
+        ]
+
+    @classmethod
+    def compute(
+        cls,
+        value: Annotated[pa.Int64Array, Param(doc="Positive integer")],
+    ) -> Annotated[pa.Int64Array, Returns()]:
+        out: list[int | None] = []
+        for n in value.to_pylist():
+            if n is None:
+                out.append(None)
+                continue
+            if n <= 0:
+                out.append(0)
+                continue
+            steps = 0
+            while n != 1:
+                n = n // 2 if (n & 1) == 0 else 3 * n + 1
+                steps += 1
+            out.append(steps)
+        return pa.array(out, type=pa.int64())
+
+
+class Sha256HexFunction(ScalarFunction):
+    """Lowercase hex SHA-256 of each UTF-8 string. Fixed compute per byte."""
+
+    class Meta:
+        name = "sha256_hex"
+        description = "Lowercase hex SHA-256 digest of the UTF-8 string"
+        examples = [
+            FunctionExample(sql="SELECT sha256_hex(s) FROM docs", description="Hash each string"),
+        ]
+
+    @classmethod
+    def compute(
+        cls,
+        value: Annotated[pa.StringArray, Param(doc="String to hash")],
+    ) -> Annotated[pa.StringArray, Returns()]:
+        out: list[str | None] = []
+        for s in value.to_pylist():
+            out.append(None if s is None else hashlib.sha256(s.encode("utf-8")).hexdigest())
+        return pa.array(out, type=pa.string())
+
+
+class HashRoundsFunction(ScalarFunction):
+    """Iterated SHA-256 (key-stretching): apply the digest ``rounds`` times.
+
+    ``rounds`` is a constant, so it is the compute knob: at a fixed input payload,
+    sweeping it scales per-row compute linearly while bytes on the wire stay put.
+    """
+
+    class Meta:
+        name = "hash_rounds"
+        description = "Apply SHA-256 `rounds` times (key-stretching); rounds is a const compute knob"
+        examples = [
+            FunctionExample(sql="SELECT hash_rounds(s, 256) FROM docs", description="256-round key stretch"),
+        ]
+
+    @classmethod
+    def compute(
+        cls,
+        value: Annotated[pa.StringArray, Param(doc="String to stretch")],
+        rounds: Annotated[pa.Int64Scalar, ConstParam("Number of SHA-256 rounds")],
+    ) -> Annotated[pa.StringArray, Returns()]:
+        k = int(rounds.as_py())
+        out: list[str | None] = []
+        for s in value.to_pylist():
+            if s is None:
+                out.append(None)
+                continue
+            b = s.encode("utf-8")
+            for _ in range(k):
+                b = hashlib.sha256(b).digest()
+            out.append(b.hex())
+        return pa.array(out, type=pa.string())

{vgi_python-0.16.1 → vgi_python-0.17.0}/vgi/_test_fixtures/worker.py

@@ -78,6 +78,7 @@ from vgi._test_fixtures.scalar import (
     CachedAddConstScalarFunction,
     CachedDoubleScalarFunction,
     CachedLabelScalarFunction,
+    CollatzStepsFunction,
     ConcatValuesIntFunction,
     ConcatValuesStrFunction,
     ConditionalMessageFunction,
@@ -91,6 +92,7 @@ from vgi._test_fixtures.scalar import (
     GeoDistanceFixedFunction,
     GeoDistanceListFunction,
     GeoDistanceStructFunction,
+    HashRoundsFunction,
     HashSeedFunction,
     MultiplyBySettingFunction,
     MultiplyFunction,
@@ -98,12 +100,14 @@ from vgi._test_fixtures.scalar import (
     PairTypeIntIntFunction,
     PairTypeIntStrFunction,
     PairTypeStrStrFunction,
+    PassthruFunction,
     QuerySeedFunction,
     RandomBytesFunction,
     RandomIntFunction,
     ReturnSecretValueFunction,
     ScaleBySettingFunction,
     SecretFieldFunction,
+    Sha256HexFunction,
     SmartFormatPrefixFunction,
     SmartFormatWidthFunction,
     SumValuesFunction,
@@ -548,6 +552,10 @@ _EXAMPLE_CATALOG = Catalog(
                 HashSeedFunction,
                 MultiplyBySettingFunction,
                 MultiplyFunction,
+                CollatzStepsFunction,
+                HashRoundsFunction,
+                Sha256HexFunction,
+                PassthruFunction,
                 NullHandlingFunction,
                 PairTypeIntIntFunction,
                 PairTypeIntStrFunction,