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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.29.0
+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
@@ -212,18 +215,22 @@ Provides-Extra: transactor
 Requires-Dist: sqlglot; extra == 'transactor'
 Description-Content-Type: text/markdown
 
-# VGI (Vector Gateway Interface)
-
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Query-farm/vgi-python/main/docs/vgi-logo.png" alt="VGI Logo" width="480">
+  <img src="https://raw.githubusercontent.com/Query-farm/vgi-python/main/docs/vgi-logo.png?v=2" alt="Vector Gateway Interface logo" width="320">
 </p>
 
+<h1 align="center">VGI</h1>
+
 <p align="center">
-  <strong>Apache Arrow-based protocol for extending DuckDB using any language.</strong>
+  Apache Arrow-based protocol for extending DuckDB using any language — the Python reference implementation.<br>
+  Built by <a href="https://query.farm">🚜 Query.Farm</a>
 </p>
 
 <p align="center">
-  Created by <a href="https://query.farm">Query.Farm</a>
+  <a href="https://github.com/Query-farm/vgi-python/actions/workflows/ci.yml"><img src="https://github.com/Query-farm/vgi-python/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/vgi-python/"><img src="https://img.shields.io/pypi/v/vgi-python" alt="PyPI"></a>
+  <a href="https://pypi.org/project/vgi-python/"><img src="https://img.shields.io/pypi/pyversions/vgi-python" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/pypi/l/vgi-python" alt="License"></a>
 </p>
 
 ---

{vgi_python-0.29.0 → vgi_python-0.29.4}/README.md

@@ -1,15 +1,19 @@
-# VGI (Vector Gateway Interface)
-
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Query-farm/vgi-python/main/docs/vgi-logo.png" alt="VGI Logo" width="480">
+  <img src="https://raw.githubusercontent.com/Query-farm/vgi-python/main/docs/vgi-logo.png?v=2" alt="Vector Gateway Interface logo" width="320">
 </p>
 
+<h1 align="center">VGI</h1>
+
 <p align="center">
-  <strong>Apache Arrow-based protocol for extending DuckDB using any language.</strong>
+  Apache Arrow-based protocol for extending DuckDB using any language — the Python reference implementation.<br>
+  Built by <a href="https://query.farm">🚜 Query.Farm</a>
 </p>
 
 <p align="center">
-  Created by <a href="https://query.farm">Query.Farm</a>
+  <a href="https://github.com/Query-farm/vgi-python/actions/workflows/ci.yml"><img src="https://github.com/Query-farm/vgi-python/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/vgi-python/"><img src="https://img.shields.io/pypi/v/vgi-python" alt="PyPI"></a>
+  <a href="https://pypi.org/project/vgi-python/"><img src="https://img.shields.io/pypi/pyversions/vgi-python" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/pypi/l/vgi-python" alt="License"></a>
 </p>
 
 ---

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

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.29.0"
+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/client/test_batch_metadata_callback.py

@@ -0,0 +1,77 @@
+# Copyright 2026 Query Farm LLC - https://query.farm
+
+# ruff: noqa: S101, D101, D102, D103
+"""`Client.table_function(batch_metadata_callback=...)`.
+
+`_table_function_parallel` previously discarded `AnnotatedBatch.custom_metadata`
+unconditionally (`if output.batch.num_rows > 0: output_queue.put(output.batch)`)
+and only forwarded the bare `pa.RecordBatch` — so a worker's `vgi.cache.*`
+cacheability advertisement (`vgi/cache_control.py`), which rides
+`custom_metadata`, was structurally unreachable through the public
+`table_function()` generator. `batch_metadata_callback` mirrors the existing
+`bind_result_callback` pattern to fix that additively, with no change to the
+generator's yield type. Exercised against `cacheable_numbers`
+(`vgi/_test_fixtures/table/cache.py`), which advertises `vgi.cache.ttl` on its
+first batch.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pyarrow as pa
+import pytest
+
+from vgi.arguments import Arguments
+
+DATA = "data"
+
+
+@pytest.fixture
+def client(client_transport: Any) -> Any:
+    with client_transport() as c:
+        c.catalog_attach(name="example", data_version_spec=None, implementation_version=None)
+        yield c
+
+
+def test_callback_receives_cache_control_metadata(client: Any) -> None:
+    metas: list[pa.KeyValueMetadata | None] = []
+    batches = list(
+        client.table_function(
+            function_name="cacheable_numbers",
+            schema_name=DATA,
+            arguments=Arguments(named={"n": pa.scalar(5)}),
+            batch_metadata_callback=metas.append,
+        )
+    )
+    assert sum(b.num_rows for b in batches) == 5
+    assert len(metas) == len(batches)
+    assert metas[0] is not None
+    assert dict(metas[0])[b"vgi.cache.ttl"] == b"300"
+
+
+def test_callback_is_optional_and_defaults_to_none(client: Any) -> None:
+    """No `batch_metadata_callback` -> unchanged behavior, no crash."""
+    batches = list(
+        client.table_function(
+            function_name="cacheable_numbers",
+            schema_name=DATA,
+            arguments=Arguments(named={"n": pa.scalar(3)}),
+        )
+    )
+    assert sum(b.num_rows for b in batches) == 3
+
+
+def test_callback_sees_none_for_a_batch_without_custom_metadata(client: Any) -> None:
+    """A function that never advertises cache control still drives the callback once per batch, with `None`."""
+    metas: list[pa.KeyValueMetadata | None] = []
+    list(
+        client.table_function(
+            function_name="sequence",
+            schema_name="main",
+            arguments=Arguments(positional=[pa.scalar(4)]),
+            batch_metadata_callback=metas.append,
+        )
+    )
+    assert metas
+    assert all(m is None for m in metas)

vgi_python-0.29.4/tests/client/test_scan_branches_client.py

@@ -0,0 +1,67 @@
+# Copyright 2026 Query Farm LLC - https://query.farm
+
+# ruff: noqa: S101, D101, D102, D103
+"""`Client.table_scan_branches_get`.
+
+`Client` had no wrapper for `catalog_table_scan_branches_get` at all —
+grepped the whole `vgi/client/` package for "branch" and the only hit was an
+unrelated code comment ("skip the subprocess branch"). A multi-branch table
+was therefore invisible to any non-DuckDB caller, not just unsupported by a
+higher-level connector. Exercised against `data.multi_branch_numbers` (two
+`sequence(50)` arms — `vgi/_test_fixtures/worker.py`) and, for the legacy
+fallback, `data.numbers` (an ordinary single-branch table whose worker only
+implements the older `table_scan_function_get`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from vgi.catalog import ScanBranch, ScanBranchesResult
+
+DATA = "data"
+
+
+@pytest.fixture
+def client(client_transport: Any) -> Any:
+    with client_transport() as c:
+        c.catalog_attach(name="example", data_version_spec=None, implementation_version=None)
+        yield c
+
+
+def _attach_opaque(client: Any) -> Any:
+    # catalog_attach() was already called by the fixture above (its return
+    # value discarded) — re-attach here to get the opaque data this method
+    # needs, mirroring how CatalogClientMixin methods are used standalone.
+    return client.catalog_attach(name="example", data_version_spec=None, implementation_version=None).attach_opaque_data
+
+
+def test_multi_branch_table_returns_all_branches(client: Any) -> None:
+    result = client.table_scan_branches_get(
+        attach_opaque_data=_attach_opaque(client),
+        schema_name=DATA,
+        name="multi_branch_numbers",
+    )
+    assert isinstance(result, ScanBranchesResult)
+    assert len(result.branches) == 2
+    for branch in result.branches:
+        assert isinstance(branch, ScanBranch)
+        assert branch.function_name == "sequence"
+        assert branch.source_table is None  # function branch, not catalog-table
+
+
+def test_single_branch_table_falls_back_to_legacy_rpc(client: Any) -> None:
+    """`data.numbers` only implements `table_scan_function_get` — the fallback wraps it as one branch."""
+    result = client.table_scan_branches_get(
+        attach_opaque_data=_attach_opaque(client),
+        schema_name=DATA,
+        name="numbers",
+    )
+    assert len(result.branches) == 1
+    assert result.branches[0].function_name == client.table_scan_function_get(
+        attach_opaque_data=_attach_opaque(client),
+        schema_name=DATA,
+        name="numbers",
+    ).function_name

vgi_python-0.29.4/tests/client/test_split_client.py

@@ -0,0 +1,93 @@
+# Copyright 2026 Query Farm LLC - https://query.farm
+
+# ruff: noqa: S101, D101, D102, D103
+"""`Client.table_function_plan` + `Client.table_function(split_tokens=...)`.
+
+Splits were previously entirely unreachable from `Client` — no wrapper for
+`on_plan()` existed at all, and `table_function()`/`_do_init` had no
+`split_tokens` parameter to redeem one, even though the wire protocol
+(`TableFunctionPlanRequest`/`PlanResponse`/`InitRequest.split_tokens`) and the
+`VgiProtocol.table_function_plan` RPC already supported it — the DuckDB C++
+extension drives this today, but the reference Python client never grew the
+equivalent. Exercised against `split_sequence` (the split-capable twin of
+`sequence`, `vgi/_test_fixtures/table/splits.py`) over every client transport.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pyarrow as pa
+import pytest
+
+from vgi.arguments import Arguments
+from vgi.protocol import ScanSplit
+
+MAIN = "main"
+
+
+@pytest.fixture
+def client(client_transport: Any) -> Any:
+    with client_transport() as c:
+        c.catalog_attach(name="example", data_version_spec=None, implementation_version=None)
+        yield c
+
+
+def test_plan_returns_typed_scan_splits(client: Any) -> None:
+    args = Arguments(named={"n": pa.scalar(20), "splits": pa.scalar(4)})
+    plan = client.table_function_plan(function_name="split_sequence", schema_name=MAIN, arguments=args)
+    assert len(plan.splits) == 4
+    for split in plan.splits:
+        assert isinstance(split, ScanSplit)
+        assert split.token  # framework-stamped, non-empty
+        assert split.estimated_rows == 5
+
+
+def test_redeeming_each_split_in_order_reproduces_the_whole_scan(client: Any) -> None:
+    """split_sequence redeemed split-by-split must equal sequence(n)'s output.
+
+    Also threads ``split_execution_id``/``split_init_opaque_data`` from the
+    plan on every redemption — this fixture doesn't need cross-split shared
+    state to be correct, but this proves the wire path accepts and round-trips
+    them without erroring, for workers that do.
+    """
+    args = Arguments(named={"n": pa.scalar(37), "splits": pa.scalar(5)})
+    plan = client.table_function_plan(function_name="split_sequence", schema_name=MAIN, arguments=args)
+
+    all_rows: list[int] = []
+    for split in plan.splits:
+        batches = list(
+            client.table_function(
+                function_name="split_sequence",
+                schema_name=MAIN,
+                arguments=args,
+                split_tokens=[split.token],
+                split_execution_id=plan.execution_id,
+                split_init_opaque_data=plan.init_opaque_data,
+            )
+        )
+        for batch in batches:
+            all_rows.extend(batch.column("n").to_pylist())
+
+    assert sorted(all_rows) == list(range(37))
+
+
+def test_split_zero_yields_no_splits_and_no_rows(client: Any) -> None:
+    args = Arguments(named={"n": pa.scalar(10), "splits": pa.scalar(4)})
+    plan = client.table_function_plan(function_name="split_zero", schema_name=MAIN, arguments=args)
+    assert plan.splits == []
+
+
+def test_redeeming_a_split_forces_single_worker(client: Any) -> None:
+    """`split_tokens` bypasses `_spawn_additional_workers` — no additional worker connections open."""
+    args = Arguments(named={"n": pa.scalar(8), "splits": pa.scalar(2)})
+    plan = client.table_function_plan(function_name="split_sequence", schema_name=MAIN, arguments=args)
+    list(
+        client.table_function(
+            function_name="split_sequence",
+            schema_name=MAIN,
+            arguments=args,
+            split_tokens=[plan.splits[0].token],
+        )
+    )
+    assert client._additional_workers == []

vgi_python-0.29.4/tests/client/test_time_travel_client.py

@@ -0,0 +1,85 @@
+# Copyright 2026 Query Farm LLC - https://query.farm
+
+# ruff: noqa: S101, D101, D102, D103
+"""`Client.table_get`/`table_function(at_unit=..., at_value=...)`.
+
+Both methods previously dropped `at_unit`/`at_value` on the floor even though
+the underlying wire RPCs (`catalog_table_get`, `BindRequest.at_unit`/
+`.at_value`) already carried them — `table_scan_function_get` was the only
+`Client` method that exposed time travel at all. Two distinct worker
+patterns are exercised, both real fixtures, proving this isn't just plumbing
+that happens to compile:
+
+* `data.versioned_data` reads its version through a pre-resolved bind
+  argument (`table_scan_function_get(at_unit=...)` bakes it into the
+  returned `ScanFunctionResult.arguments`) — `table_get(at_unit=...)` is
+  what needed fixing here, to see the schema at that version at all.
+* `data.tt_pushdown_fn` (`tt_pushdown_scan`) reads `at_unit`/`at_value`
+  **directly off the init request** (`ProcessParams.at_unit`/`.at_value`,
+  see `vgi/_test_fixtures/table/tt_pushdown.py`) — this is the pattern that
+  needed `table_function(at_unit=...)` specifically; no amount of
+  pre-resolved arguments would reach it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pyarrow as pa
+import pytest
+
+from vgi.arguments import Arguments
+
+DATA = "data"
+
+
+@pytest.fixture
+def client(client_transport: Any) -> Any:
+    with client_transport() as c:
+        c.catalog_attach(name="example", data_version_spec=None, implementation_version=None)
+        yield c
+
+
+def _attach_opaque(client: Any) -> Any:
+    result = client.catalog_attach(name="example", data_version_spec=None, implementation_version=None)
+    return result.attach_opaque_data
+
+
+def test_table_get_at_unit_returns_the_versioned_schema(client: Any) -> None:
+    opaque = _attach_opaque(client)
+    v1 = client.table_get(
+        attach_opaque_data=opaque, schema_name=DATA, name="versioned_data", at_unit="VERSION", at_value="1"
+    )
+    live = client.table_get(attach_opaque_data=opaque, schema_name=DATA, name="versioned_data")
+
+    v1_schema = pa.ipc.read_schema(pa.py_buffer(v1.columns))
+    live_schema = pa.ipc.read_schema(pa.py_buffer(live.columns))
+    assert v1_schema.names == ["id"]  # version 1: (id int64) only
+    assert live_schema.names == ["id", "score"]  # current: version 3
+
+
+def test_table_get_with_no_at_clause_is_unaffected(client: Any) -> None:
+    """The new `at_unit`/`at_value` params default to `None` — unchanged behavior without them."""
+    info = client.table_get(attach_opaque_data=_attach_opaque(client), schema_name=DATA, name="numbers")
+    assert info is not None
+
+
+def test_table_function_at_unit_reaches_a_worker_that_reads_it_from_init(client: Any) -> None:
+    """`tt_pushdown_scan` reads `at_unit`/`at_value` off the init request, not a resolved bind arg."""
+    v1_batches = list(
+        client.table_function(function_name="tt_pushdown_scan", schema_name=DATA, at_unit="VERSION", at_value="1")
+    )
+    live_batches = list(client.table_function(function_name="tt_pushdown_scan", schema_name=DATA))
+
+    assert sum(b.num_rows for b in v1_batches) == 5
+    assert sum(b.num_rows for b in live_batches) == 10
+
+
+def test_table_function_with_no_at_clause_is_unaffected(client: Any) -> None:
+    """The new `at_unit`/`at_value` params default to `None` — unchanged behavior without them."""
+    batches = list(
+        client.table_function(
+            function_name="sequence", schema_name="main", arguments=Arguments(positional=[pa.scalar(5)])
+        )
+    )
+    assert sum(b.num_rows for b in batches) == 5

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)