vgi-python 0.24.0__tar.gz → 0.26.0__tar.gz

{vgi_python-0.24.0 → vgi_python-0.26.0}/.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.2.0
+        uses: astral-sh/setup-uv@v9.0.0
 
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
@@ -48,7 +48,7 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.2.0
+        uses: astral-sh/setup-uv@v9.0.0
 
       - name: Install dependencies
         run: uv sync --all-extras
@@ -62,15 +62,18 @@ jobs:
       # Docstring consistency (pydoclint) runs inside the pytest suite via
       # tests/test_docstrings.py, so it's not a separate CI lint step.
 
+      # ty was removed here in 0.25.2. It was already non-blocking, and at
+      # 0.0.66 it stopped terminating on this tree at all -- `ty check vgi/`
+      # ran past ten minutes and had to be killed. A signal nothing gates on,
+      # that also burns a CI job's wall clock, is worse than no signal.
       - name: Type check (mypy)
         run: uv run mypy vgi/
 
-      # ty is pre-1.0 and its inference drifts release-to-release; keep it
-      # visible as a signal but don't gate CI on it (mypy is the blocking
-      # type gate).
-      - name: Type check (ty, non-blocking)
-        run: uv run ty check vgi/
-        continue-on-error: true
+      # tests/ became clean in 0.26.0 and is gated from here on. It was
+      # unchecked for long enough to accumulate 174 errors; the point of the
+      # gate is that it never gets to accumulate a second batch.
+      - name: Type check tests (mypy)
+        run: uv run mypy tests/
 
   docs:
     name: Docs (build + examples + prose)
@@ -81,10 +84,10 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.2.0
+        uses: astral-sh/setup-uv@v9.0.0
 
-      - name: Set up Python 3.13
-        run: uv python install 3.13
+      - name: Set up Python 3.14
+        run: uv python install 3.14
 
       - name: Install dependencies
         run: uv sync --all-extras --group docs
@@ -139,10 +142,10 @@ jobs:
           path: vgi-rpc
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.2.0
+        uses: astral-sh/setup-uv@v9.0.0
 
-      - name: Set up Python 3.13
-        run: uv python install 3.13
+      - name: Set up Python 3.14
+        run: uv python install 3.14
 
       - name: Install test dependencies
         run: |
@@ -150,7 +153,7 @@ jobs:
           # local vgi-rpc checkout with the s3/external extras plus boto3.
           # Subsequent uv run calls must pass --no-sync or uv re-syncs the
           # env to the lockfile and drops the overlay.
-          uv sync --all-extras --python 3.13
+          uv sync --all-extras --python 3.14
           uv pip install './vgi-rpc[http,s3,external]' boto3
 
       - name: Create test bucket in LocalStack

{vgi_python-0.24.0 → vgi_python-0.26.0}/.github/workflows/docs.yml

@@ -18,10 +18,10 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.2.0
+        uses: astral-sh/setup-uv@v9.0.0
 
       - name: Set up Python
-        run: uv python install 3.13
+        run: uv python install 3.14
 
       - name: Install dependencies
         run: uv sync --group docs

{vgi_python-0.24.0 → vgi_python-0.26.0}/.github/workflows/integration.yml

@@ -76,13 +76,13 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.2.0
+        uses: astral-sh/setup-uv@v9.0.0
 
-      - name: Set up Python 3.13
-        run: uv python install 3.13
+      - name: Set up Python 3.14
+        run: uv python install 3.14
 
       - name: Install dependencies (vgi + fixtures + all extras)
-        run: uv sync --all-extras --python 3.13
+        run: uv sync --all-extras --python 3.14
 
       - name: Download haybarn-unittest
         run: |

{vgi_python-0.24.0 → vgi_python-0.26.0}/.github/workflows/release.yml

@@ -33,7 +33,7 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.2.0
+        uses: astral-sh/setup-uv@v9.0.0
 
       - name: Build vgi (sdist + wheel)
         run: uv build --sdist --wheel --out-dir dist-vgi .
@@ -108,17 +108,17 @@ jobs:
           fi
           echo "tags=$tags" >> "$GITHUB_OUTPUT"
 
-      - uses: docker/setup-buildx-action@v3
+      - uses: docker/setup-buildx-action@v4
 
       - name: Log in to GHCR
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build & push
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
         with:
           context: .
           file: packages/vgi-fixtures/docker/Dockerfile

{vgi_python-0.24.0 → vgi_python-0.26.0}/CLAUDE.md

@@ -297,6 +297,11 @@ vgi-client --input data.parquet --function sum_all_columns --worker vgi-fixture-
 | `VGI_OAUTH_DEVICE_CODE_CLIENT_ID` | Client ID for device-code flow (optional, URL-safe chars only) |
 | `VGI_OAUTH_DEVICE_CODE_CLIENT_SECRET` | Client secret for device-code flow (optional, URL-safe chars only) |
 | `VGI_OAUTH_USE_ID_TOKEN` | When `1`/`true`/`yes`, clients use OIDC `id_token` as Bearer instead of `access_token` |
+| `VGI_INTROSPECT_PRINCIPALS` | Comma-separated principals permitted to call `__introspect_token__`. Required — no permissive default — whenever the worker implements `resolve_token()` (see below) |
+| `VGI_INTROSPECT_RATE_LIMIT` | Introspection requests allowed per caller per second (default 20) |
+| `VGI_WORKER_ACCESS_LOG_SAMPLE` | Fraction of *successful* calls to keep in the access log, `0.0`–`1.0`. Errors are always kept; the decision is per call, so every record of one stream shares a fate |
+| `VGI_WORKER_ACCESS_LOG_ASYNC` | When `1`/`true`/`yes`, emit access-log records from a listener thread. Bounded queue; full means drop, and a crash loses whatever is queued |
+| `VGI_WORKER_ACCESS_LOG_QUEUE_SIZE` | Bound on the async access-log queue (default 10000) |
 | `VGI_OTEL_ENABLED` | Enable OpenTelemetry instrumentation (`1`/`true`/`yes`) |
 | `VGI_OTEL_CUSTOM_ATTRIBUTES` | Comma-separated `key=value` pairs for custom span/metric attributes |
 | `VGI_OTEL_CLAIM_ATTRIBUTES` | Comma-separated `claim_key=span_attr_name` pairs for claim extraction |
@@ -392,6 +397,96 @@ Set `SENTRY_DSN` (and install `vgi[sentry]`) to forward unhandled exceptions to
 
 The same enrichment applies to OTel spans when `VGI_OTEL_ENABLED=1` — both backends read from the same `VgiTracer.set_current_span_attributes()` call sites in `vgi/otel.py`. Either, neither, or both can be active in a process.
 
+### Serving Behind a Load Balancer
+
+`--max-externalized-response-bytes` caps a single *externalized* response — the
+payload uploaded to blob storage and replaced on the wire by a pointer. Set it
+to whatever the load balancer, API gateway, or object-store policy in front of
+the worker will actually carry.
+
+```bash
+vgi-serve my.worker:MyWorker --http --max-externalized-response-bytes 67108864
+```
+
+Unlike `--max-stream-response-bytes`, which governs the wire and is *soft* for
+producer streams (a continuation token carries the overshoot to the next turn),
+this cap is **hard on every method type with no continuation escape** — bytes
+already uploaded cannot be un-uploaded. Default is no cap. When set, the value
+is advertised as `VGI-Max-Externalized-Response-Bytes` so clients can size their
+own expectations.
+
+Also available on `Worker.main --http` and the fixture server. Under
+`--server granian` it travels to worker processes through `export_serve_config`.
+
+### Token Introspection (`resolve_token`)
+
+A worker may optionally expose `POST {prefix}/__introspect_token__`, which
+resolves an opaque bearer credential to a principal — for a reverse proxy that
+terminates the only public listener and must know the caller's identity before
+it can authorize anything.
+
+```python
+from vgi.auth import AuthUnavailableError, TokenIdentity
+from vgi.worker import Worker
+
+class MyWorker(Worker):
+    functions = [...]
+
+    @classmethod
+    def resolve_token(cls, token: str) -> TokenIdentity | None:
+        try:
+            row = api_keys.lookup(token)          # your own store
+        except ConnectionError as exc:
+            # "I could not find out" -- 503 + Retry-After, not 401.
+            raise AuthUnavailableError(str(exc)) from exc
+        if row is None:
+            return None                           # "the credential is unknown"
+        return TokenIdentity(principal=row.principal, token_name=row.label)
+```
+
+**The route does not exist until `resolve_token` is overridden** — absent, not
+routed-and-refusing. That is what keeps a dependency upgrade from growing a
+credential-to-identity oracle on every existing worker.
+
+Enabling it also requires an allowlist of principals permitted to ask, via
+`--introspect-principals` or `VGI_INTROSPECT_PRINCIPALS`. There is no permissive
+default and a worker that overrides the hook without one **refuses to start**:
+authenticating and introspecting are different capabilities, and "any
+authenticated caller" lets any user resolve any other user's credential to its
+owner. `--introspect-rate-limit` (default 20/caller/second) bounds, rather than
+closes, the oracle an allowlisted-but-compromised caller still has.
+
+Return `None` for "the store answered and this credential is unknown"; raise
+`AuthUnavailableError` for "the answer is not knowable". A caller that
+negative-caches the first must not cache the second. Never return claims — a
+pass-through claims field would let a worker choose its caller's tenant routing
+and policy branch.
+
+`AuthUnavailableError` is worth reaching for in any custom `authenticate`
+callback too, not just here: it is deliberately **not** a `ValueError`, because
+`chain_authenticate` advances to the next authenticator on `ValueError` — so a
+sidecar outage raised as one is read as "not my credential, try the next" and
+ends up a 401 from the end of the chain, restarting every session in the fleet
+over a thirty-second blip.
+
+### Access Log Sampling and Async Emission
+
+`--access-log-sample 0.05` keeps 5% of *successful* calls. Errors are always
+kept, and the decision is made per call so every record belonging to one stream
+shares a fate. `--access-log-async` moves formatting and writing to a listener
+thread so disk latency stays off the request path; the queue is bounded
+(`--access-log-queue-size`, default 10000), full means drop, and the next record
+through carries `dropped_records` so a gap is never silent. A crash loses
+whatever is still queued — that is the trade.
+
+Both apply only to `vgi_rpc.access`, which gets its own handler for the purpose.
+They are deliberately not applied to the diagnostic loggers: dropping half of a
+traceback is not a saving.
+
+**Trace correlation needs no configuration.** vgi-rpc reads whatever span is
+current when it emits a record, so `trace_id` / `span_id` appear on every access
+record as soon as `VGI_OTEL_ENABLED=1`.
+
 ### Key Constraints for Scalar Functions:
 - **1:1 row mapping**: Output must have exactly the same number of rows as input
 - **Single column output**: Output schema has exactly one column named "result"

{vgi_python-0.24.0 → vgi_python-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.24.0
+Version: 0.26.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
@@ -158,11 +158,11 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
 Requires-Dist: click
-Requires-Dist: httpx>=0.24
+Requires-Dist: httpx2>=2.9.1
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.33.0
+Requires-Dist: vgi-rpc>=0.40.0
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

{vgi_python-0.24.0 → vgi_python-0.26.0}/docs/api/auth.md

@@ -12,6 +12,12 @@ require `pip install vgi-python[http]`; JWT authentication additionally requires
 
 ::: vgi.auth
 
+## Token introspection
+
+`TokenIdentity` is what [`Worker.resolve_token`][vgi.worker.Worker.resolve_token] returns: a
+`principal` plus an optional `token_name`. It lives in a private `vgi-rpc` module, so `vgi.auth`
+re-exports it — a worker that implements `resolve_token` never has to name a private import path.
+
 ## Secret protocol
 
 ::: vgi.secret_protocol

{vgi_python-0.24.0 → vgi_python-0.26.0}/docs/how-to/state-storage.md

@@ -57,7 +57,7 @@ VGI_WORKER_SHARED_STORAGE=cloudflare-do vgi-serve my_worker.py --http
 |---|---|---|---|
 | SQLite | `sqlite` (default) | local / subprocess | none (stdlib) |
 | Azure SQL | `azure-sql` | Azure deployments | `vgi-python[azure]` |
-| Cloudflare DO | `cloudflare-do` | edge / multi-cloud | none extra — uses `httpx`, which ships with `vgi-python`; needs a Worker endpoint + token |
+| Cloudflare DO | `cloudflare-do` | edge / multi-cloud | none extra — uses `httpx2`, which ships with `vgi-python`; needs a Worker endpoint + token |
 
 The per-backend setup (connection strings, credentials, table provisioning) is documented in the
 [Shared Storage reference](../shared-storage.md).

{vgi_python-0.24.0 → vgi_python-0.26.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.24.0"
+version = "0.26.0"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [
@@ -40,8 +40,8 @@ dependencies = [
     "pyarrow",
     "typer>=0.9",
     "platformdirs",
-    "vgi-rpc>=0.33.0",
-    "httpx>=0.24",
+    "vgi-rpc>=0.40.0",
+    "httpx2>=2.9.1",
 ]
 
 [project.optional-dependencies]
@@ -186,6 +186,10 @@ python_version = "3.13"
 strict = true
 warn_return_any = true
 warn_unused_ignores = true
+# tests/test_examples_workers.py puts examples/ on sys.path and imports the
+# doc example workers by bare module name; mirror that for mypy so the imports
+# resolve (and the examples themselves get checked).
+mypy_path = "examples"
 
 [[tool.mypy.overrides]]
 module = "typer.*"
@@ -197,6 +201,13 @@ ignore_missing_imports = true
 module = "granian.*"
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+# jsonschema ships no py.typed marker and its stubs live in the separate
+# types-jsonschema distribution, which we don't depend on. Used only by the
+# landing-page conformance checker in tests/.
+module = "jsonschema.*"
+ignore_missing_imports = true
+
 [[tool.mypy.overrides]]
 # These files have type: ignore comments for ty that mypy doesn't need
 module = ["vgi._test_fixtures.scalar.null_handling", "vgi.table_function"]
@@ -250,7 +261,7 @@ members = ["packages/vgi-fixtures"]
 vgi-fixtures = { workspace = true }
 
 [dependency-groups]
-dev = ["lxml>=6.0.2", "pytest-timeout>=2.4.0", "ty>=0.0.8", "vgi-fixtures"]
+dev = ["lxml>=6.0.2", "pytest-timeout>=2.4.0", "vgi-fixtures"]
 docs = [
     "mkdocs>=1.6",
     "mkdocs-material>=9.5",

{vgi_python-0.24.0 → vgi_python-0.26.0}/tests/catalog/test_declarative.py

@@ -1279,9 +1279,11 @@ class TestSchemaDescriptor:
         """
         schema = Schema(name="main", functions=[UsersFunction])  # only table fn
         info = schema.to_schema_info(AttachOpaqueData(b"x"))
-        assert info.estimated_object_count["scalar_function"] == 0
-        assert info.estimated_object_count["aggregate_function"] == 0
-        assert info.estimated_object_count["table_function"] == 1
+        counts = info.estimated_object_count
+        assert counts is not None
+        assert counts["scalar_function"] == 0
+        assert counts["aggregate_function"] == 0
+        assert counts["table_function"] == 1
 
 
 class TestLegacyFunctionsListSchemaInfo:
@@ -1320,6 +1322,7 @@ class TestLegacyFunctionsListSchemaInfo:
         schemas = ci.schemas(attach_opaque_data=AttachOpaqueData(b"x"), transaction_opaque_data=None)
         assert len(schemas) == 1
         counts = schemas[0].estimated_object_count
+        assert counts is not None
         assert counts["scalar_function"] == 1
         assert counts["table_function"] == 1
 

{vgi_python-0.24.0 → vgi_python-0.26.0}/tests/catalog/test_required_filters.py

@@ -23,23 +23,22 @@ class TestRequiredFiltersField:
 
     def _bbox_columns(self) -> pa.Schema:
         """Return a small schema with a ``bbox`` STRUCT plus flat id/ticker."""
-        return pa.schema(
-            [
-                ("id", pa.int64()),
-                ("ticker", pa.string()),
-                (
-                    "bbox",
-                    pa.struct(
-                        [
-                            ("xmin", pa.float64()),
-                            ("ymin", pa.float64()),
-                            ("xmax", pa.float64()),
-                            ("ymax", pa.float64()),
-                        ]
-                    ),
+        fields: list[tuple[str, pa.DataType]] = [
+            ("id", pa.int64()),
+            ("ticker", pa.string()),
+            (
+                "bbox",
+                pa.struct(
+                    [
+                        ("xmin", pa.float64()),
+                        ("ymin", pa.float64()),
+                        ("xmax", pa.float64()),
+                        ("ymax", pa.float64()),
+                    ]
                 ),
-            ]
-        )
+            ),
+        ]
+        return pa.schema(fields)
 
     def test_default_is_empty_tuple(self) -> None:
         """Default is an empty tuple; TableInfo wire field is an empty list."""

{vgi_python-0.24.0 → vgi_python-0.26.0}/tests/catalog/test_scan_branches.py

@@ -63,7 +63,7 @@ class _LegacyOnlyCatalog(_StubCatalogBase):
 
     # Only the legacy method is overridden; table_scan_branches_get falls back
     # to the CatalogInterface default-impl shim.
-    def table_scan_function_get(  # type: ignore[override]
+    def table_scan_function_get(
         self,
         *,
         attach_opaque_data: AttachOpaqueData,
@@ -89,7 +89,7 @@ class _MultiBranchCatalog(_StubCatalogBase):
     keep them non-overlapping at scan time.
     """
 
-    def table_scan_function_get(  # type: ignore[override]
+    def table_scan_function_get(
         self,
         *,
         attach_opaque_data: AttachOpaqueData,
@@ -108,7 +108,7 @@ class _MultiBranchCatalog(_StubCatalogBase):
             required_extensions=[],
         )
 
-    def table_scan_branches_get(  # type: ignore[override]
+    def table_scan_branches_get(
         self,
         *,
         attach_opaque_data: AttachOpaqueData,
@@ -184,7 +184,7 @@ class TestDefaultImplShim:
                 super().__init__()
                 self.last_at: tuple[str | None, str | None] | None = None
 
-            def table_scan_function_get(  # type: ignore[override]
+            def table_scan_function_get(
                 self,
                 *,
                 attach_opaque_data: AttachOpaqueData,