vgi-python 0.8.6__tar.gz → 0.8.7__tar.gz

{vgi_python-0.8.6 → vgi_python-0.8.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.8.6
+Version: 0.8.7
 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.20.5
+Requires-Dist: vgi-rpc>=0.21.0
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

{vgi_python-0.8.6 → vgi_python-0.8.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.8.6"
+version = "0.8.7"
 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.20.5",
+    "vgi-rpc>=0.21.0",
     "httpx>=0.24",
 ]
 

vgi_python-0.8.7/tests/test_tcp_transport.py

@@ -0,0 +1,122 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Round-trip tests for the TCP transport.
+
+Spawns ``vgi-fixture-worker --tcp 127.0.0.1:0`` (raw Arrow-IPC framing over a
+TCP socket, served by ``vgi_rpc.rpc.run_server``), parses the ``TCP:host:port``
+discovery line it prints on stdout, then drives it through
+``Client.from_tcp(...)`` — the TCP analog of the HTTP round-trip in
+``tests/_http_fixtures.py``.
+"""
+
+from __future__ import annotations
+
+import queue
+import subprocess
+import sys
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import pyarrow as pa
+import pytest
+
+from vgi.arguments import Arguments
+from vgi.client import Client
+
+
+@contextmanager
+def run_tcp_worker(*, bind: str = "127.0.0.1:0") -> Iterator[tuple[str, int]]:
+    """Run ``vgi-fixture-worker --tcp`` and yield the bound ``(host, port)``.
+
+    The worker prints ``TCP:<host>:<port>`` once bound and then must not write
+    further to stdout (the cross-language launcher discovery contract), so we
+    read exactly one line to learn the port. stderr is drained in the
+    background to keep the worker from blocking on a full pipe buffer.
+    """
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "vgi._test_fixtures.worker", "--tcp", bind],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+    )
+
+    def _drain(pipe: object) -> None:
+        for _ in pipe:  # type: ignore[attr-defined]
+            pass
+
+    stderr_thread = threading.Thread(target=_drain, args=(proc.stderr,), daemon=True)
+    stderr_thread.start()
+
+    # Read the discovery line off stdout with a timeout so a worker that never
+    # binds fails the test instead of hanging it.
+    line_q: queue.Queue[str] = queue.Queue(maxsize=1)
+
+    def _read_line() -> None:
+        assert proc.stdout is not None
+        for line in proc.stdout:
+            if line.startswith("TCP:"):
+                line_q.put(line.strip())
+                return
+
+    reader = threading.Thread(target=_read_line, daemon=True)
+    reader.start()
+    try:
+        discovery = line_q.get(timeout=30)
+    except queue.Empty:
+        proc.terminate()
+        raise TimeoutError("worker did not emit a TCP: discovery line within 30s") from None
+
+    _, host, port_str = discovery.split(":", 2)
+    try:
+        yield host, int(port_str)
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait(timeout=5)
+        stderr_thread.join(timeout=5)
+
+
+def test_tcp_round_trip_table_function() -> None:
+    """A table function streams rows correctly over the TCP transport."""
+    with run_tcp_worker() as (host, port), Client.from_tcp(host, port) as client:
+        batches = list(
+            client.table_function(
+                function_name="sequence",
+                arguments=Arguments(positional=(pa.scalar(5),)),
+            )
+        )
+
+    table = pa.Table.from_batches(batches)
+    assert table.column("n").to_pylist() == [0, 1, 2, 3, 4]
+
+
+def test_tcp_round_trip_catalog_listing() -> None:
+    """Catalog discovery works over the TCP transport (catalog_mixin path)."""
+    with run_tcp_worker() as (host, port), Client.from_tcp(host, port) as client:
+        catalogs = client.catalogs()
+
+    assert any(c.name == "example" for c in catalogs)
+
+
+class TestTcpConstructorValidation:
+    """``transport='tcp'`` argument validation."""
+
+    def test_requires_host_and_port(self) -> None:
+        """Tcp transport without host/port is rejected."""
+        with pytest.raises(ValueError, match="requires tcp_host and tcp_port"):
+            Client(transport="tcp", pool=None)
+
+    def test_rejects_server_path(self) -> None:
+        """server_path is subprocess-only."""
+        with pytest.raises(ValueError, match="server_path is only meaningful"):
+            Client("some-worker", transport="tcp", tcp_host="127.0.0.1", tcp_port=1, pool=None)
+
+    def test_rejects_base_url(self) -> None:
+        """base_url is http-only."""
+        with pytest.raises(ValueError, match="base_url is only meaningful"):
+            Client(transport="tcp", tcp_host="127.0.0.1", tcp_port=1, base_url="http://x", pool=None)

{vgi_python-0.8.6 → vgi_python-0.8.7}/uv.lock

@@ -2250,7 +2250,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.8.5"
+version = "0.8.7"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -2360,7 +2360,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.20.5" },
+    { name = "vgi-rpc", specifier = ">=0.21.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'" },
@@ -2389,7 +2389,7 @@ docs = [
 
 [[package]]
 name = "vgi-rpc"
-version = "0.20.6"
+version = "0.21.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "docstring-parser" },
@@ -2397,9 +2397,9 @@ dependencies = [
     { name = "pywin32", marker = "sys_platform == 'win32'" },
     { name = "tzdata", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/40/76/4a2c35af34928c6ab17fcb9b1b50639241bf9d015d45b23ce004d0d70d51/vgi_rpc-0.20.6.tar.gz", hash = "sha256:3172d5041b901b0d1a32c9b45da32363195bbca18adb7e305456f19c241cf8fe", size = 847271, upload-time = "2026-06-22T18:24:18.969Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/3d/7b/0de17f5f638414188829f8bb4952e9a6116145ad402512ead8d0f035b705/vgi_rpc-0.21.0.tar.gz", hash = "sha256:c82c17149c0977080184d4728bdebe38aebcd1374984f6c81a3ce39be0aca367", size = 857916, upload-time = "2026-06-26T00:05:14.045Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d3/3c/9ccc888e725ad9d7091e8ec6fd7504eec15dc2ccfabedabd7d072123b0e8/vgi_rpc-0.20.6-py3-none-any.whl", hash = "sha256:74f8b7c0685f1c28a3ff754d76f8c0179c782e33aa5915ad0343bb9955d7509d", size = 371735, upload-time = "2026-06-22T18:24:17.458Z" },
+    { url = "https://files.pythonhosted.org/packages/40/71/1607a7b093e2477d64a0193d21ec9b9fdfe8bc09f0165ce378fc214ef0a9/vgi_rpc-0.21.0-py3-none-any.whl", hash = "sha256:5e5b1ef8585f459eb0761c9232a6e4eeedef69be7b61ead61e0993f4a15b8698", size = 378442, upload-time = "2026-06-26T00:05:11.821Z" },
 ]
 
 [package.optional-dependencies]

{vgi_python-0.8.6 → vgi_python-0.8.7}/vgi/client/catalog_mixin.py

@@ -90,12 +90,14 @@ class CatalogClientMixin:
     Catalog methods spawn ephemeral connections under the hood — for
     subprocess transport a pooled subprocess worker; for HTTP transport a
     short-lived ``http_connect`` session reusing the ``Client``'s shared
-    ``httpx.Client`` (bearer token, headers). Browsing catalogs over HTTP
-    is the canonical non-DuckDB use case this mixin supports.
+    ``httpx.Client`` (bearer token, headers); for TCP transport a short-lived
+    ``tcp_connect`` session. Browsing catalogs over HTTP is the canonical
+    non-DuckDB use case this mixin supports.
 
-    Other attributes expected from ``Client``: ``_transport`` (subprocess vs
-    http), ``_base_url`` (HTTP base URL), and ``_get_or_create_httpx_client()``
-    (shared HTTP client factory).
+    Other attributes expected from ``Client``: ``_transport`` (subprocess,
+    http, or tcp), ``_base_url`` (HTTP base URL), ``_tcp_host`` / ``_tcp_port``
+    (TCP endpoint), and ``_get_or_create_httpx_client()`` (shared HTTP client
+    factory).
 
     Attributes:
         server_path: Worker shell command used for subprocess transport.
@@ -103,8 +105,10 @@ class CatalogClientMixin:
 
     # Type hints for attributes expected from Client
     server_path: str
-    _transport: Literal["subprocess", "http"]
+    _transport: Literal["subprocess", "http", "tcp"]
     _base_url: str | None
+    _tcp_host: str | None
+    _tcp_port: int | None
     _external_location: Any | None
 
     def _get_or_create_httpx_client(self) -> Any:  # implemented by Client
@@ -128,7 +132,8 @@ class CatalogClientMixin:
             A typed `[`VgiProtocol`][]` proxy bound to the active transport.
         """
         try:
-            if getattr(self, "_transport", "subprocess") == "http":
+            transport = getattr(self, "_transport", "subprocess")
+            if transport == "http":
                 from vgi_rpc.http import http_connect
 
                 httpx_client = self._get_or_create_httpx_client()
@@ -139,6 +144,17 @@ class CatalogClientMixin:
                     external_location=getattr(self, "_external_location", None),
                 ) as proxy:
                     yield proxy
+            elif transport == "tcp":
+                from vgi_rpc.rpc import tcp_connect
+
+                assert self._tcp_host is not None and self._tcp_port is not None
+                with tcp_connect(
+                    VgiProtocol,  # type: ignore[type-abstract]
+                    self._tcp_host,
+                    self._tcp_port,
+                    external_location=getattr(self, "_external_location", None),
+                ) as proxy:
+                    yield proxy
             else:
                 cmd = shlex.split(self.server_path, posix=sys.platform != "win32")
                 with _catalog_pool.connect(VgiProtocol, cmd) as proxy:  # type: ignore[type-abstract]

{vgi_python-0.8.6 → vgi_python-0.8.7}/vgi/client/client.py

@@ -197,10 +197,10 @@ _HTTP_TRANSPORT_READY = True
 
 @dataclass
 class WorkerConnection:
-    """Holds state for a single worker connection (subprocess or HTTP).
+    """Holds state for a single worker connection (subprocess, HTTP, or TCP).
 
-    Exactly one of {proc+connection, _pool_ctx, _http_ctx} is active per
-    connection — transport-specific teardown inspects these fields.
+    Exactly one of {proc+connection, _pool_ctx, _http_ctx, _tcp_ctx} is active
+    per connection — transport-specific teardown inspects these fields.
 
     Attributes:
         proxy: The typed `[`VgiProtocol`][]` proxy used to invoke the worker.
@@ -220,6 +220,8 @@ class WorkerConnection:
     _pool_ctx: AbstractContextManager[Any] | None = field(default=None, repr=False)
     # HTTP transport: context manager from vgi_rpc.http.http_connect.
     _http_ctx: AbstractContextManager[Any] | None = field(default=None, repr=False)
+    # TCP transport: context manager from vgi_rpc.rpc.tcp_connect.
+    _tcp_ctx: AbstractContextManager[Any] | None = field(default=None, repr=False)
 
 
 class Client(CatalogClientMixin):
@@ -381,8 +383,10 @@ class Client(CatalogClientMixin):
         attach_opaque_data: bytes | None = None,
         pool: WorkerPool | None = _default_pool,
         *,
-        transport: Literal["subprocess", "http"] = "subprocess",
+        transport: Literal["subprocess", "http", "tcp"] = "subprocess",
         base_url: str | None = None,
+        tcp_host: str | None = None,
+        tcp_port: int | None = None,
         bearer_token: str | None = None,
         httpx_client: Any | None = None,
         external_location: Any | None = None,
@@ -413,9 +417,14 @@ class Client(CatalogClientMixin):
                 management.
             transport: Which transport to use. ``"subprocess"`` (default)
                 spawns a local subprocess per worker; ``"http"`` connects to
-                a running worker via ``vgi_rpc.http.http_connect``.
+                a running worker via ``vgi_rpc.http.http_connect``; ``"tcp"``
+                connects to a running worker via ``vgi_rpc.rpc.tcp_connect``
+                (raw Arrow-IPC framing, no auth/encryption — loopback /
+                trusted networks only; use ``Client.from_tcp(...)``).
             base_url: HTTP-only. Base URL of the running worker, e.g.
                 ``"http://127.0.0.1:8765"``.
+            tcp_host: TCP-only. Hostname or IP of the running worker.
+            tcp_port: TCP-only. Port of the running worker.
             bearer_token: HTTP-only. When set, every request carries an
                 ``Authorization: Bearer <token>`` header. Static token
                 support only — no JWT / OAuth flows.
@@ -446,12 +455,21 @@ class Client(CatalogClientMixin):
                 raise ValueError("transport='http' requires base_url")
             if server_path is not None:
                 raise ValueError("server_path is only meaningful for transport='subprocess'")
+        elif transport == "tcp":
+            if tcp_host is None or tcp_port is None:
+                raise ValueError("transport='tcp' requires tcp_host and tcp_port")
+            if server_path is not None:
+                raise ValueError("server_path is only meaningful for transport='subprocess'")
+            if base_url is not None:
+                raise ValueError("base_url is only meaningful for transport='http'")
         else:
             raise ValueError(f"unknown transport {transport!r}")
 
         self.server_path = server_path or ""
         self._transport = transport
         self._base_url = base_url
+        self._tcp_host = tcp_host
+        self._tcp_port = tcp_port
         self._bearer_token = bearer_token
         self._httpx_client = httpx_client
         # True when ``_get_or_create_httpx_client`` constructed the client and
@@ -460,7 +478,7 @@ class Client(CatalogClientMixin):
         self._httpx_client_owned = False
         # Auto-enable pointer-batch resolution for HTTP unless the caller
         # asked for something different. See ``external_location`` docs above.
-        if transport == "http" and external_location is None:
+        if transport in ("http", "tcp") and external_location is None:
             from vgi_rpc.external import ExternalLocationConfig
 
             external_location = ExternalLocationConfig()
@@ -509,6 +527,34 @@ class Client(CatalogClientMixin):
             pool=None,
         )
 
+    @classmethod
+    def from_tcp(
+        cls,
+        host: str,
+        port: int,
+        *,
+        external_location: Any | None = None,
+        worker_limit: int | None = None,
+        attach_opaque_data: bytes | None = None,
+    ) -> Client:
+        """Create a `[`Client`][]` bound to a running TCP VGI worker.
+
+        Connects via ``vgi_rpc.rpc.tcp_connect`` (raw Arrow-IPC framing). The
+        framing carries **no authentication or encryption** — only connect to
+        trusted endpoints on loopback or a trusted network; use
+        ``Client.from_http(...)`` for untrusted networks. Spin up a matching
+        worker with ``vgi-fixture-worker --tcp [HOST:]PORT``.
+        """
+        return cls(
+            transport="tcp",
+            tcp_host=host,
+            tcp_port=port,
+            external_location=external_location,
+            worker_limit=worker_limit,
+            attach_opaque_data=attach_opaque_data,
+            pool=None,
+        )
+
     def _drain_stderr(self, stderr: IO[bytes]) -> None:
         """Background thread that continuously reads stderr.
 
@@ -577,8 +623,40 @@ class Client(CatalogClientMixin):
         """
         if self._transport == "http":
             return self._spawn_http_connection(worker_index)
+        if self._transport == "tcp":
+            return self._spawn_tcp_connection(worker_index)
         return self._spawn_subprocess_connection(worker_index)
 
+    def _spawn_tcp_connection(self, worker_index: int) -> WorkerConnection:
+        """Connect to a running TCP worker via ``vgi_rpc.rpc.tcp_connect``.
+
+        Raw Arrow-IPC framing with no auth/encryption — see ``from_tcp``.
+        Multiple ``worker_index`` values open independent TCP connections to
+        the same ``host:port``.
+        """
+        from vgi_rpc.rpc import tcp_connect
+
+        assert self._tcp_host is not None and self._tcp_port is not None  # enforced in __init__
+        ctx: AbstractContextManager[VgiProtocol] = tcp_connect(
+            VgiProtocol,  # type: ignore[type-abstract]
+            self._tcp_host,
+            self._tcp_port,
+            on_log=self._on_worker_log,
+            external_location=self._external_location,
+        )
+        proxy = ctx.__enter__()
+        _logger.debug(
+            "tcp_connection_opened worker_index=%s host=%s port=%s",
+            worker_index,
+            self._tcp_host,
+            self._tcp_port,
+        )
+        return WorkerConnection(
+            proxy=proxy,
+            worker_index=worker_index,
+            _tcp_ctx=ctx,
+        )
+
     def _spawn_http_connection(self, worker_index: int) -> WorkerConnection:
         """Connect to a remote HTTP worker via ``vgi_rpc.http.http_connect``.
 
@@ -724,6 +802,12 @@ class Client(CatalogClientMixin):
             _logger.debug("http_connection_closed worker_index=%s", worker.worker_index)
             return 0
 
+        if worker._tcp_ctx is not None:
+            # TCP transport — close the RPC proxy (and its socket).
+            worker._tcp_ctx.__exit__(None, None, None)
+            _logger.debug("tcp_connection_closed worker_index=%s", worker.worker_index)
+            return 0
+
         if worker._pool_ctx is not None:
             # Return to pool — pool handles subprocess lifecycle
             worker._pool_ctx.__exit__(None, None, None)
@@ -805,6 +889,8 @@ class Client(CatalogClientMixin):
             id_repr: Any = self._primary.proc.pid
         elif self._primary._http_ctx is not None:
             id_repr = f"http({self._base_url})"
+        elif self._primary._tcp_ctx is not None:
+            id_repr = f"tcp({self._tcp_host}:{self._tcp_port})"
         else:
             id_repr = "pooled"
         _logger.debug("server_started id=%s", id_repr)

{vgi_python-0.8.6 → vgi_python-0.8.7}/vgi/worker.py

@@ -1276,10 +1276,25 @@ class Worker:
                 "--unix",
                 help="Bind to this AF_UNIX socket path instead of stdin/stdout (mutex with --http).",
             ),
+            # TCP launcher contract — mutually exclusive with --http/--unix.
+            # Accepts ``[HOST:]PORT``; host defaults to loopback (127.0.0.1)
+            # and ``PORT`` may be 0 to auto-select a free port.  After binding
+            # the worker prints TCP:<host>:<port> to stdout and self-shuts-down
+            # after --idle-timeout seconds with zero connected clients. The raw
+            # framing carries no auth/encryption — bind loopback only; use
+            # --http for untrusted networks.
+            tcp: str | None = typer.Option(
+                None,
+                "--tcp",
+                help=(
+                    "Bind a TCP socket ([HOST:]PORT, host defaults to 127.0.0.1, PORT 0 "
+                    "auto-selects) instead of stdin/stdout (mutex with --http/--unix)."
+                ),
+            ),
             idle_timeout: float = typer.Option(
                 300.0,
                 "--idle-timeout",
-                help="Self-shutdown after N seconds idle when serving --unix.",
+                help="Self-shutdown after N seconds idle when serving --unix/--tcp.",
             ),
             http_threads: int | None = typer.Option(  # noqa: B008
                 None,
@@ -1300,8 +1315,8 @@ class Worker:
                 log_format=log_format,
             )
 
-            if http and unix is not None:
-                raise typer.BadParameter("--http and --unix are mutually exclusive")
+            if sum(x for x in (http, unix is not None, tcp is not None)) > 1:
+                raise typer.BadParameter("--http, --unix, and --tcp are mutually exclusive")
 
             if http:
                 from vgi.serve import (
@@ -1358,6 +1373,47 @@ class Worker:
                     idle_timeout=effective_idle,
                     on_bound=_emit,
                 )
+            elif tcp is not None:
+                # TCP launcher path.  Bind to [HOST:]PORT, print
+                # TCP:<host>:<port> on stdout (mirrors run_server's
+                # cross-language discovery contract), idle-shutdown after
+                # idle_timeout seconds.
+                from vgi_rpc.rpc import serve_tcp
+
+                from vgi.serve import _maybe_init_sentry, _resolve_otel_config
+
+                if ":" in tcp:
+                    host_part, _, port_part = tcp.rpartition(":")
+                    tcp_host = host_part or "127.0.0.1"
+                else:
+                    tcp_host, port_part = "127.0.0.1", tcp
+                try:
+                    tcp_port = int(port_part)
+                except ValueError:
+                    raise typer.BadParameter(f"--tcp expects [HOST:]PORT, got {tcp!r}") from None
+
+                _maybe_init_sentry()
+                otel_config = _resolve_otel_config()
+                worker = cls(quiet=quiet, log_level=effective_level)
+                server = RpcServer(cls.protocol_class, worker, server_version=_get_vgi_version())
+                if otel_config is not None:
+                    from vgi_rpc.otel import instrument_server
+
+                    instrument_server(server, otel_config)
+                    worker._vgi_tracer = VgiTracer.create(otel_config)
+                effective_idle = idle_timeout if idle_timeout > 0 else None
+
+                def _emit_tcp(bound_host: str, bound_port: int) -> None:
+                    print(f"TCP:{bound_host}:{bound_port}", flush=True)
+
+                serve_tcp(
+                    server,
+                    tcp_host,
+                    tcp_port,
+                    threaded=True,
+                    idle_timeout=effective_idle,
+                    on_bound=_emit_tcp,
+                )
             else:
                 from vgi.serve import _maybe_init_sentry, _resolve_otel_config