vgi-python 0.8.6__py3-none-any.whl → 0.8.7__py3-none-any.whl

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/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/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
 

{vgi_python-0.8.6.dist-info → vgi_python-0.8.7.dist-info}/METADATA

@@ -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.dist-info → vgi_python-0.8.7.dist-info}/RECORD

@@ -27,7 +27,7 @@ vgi/table_buffering_function.py,sha256=O5TcIdqk8-YViCQCkb8bOevO-zhe3IoyzLgwXDO3C
 vgi/table_filter_pushdown.py,sha256=zak3AuXLVw51vXew93i81fRReG1H8yr4XxCfRnnISj4,63961
 vgi/table_function.py,sha256=_Ni1deyPaabnQJDQz9CUL4fXy79r_OVyN6ZuWTZ1lMQ,52215
 vgi/table_in_out_function.py,sha256=Ouv02ubP-XsRdByIR0ZSagi6VbZfQ8G1e5QWpqlLqvY,15508
-vgi/worker.py,sha256=zrAk_ac_SFMLO0pTZajOrYevAYTGr5opkAV_BtF9CT0,195873
+vgi/worker.py,sha256=t5OKx5mGU91zeV6ErOifeTQmOw16fTOc18jOSDbTDaA,198588
 vgi/_test_fixtures/__init__.py,sha256=xQq-QQLk8USQ6TZHsPiPcZldNNUdcJ2gToXMPGzScLI,444
 vgi/_test_fixtures/attach_options.py,sha256=YtNk1krDdKLnNVtX9yGkgS8XyzdOI0oXtNDbAV73Phg,11091
 vgi/_test_fixtures/bad_enum.py,sha256=lIVemVWTM1JVOHut47Q71Czw-sEiMjfFiyZ15NDaWAk,2910
@@ -105,7 +105,7 @@ vgi/catalog/secret_type.py,sha256=MKtAypBa3xXyr-NC5CHjdX1R00JEnuMtvgboFWC2T9o,33
 vgi/catalog/setting.py,sha256=06QfgaAR-0BKflIJ0du6PGqA5BPMdrkwr6u7f4nddII,1846
 vgi/catalog/storage.py,sha256=DhngzywbhQUfLF7NjFyiPp4Sw2ovOhcUXAuW3rkBQD8,11935
 vgi/client/__init__.py,sha256=6LPHqlcNFy77apDNXUntgOVLhuXfpJyZd6TI7R7QfbY,2122
-vgi/client/catalog_mixin.py,sha256=0EL7eY6DYkqIq_zWWjcEH7xCyNkEyxaoygMW0ehsvEY,45908
+vgi/client/catalog_mixin.py,sha256=fH_D756rzQZHi6UKbeVbWCIScVUqcGw8Dfp8nD36dao,46600
 vgi/client/cli.py,sha256=KfoqIiMXiUNAdYxRp-O6BOi3FA1IsesSBb_XeZGWFSo,22287
 vgi/client/cli_catalog.py,sha256=twjlhHGl7n2mNN4jc7DnDRQr-Zj9KLAF2eATIQnITHQ,5577
 vgi/client/cli_schema.py,sha256=FTkf1moDn_dWFMPDxJqaNFhc2oyrLEutP8xC60EbPIk,7556
@@ -113,7 +113,7 @@ vgi/client/cli_table.py,sha256=hxASTkLZy69z4qoYhpIqrV9ZmZdPLKIzhmHy-hB9qqE,26145
 vgi/client/cli_transaction.py,sha256=TDW0ZrBy8XM_eYSkYk5ewEsnozfzDJOlopd66Fm7OOE,3142
 vgi/client/cli_utils.py,sha256=kilyfxRgFdW63IYQU6xsVls1wIcRjR-ZP63qu0FdXLI,16223
 vgi/client/cli_view.py,sha256=p2wiJAuaEv-8qEgWxiNKgzA9qLdYZ87XCJwkxx5c-YU,8353
-vgi/client/client.py,sha256=M-P3v1Xi5aroTl7Zdtx_tdMT4VjWhTZKiqAog9BDsb4,93582
+vgi/client/client.py,sha256=Pb5qLfydDEnrTW-yCUDSGkerGJesCeHQQbFNTZpxN24,97270
 vgi/http/__init__.py,sha256=hlOwOVcoZqmEKVGk7ganOdr5ryRSpEhLBF9sRD7BkYc,608
 vgi/http/demo_storage.py,sha256=830s-H61thozC3eEuqdnwCpYFfvoJRq9vjyuXa5OURo,8769
 vgi/http/worker_page.py,sha256=Eq70-hPfG2PIuhFjEDMf-BxF7Fdjcb4dN2SploH2jWE,54577
@@ -122,8 +122,8 @@ vgi/transactor/_duckdb_compat.py,sha256=sXVZ9JLKAQyGR1BjWczSwdQEavtr-TcZPoVZZnTr
 vgi/transactor/client.py,sha256=7DTeMksogsw6ANjQjGOPpKYrV76rg4_kGjktMJf54jg,4486
 vgi/transactor/protocol.py,sha256=Mtmll3CdrLFL1B4NY4NZUTO_yi3PT0qhvMQnzapuBWU,4780
 vgi/transactor/server.py,sha256=WpIqjzy2Mebw17Jui4-w7vyGEo9pD-pEZJG-3Ob1Sk8,29705
-vgi_python-0.8.6.dist-info/METADATA,sha256=b59V9U4mHNCh4vgMDP_4iOEGPAa6eCisvaxwNhrtC4s,24725
-vgi_python-0.8.6.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-vgi_python-0.8.6.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
-vgi_python-0.8.6.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
-vgi_python-0.8.6.dist-info/RECORD,,
+vgi_python-0.8.7.dist-info/METADATA,sha256=tNHKhPZbF3jkRYNokolq5dGV1pj1iLcqN2AedbfdK2I,24725
+vgi_python-0.8.7.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+vgi_python-0.8.7.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
+vgi_python-0.8.7.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
+vgi_python-0.8.7.dist-info/RECORD,,