vgi-python 0.29.3__tar.gz → 0.29.4__tar.gz

{vgi_python-0.29.3 → vgi_python-0.29.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.29.3
+Version: 0.29.4
 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: httpx2>=2.9.1
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.43.0
+Requires-Dist: vgi-rpc>=0.43.2
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'
@@ -181,7 +181,8 @@ Requires-Dist: pytest-ruff; extra == 'dev'
 Requires-Dist: pytest-xdist; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: sqlglot; extra == 'dev'
-Requires-Dist: vgi-rpc[conformance,external,http,oauth,otel,sentry]; extra == 'dev'
+Requires-Dist: vgi-rpc[cli,conformance,external,http,oauth,otel,sentry]; extra == 'dev'
+Requires-Dist: vgi-rpc[cli]; extra == 'dev'
 Requires-Dist: vgi-rpc[http]; extra == 'dev'
 Requires-Dist: vgi-rpc[oauth]; extra == 'dev'
 Requires-Dist: vgi-rpc[otel]; extra == 'dev'
@@ -197,6 +198,8 @@ Provides-Extra: haybarn
 Requires-Dist: haybarn>=1.5.5rc1; extra == 'haybarn'
 Provides-Extra: http
 Requires-Dist: vgi-rpc[http]; extra == 'http'
+Provides-Extra: launch
+Requires-Dist: vgi-rpc[cli]; extra == 'launch'
 Provides-Extra: oauth
 Requires-Dist: vgi-rpc[oauth]; extra == 'oauth'
 Provides-Extra: otel

{vgi_python-0.29.3 → vgi_python-0.29.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.29.3"
+version = "0.29.4"
 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.43.0",
+    "vgi-rpc>=0.43.2",
     "httpx2>=2.9.1",
 ]
 
@@ -52,6 +52,11 @@ dependencies = [
 haybarn = ["haybarn>=1.5.5rc1"]
 duckdb = ["duckdb>=1.5.3"]
 http = ["vgi-rpc[http]"]
+# transport="launch": vgi_rpc.launcher imports filelock unconditionally at
+# module level, which lives behind vgi-rpc's own `cli` extra (alongside
+# typer, already a core dependency here, and httpx2, ditto) rather than in
+# vgi-rpc's core dependency set.
+launch = ["vgi-rpc[cli]"]
 # Alternative HTTP server: granian moves socket I/O and HTTP parsing into Rust,
 # off the GIL. Optional because it is a compiled extension where waitress is
 # pure Python; select it with `vgi-serve --http --server granian`.
@@ -93,8 +98,8 @@ dev = [
     "pytest-ruff",
     "pytest-xdist",
     "ruff",
-    "vgi-python[test-fixtures,test-fixtures-writable,http,oauth,otel,sentry,azure]",
-    "vgi-rpc[conformance,external,http,oauth,otel,sentry]",
+    "vgi-python[test-fixtures,test-fixtures-writable,http,launch,oauth,otel,sentry,azure]",
+    "vgi-rpc[cli,conformance,external,http,oauth,otel,sentry]",
 ]
 [project.scripts]
 vgi-serve = "vgi.serve:main"

vgi_python-0.29.4/tests/test_launch_transport.py

@@ -0,0 +1,114 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Round-trip tests for the launcher-managed (``transport="launch"``) transport.
+
+Drives ``vgi._test_fixtures.worker`` (the same fixture module ``test_tcp_transport.py``
+uses) through ``Client.from_launch(...)`` — no separate fixture worker needed, since
+``MetaWorker.serve`` already passes argv through to ``vgi_rpc.rpc.run_server()``, which
+participates in the AF_UNIX launcher path (``--unix PATH --idle-timeout SEC``) the same
+way it participates in the TCP path (``--tcp HOST:PORT``).
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+import tempfile
+import uuid
+from collections.abc import Iterator
+from pathlib import Path
+
+import pyarrow as pa
+import pytest
+from vgi_rpc.launcher import status_rows
+
+from vgi.arguments import Arguments
+from vgi.client import Client
+
+_WORKER_ARGV = (sys.executable, "-m", "vgi._test_fixtures.worker")
+
+
+@pytest.fixture
+def state_dir() -> Iterator[str]:
+    """Per-test state dir under ``/tmp`` to stay under macOS's 104-byte AF_UNIX limit.
+
+    Mirrors ``vgi-rpc``'s own ``test_launcher.py`` fixture — ``tmp_path`` resolves to a
+    deeply nested path that, concatenated with ``<hash>.sock``, blows past the cap.
+    """
+    d = Path(tempfile.gettempdir()) / f"vgi-launch-test-{uuid.uuid4().hex[:8]}"
+    d.mkdir(mode=0o700)
+    try:
+        yield str(d)
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def test_launch_round_trip_table_function(state_dir: str) -> None:
+    """A table function streams rows correctly over the launch transport."""
+    with Client.from_launch(_WORKER_ARGV, idle_timeout=10.0, state_dir=state_dir) as client:
+        batches = list(
+            client.table_function(
+                function_name="sequence",
+                schema_name="main",
+                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_launch_round_trip_catalog_listing(state_dir: str) -> None:
+    """Catalog discovery works over the launch transport (catalog_mixin path)."""
+    with Client.from_launch(_WORKER_ARGV, idle_timeout=10.0, state_dir=state_dir) as client:
+        catalogs = client.catalogs()
+
+    assert any(c.name == "example" for c in catalogs)
+
+
+def test_launch_shares_one_worker_across_clients(state_dir: str) -> None:
+    """Two `Client`s with the same worker_argv + state_dir share one warm worker.
+
+    The whole point of the launcher over plain subprocess/TCP: a second client
+    pointing at the same command must reuse the first client's worker rather than
+    spawning its own. Proven by checking exactly one tracked worker exists in the
+    shared state dir after both clients have connected, not by any client-visible
+    process identity (the client has no API for that, by design — it shouldn't need
+    to know or care).
+    """
+    with Client.from_launch(_WORKER_ARGV, idle_timeout=10.0, state_dir=state_dir) as client_a:
+        assert client_a.catalogs()
+        with Client.from_launch(_WORKER_ARGV, idle_timeout=10.0, state_dir=state_dir) as client_b:
+            assert client_b.catalogs()
+            rows = status_rows(Path(state_dir))
+            assert len(rows) == 1, f"expected exactly one shared worker, found {len(rows)}: {rows}"
+            assert rows[0].alive
+
+
+class TestLaunchConstructorValidation:
+    """``transport='launch'`` argument validation."""
+
+    def test_requires_launch_argv(self) -> None:
+        """Launch transport without launch_argv is rejected."""
+        with pytest.raises(ValueError, match="requires a non-empty launch_argv"):
+            Client(transport="launch", pool=None)
+
+    def test_rejects_empty_launch_argv(self) -> None:
+        """An explicitly empty launch_argv is rejected the same as omitting it."""
+        with pytest.raises(ValueError, match="requires a non-empty launch_argv"):
+            Client(transport="launch", launch_argv=(), 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="launch", launch_argv=("x",), 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="launch", launch_argv=("x",), base_url="http://x", pool=None)
+
+    def test_rejects_tcp_host_and_port(self) -> None:
+        """tcp_host/tcp_port are tcp-only."""
+        with pytest.raises(ValueError, match="tcp_host/tcp_port are only meaningful"):
+            Client(transport="launch", launch_argv=("x",), tcp_host="127.0.0.1", tcp_port=1, pool=None)

{vgi_python-0.29.3 → vgi_python-0.29.4}/uv.lock

@@ -714,6 +714,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/da/ef/5790e74a7b39d2c085554f347be22a1882649a29a7a65e9c81bfaf9e8fc6/falcon-4.3.1-py3-none-any.whl", hash = "sha256:5402602d14bc426afc01c388538f2ad402ac4c8c2477415dfe972a2deee17248", size = 332719, upload-time = "2026-06-16T05:31:23.373Z" },
 ]
 
+[[package]]
+name = "filelock"
+version = "3.32.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6d/30/03b03951873a1a0ffc7e8ca0e10c15597b59e8d0e39260704cd2ea087bc4/filelock-3.32.4.tar.gz", hash = "sha256:2bde2e4cf732e0153406d8a7bc80620ecf5e621fe0d25e41143c4e3b4733ff30", size = 222126, upload-time = "2026-08-23T17:37:55.363Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/01/a4/9b63d595d748e3aff8812b65eacc1a2c4bd90b7c2012e08e72373b4835eb/filelock-3.32.4-py3-none-any.whl", hash = "sha256:22e58ca3b1ae3b98993b762d7338367ae64fe50252bf78d59da3bfebcdf1cedd", size = 99864, upload-time = "2026-08-23T17:37:53.913Z" },
+]
+
 [[package]]
 name = "frozenlist"
 version = "1.8.0"
@@ -2560,7 +2569,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.29.2"
+version = "0.29.4"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -2591,7 +2600,7 @@ dev = [
     { name = "pytest-xdist" },
     { name = "ruff" },
     { name = "sqlglot" },
-    { name = "vgi-rpc", extra = ["conformance", "external", "http", "oauth", "otel", "sentry"] },
+    { name = "vgi-rpc", extra = ["cli", "conformance", "external", "http", "oauth", "otel", "sentry"] },
 ]
 duckdb = [
     { name = "duckdb" },
@@ -2609,6 +2618,9 @@ haybarn = [
 http = [
     { name = "vgi-rpc", extra = ["http"] },
 ]
+launch = [
+    { name = "vgi-rpc", extra = ["cli"] },
+]
 oauth = [
     { name = "vgi-rpc", extra = ["oauth"] },
 ]
@@ -2672,17 +2684,18 @@ requires-dist = [
     { name = "typer", specifier = ">=0.9" },
     { name = "vgi-fixtures", marker = "extra == 'fixtures'", editable = "packages/vgi-fixtures" },
     { 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 = ["test-fixtures", "test-fixtures-writable", "http", "launch", "oauth", "otel", "sentry", "azure"], marker = "extra == 'dev'" },
     { name = "vgi-python", extras = ["transactor"], marker = "extra == 'test-fixtures-writable'" },
-    { name = "vgi-rpc", specifier = ">=0.43.0" },
-    { name = "vgi-rpc", extras = ["conformance", "external", "http", "oauth", "otel", "sentry"], marker = "extra == 'dev'" },
+    { name = "vgi-rpc", specifier = ">=0.43.2" },
+    { name = "vgi-rpc", extras = ["cli"], marker = "extra == 'launch'" },
+    { name = "vgi-rpc", extras = ["cli", "conformance", "external", "http", "oauth", "otel", "sentry"], marker = "extra == 'dev'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'granian'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'http'" },
     { name = "vgi-rpc", extras = ["oauth"], marker = "extra == 'oauth'" },
     { name = "vgi-rpc", extras = ["otel"], marker = "extra == 'otel'" },
     { name = "vgi-rpc", extras = ["sentry"], marker = "extra == 'sentry'" },
 ]
-provides-extras = ["haybarn", "duckdb", "http", "granian", "oauth", "otel", "sentry", "azure", "test-fixtures", "transactor", "fixtures", "test-fixtures-writable", "dev"]
+provides-extras = ["haybarn", "duckdb", "http", "launch", "granian", "oauth", "otel", "sentry", "azure", "test-fixtures", "transactor", "fixtures", "test-fixtures-writable", "dev"]
 
 [package.metadata.requires-dev]
 dev = [
@@ -2703,7 +2716,7 @@ docs = [
 
 [[package]]
 name = "vgi-rpc"
-version = "0.43.1"
+version = "0.43.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "docstring-parser" },
@@ -2711,12 +2724,17 @@ dependencies = [
     { name = "pywin32", marker = "sys_platform == 'win32'" },
     { name = "tzdata", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/27/a0/b308cc62cde38fe2a7bc7a2c57bbb8e956084dd04134a4b0d805378daf16/vgi_rpc-0.43.1.tar.gz", hash = "sha256:d94a3c2cfcf90e1122b2b7ec23a47912f1b3e2d265267aa6704bd64c3a7f2a55", size = 1145519, upload-time = "2026-08-27T14:51:14.923Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/ce/04/efb99f0fb56535bcba110e6c12448c31b429e0861aae4bc2f7136299cfc2/vgi_rpc-0.43.2.tar.gz", hash = "sha256:6a06437af17442451bfe07186bc472a2efb57e030b0e5b38a28922034a814123", size = 1147340, upload-time = "2026-08-27T18:33:54.608Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/96/f2/15bd8a76ee3534c4d911b0f76c948378db4c175a40ceeb30325e6ab994a6/vgi_rpc-0.43.1-py3-none-any.whl", hash = "sha256:1eecd6c17f06d6fadae332be33998d22cdd01e5caaaae7889b747f0c1eaac498", size = 526753, upload-time = "2026-08-27T14:51:12.975Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/b9/33cdb4fe27ef3893e1cded63f396af8bc517e390615f34db6f4bd227ef4c/vgi_rpc-0.43.2-py3-none-any.whl", hash = "sha256:b112ab76828367176a41f1b9a4ceeaba8979629e4e5972f64bf769c94b3e36a4", size = 528134, upload-time = "2026-08-27T18:33:52.829Z" },
 ]
 
 [package.optional-dependencies]
+cli = [
+    { name = "filelock" },
+    { name = "httpx2" },
+    { name = "typer" },
+]
 conformance = [
     { name = "jsonschema" },
     { name = "psutil" },

{vgi_python-0.29.3 → vgi_python-0.29.4}/vgi/client/catalog_mixin.py

@@ -100,9 +100,11 @@ class CatalogClientMixin:
     non-DuckDB use case this mixin supports.
 
     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).
+    http, tcp, or launch), ``_base_url`` (HTTP base URL), ``_tcp_host`` /
+    ``_tcp_port`` (TCP endpoint), ``_launch_argv`` / ``_launch_idle_timeout`` /
+    ``_launch_state_dir`` / ``_launch_socket_path`` (launcher worker
+    identity + lifecycle), and ``_get_or_create_httpx_client()`` (shared
+    HTTP client factory).
 
     Attributes:
         server_path: Worker command used for subprocess transport — a string to
@@ -111,10 +113,14 @@ class CatalogClientMixin:
 
     # Type hints for attributes expected from Client
     server_path: str | Sequence[str]
-    _transport: Literal["subprocess", "http", "tcp"]
+    _transport: Literal["subprocess", "http", "tcp", "launch"]
     _base_url: str | None
     _tcp_host: str | None
     _tcp_port: int | None
+    _launch_argv: tuple[str, ...] | None
+    _launch_idle_timeout: float
+    _launch_state_dir: str | None
+    _launch_socket_path: str | None
     _external_location: Any | None
 
     def _worker_argv(self) -> list[str]:
@@ -144,6 +150,11 @@ class CatalogClientMixin:
         ``Client._get_or_create_httpx_client`` so auth headers and
         connection pooling are consistent.
 
+        Launch: opens a short-lived ``resolve_and_connect`` session per call
+        against the launcher-managed shared worker — same warm-worker sharing
+        as exchange-mode calls (``Client._spawn_launch_connection``), just a
+        fresh connection to it per catalog RPC rather than one held open.
+
         Worker errors are caught and re-raised as ``CatalogClientError``.
 
         Yields:
@@ -173,6 +184,22 @@ class CatalogClientMixin:
                     external_location=getattr(self, "_external_location", None),
                 ) as proxy:
                     yield proxy
+            elif transport == "launch":
+                from vgi_rpc.launcher import LaunchConfig, resolve_and_connect
+
+                assert self._launch_argv is not None
+                config = LaunchConfig(
+                    worker_argv=self._launch_argv,
+                    socket_path=self._launch_socket_path,
+                    idle_timeout=self._launch_idle_timeout,
+                    state_dir=self._launch_state_dir,
+                )
+                with resolve_and_connect(
+                    VgiProtocol,  # type: ignore[type-abstract]
+                    config,
+                    external_location=getattr(self, "_external_location", None),
+                ) as proxy:
+                    yield proxy
             else:
                 cmd = self._worker_argv()
                 with _catalog_pool.connect(VgiProtocol, cmd) as proxy:  # type: ignore[type-abstract]

{vgi_python-0.29.3 → vgi_python-0.29.4}/vgi/client/client.py

@@ -184,10 +184,10 @@ _HTTP_TRANSPORT_READY = True
 
 @dataclass
 class WorkerConnection:
-    """Holds state for a single worker connection (subprocess, HTTP, or TCP).
+    """Holds state for a single worker connection (subprocess, HTTP, TCP, or launch).
 
-    Exactly one of {proc+connection, _pool_ctx, _http_ctx, _tcp_ctx} is active
-    per connection — transport-specific teardown inspects these fields.
+    Exactly one of {proc+connection, _pool_ctx, _http_ctx, _tcp_ctx, _launch_ctx}
+    is active per connection — transport-specific teardown inspects these fields.
 
     Attributes:
         proxy: The typed `[`VgiProtocol`][]` proxy used to invoke the worker.
@@ -209,6 +209,8 @@ class WorkerConnection:
     _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)
+    # Launch transport: context manager from vgi_rpc.launcher.resolve_and_connect.
+    _launch_ctx: AbstractContextManager[Any] | None = field(default=None, repr=False)
 
 
 class Client(CatalogClientMixin, AggregateClientMixin):
@@ -389,13 +391,17 @@ class Client(CatalogClientMixin, AggregateClientMixin):
         attach_opaque_data: bytes | None = None,
         pool: WorkerPool | None = _default_pool,
         *,
-        transport: Literal["subprocess", "http", "tcp"] = "subprocess",
+        transport: Literal["subprocess", "http", "tcp", "launch"] = "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,
+        launch_argv: Sequence[str] | None = None,
+        launch_idle_timeout: float = 300.0,
+        launch_state_dir: str | None = None,
+        launch_socket_path: str | None = None,
     ):
         """Initialize the VGI client.
 
@@ -430,7 +436,10 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 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(...)``).
+                trusted networks only; use ``Client.from_tcp(...)``); ``"launch"``
+                spawns-or-reuses a warm worker shared across every client
+                pointing at the same command, coordinated via
+                ``vgi_rpc.launcher`` (use ``Client.from_launch(...)``).
             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.
@@ -449,6 +458,20 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 transport so pointer batches are resolved automatically.
                 Subprocess transport ignores this — subprocess workers
                 don't return pointer batches.
+            launch_argv: Launch-only. The worker command and arguments (an
+                argv sequence, not a shell string — matches
+                ``vgi_rpc.launcher.LaunchConfig.worker_argv``). Requires the
+                ``vgi-python[launch]`` extra (pulls in ``vgi-rpc[cli]`` for
+                ``filelock``, which ``vgi_rpc.launcher`` imports unconditionally).
+            launch_idle_timeout: Launch-only. The shared worker self-terminates
+                after this many idle seconds with zero connected clients.
+                Forwarded to ``LaunchConfig.idle_timeout``.
+            launch_state_dir: Launch-only. Override the launcher's default
+                per-user state directory (lockfiles + sockets). Forwarded to
+                ``LaunchConfig.state_dir``.
+            launch_socket_path: Launch-only. Explicit socket path, skipping
+                the hash-derived default. Forwarded to
+                ``LaunchConfig.socket_path``.
 
         Raises:
             ValueError: If the transport / server_path / base_url
@@ -472,6 +495,15 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 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'")
+        elif transport == "launch":
+            if not launch_argv:
+                raise ValueError("transport='launch' requires a non-empty launch_argv")
+            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'")
+            if tcp_host is not None or tcp_port is not None:
+                raise ValueError("tcp_host/tcp_port are only meaningful for transport='tcp'")
         else:
             raise ValueError(f"unknown transport {transport!r}")
 
@@ -482,13 +514,19 @@ class Client(CatalogClientMixin, AggregateClientMixin):
         self._tcp_port = tcp_port
         self._bearer_token = bearer_token
         self._httpx_client = httpx_client
+        self._launch_argv = tuple(launch_argv) if launch_argv is not None else None
+        self._launch_idle_timeout = launch_idle_timeout
+        self._launch_state_dir = launch_state_dir
+        self._launch_socket_path = launch_socket_path
         # True when ``_get_or_create_httpx_client`` constructed the client and
         # is therefore responsible for closing it on ``stop()``. False when
         # the caller passed ``httpx_client=`` — ownership stays with them.
         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 in ("http", "tcp") and external_location is None:
+        # Auto-enable pointer-batch resolution for HTTP/TCP/launch unless the
+        # caller asked for something different — all three are ordinary RPC
+        # transports a worker can externalize batches over, unlike subprocess
+        # (which never returns pointer batches). See ``external_location`` docs above.
+        if transport in ("http", "tcp", "launch") and external_location is None:
             from vgi_rpc.external import ExternalLocationConfig
 
             external_location = ExternalLocationConfig()
@@ -565,6 +603,63 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             pool=None,
         )
 
+    @classmethod
+    def from_launch(
+        cls,
+        worker_argv: Sequence[str],
+        *,
+        idle_timeout: float = 300.0,
+        state_dir: str | None = None,
+        socket_path: str | None = None,
+        external_location: Any | None = None,
+        worker_limit: int | None = None,
+        attach_opaque_data: bytes | None = None,
+    ) -> Client:
+        """Create a `[`Client`][]` bound to a launcher-managed warm worker.
+
+        Spawns (or reuses) a worker process serving over an ``AF_UNIX``
+        socket via ``vgi_rpc.launcher`` — every client across the machine
+        pointing at the same ``worker_argv`` shares one warm worker,
+        coordinated by a per-command-hash flock, and the worker
+        self-terminates after ``idle_timeout`` idle seconds with zero
+        connected clients. This is the Python client-side counterpart to the
+        VGI DuckDB extension's ``launch:<argv>`` LOCATION scheme. Requires
+        the ``vgi-python[launch]`` extra.
+
+        Args:
+            worker_argv: The worker command and arguments, as an argv
+                sequence — not a shell string, and not split with
+                ``shlex.split`` the way ``server_path`` is for
+                ``transport="subprocess"``.
+            idle_timeout: Shared worker self-shutdown after this many idle
+                seconds.
+            state_dir: Override the launcher's default per-user state
+                directory (lockfiles + sockets).
+            socket_path: Explicit socket path, skipping the hash-derived
+                default — every caller passing the same explicit path
+                shares that worker regardless of ``worker_argv`` differences.
+            external_location: Optional ``ExternalLocationConfig`` — see the
+                constructor's docstring.
+            worker_limit: Maximum number of parallel worker connections.
+            attach_opaque_data: Optional unique identifier for the DuckDB
+                database attachment.
+
+        Returns:
+            A `[`Client`][]` bound to the launcher-managed worker.
+
+        """
+        return cls(
+            transport="launch",
+            launch_argv=worker_argv,
+            launch_idle_timeout=idle_timeout,
+            launch_state_dir=state_dir,
+            launch_socket_path=socket_path,
+            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.
 
@@ -660,6 +755,8 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             return self._spawn_http_connection(worker_index)
         if self._transport == "tcp":
             return self._spawn_tcp_connection(worker_index)
+        if self._transport == "launch":
+            return self._spawn_launch_connection(worker_index)
         return self._spawn_subprocess_connection(worker_index)
 
     def _spawn_tcp_connection(self, worker_index: int) -> WorkerConnection:
@@ -692,6 +789,41 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             _tcp_ctx=ctx,
         )
 
+    def _spawn_launch_connection(self, worker_index: int) -> WorkerConnection:
+        """Connect to a launcher-managed worker via ``vgi_rpc.launcher.resolve_and_connect``.
+
+        Every ``Client`` (in this process or any other on the machine) built
+        with the same ``launch_argv`` shares one warm worker — see
+        ``from_launch``. Multiple ``worker_index`` values open independent
+        connections to that same shared worker.
+        """
+        from vgi_rpc.launcher import LaunchConfig, resolve_and_connect
+
+        assert self._launch_argv is not None  # enforced in __init__
+        config = LaunchConfig(
+            worker_argv=self._launch_argv,
+            socket_path=self._launch_socket_path,
+            idle_timeout=self._launch_idle_timeout,
+            state_dir=self._launch_state_dir,
+        )
+        ctx: AbstractContextManager[VgiProtocol] = resolve_and_connect(
+            VgiProtocol,  # type: ignore[type-abstract]
+            config,
+            on_log=self._on_worker_log,
+            external_location=self._external_location,
+        )
+        proxy = ctx.__enter__()
+        _logger.debug(
+            "launch_connection_opened worker_index=%s argv=%s",
+            worker_index,
+            self._launch_argv,
+        )
+        return WorkerConnection(
+            proxy=proxy,
+            worker_index=worker_index,
+            _launch_ctx=ctx,
+        )
+
     def _spawn_http_connection(self, worker_index: int) -> WorkerConnection:
         """Connect to a remote HTTP worker via ``vgi_rpc.http.http_connect``.
 
@@ -863,6 +995,14 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             _logger.debug("tcp_connection_closed worker_index=%s", worker.worker_index)
             return 0
 
+        if worker._launch_ctx is not None:
+            # Launch transport — close the RPC proxy (and its socket). The
+            # shared worker process itself is untouched: it lives on for other
+            # clients and self-terminates via its own idle timer.
+            worker._launch_ctx.__exit__(None, None, None)
+            _logger.debug("launch_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)
@@ -979,6 +1119,8 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             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})"
+        elif self._primary._launch_ctx is not None:
+            id_repr = f"launch({' '.join(self._launch_argv or ())})"
         else:
             id_repr = "pooled"
         _logger.debug("server_started id=%s", id_repr)