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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.8.6
+Version: 0.8.8
 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.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.8.6"
+version = "0.8.8"
 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.6 → vgi_python-0.8.8}/tests/conformance/test_protocol_inventory.py

@@ -180,6 +180,15 @@ _RPC_ALLOWLIST: dict[str, tuple[str, ...] | NotExposed] = {
     "catalog_schema_contents_views": ("schema_contents",),
     "catalog_schema_contents_functions": ("schema_contents",),
     "catalog_schema_contents_macros": ("schema_contents",),
+    "catalog_copy_from_formats": NotExposed(
+        reason=(
+            "COPY ... FROM format discovery. Consumed today by the C++ extension, "
+            "which calls this at ATTACH to register a DuckDB CopyFunction per "
+            "advertised format; covered by C++ integration/copy_from/*.test. Client "
+            "wrappers for the other VGI languages are planned to follow the "
+            "Python/C++ implementation."
+        )
+    ),
     "catalog_schema_contents_indexes": NotExposed(
         reason=(
             "DuckDB-only metadata path. Indexes are catalog-planner territory; "

vgi_python-0.8.8/tests/test_copy_from_function.py

@@ -0,0 +1,147 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Worker-side unit tests for CopyFromFunction and the example_lines format."""
+
+from __future__ import annotations
+
+import tempfile
+
+import pyarrow as pa
+import pytest
+
+from vgi._test_fixtures.copy_from import ExampleLinesCopyFromArgs, ExampleLinesCopyFromFunction
+from vgi._test_fixtures.worker import ExampleCatalog
+from vgi.arguments import Arguments
+from vgi.invocation import FunctionType
+from vgi.protocol import BindRequest, CopyFromContext
+
+
+class _CollectOut:
+    """Minimal OutputCollector stand-in for read()."""
+
+    def __init__(self) -> None:
+        self.batches: list[pa.RecordBatch] = []
+
+    def emit(self, batch: pa.RecordBatch, **_kwargs: object) -> None:
+        self.batches.append(batch)
+
+    def finish(self) -> None:  # pragma: no cover - read() never calls finish itself
+        pass
+
+
+def _write(text: str) -> str:
+    """Write ``text`` to a throwaway file and return its path."""
+    with tempfile.NamedTemporaryFile("w", suffix=".txt", delete=False) as fp:
+        fp.write(text)
+        return fp.name
+
+
+EXPECTED = pa.schema([("a", pa.int64()), ("b", pa.string())])
+
+
+def test_on_bind_binds_to_expected_schema() -> None:
+    """on_bind binds output to the COPY target schema."""
+    cf = CopyFromContext(format="example_lines", file_path="/x", expected_schema=EXPECTED)
+    br = BindRequest(
+        function_name="example_lines_copy_reader",
+        arguments=Arguments(named={"null_string": pa.scalar("NA")}),
+        function_type=FunctionType.TABLE,
+        copy_from=cf,
+    )
+    resp = ExampleLinesCopyFromFunction.bind(br)
+    assert resp.output_schema.equals(EXPECTED)
+
+
+def test_on_bind_without_copy_from_context_raises() -> None:
+    """on_bind rejects a non-COPY invocation."""
+    br = BindRequest(
+        function_name="example_lines_copy_reader",
+        arguments=Arguments(named={"null_string": pa.scalar("NA")}),
+        function_type=FunctionType.TABLE,
+    )
+    with pytest.raises(ValueError, match="COPY FROM format reader"):
+        ExampleLinesCopyFromFunction.bind(br)
+
+
+def test_read_parses_and_coerces_with_null_string() -> None:
+    """read() parses, null-maps, and casts to the target schema."""
+    path = _write("1,foo\n2,NA\n3,baz\n")
+    out = _CollectOut()
+    ExampleLinesCopyFromFunction.read(
+        path=path,
+        options=ExampleLinesCopyFromArgs(null_string="NA"),
+        expected_schema=EXPECTED,
+        params=None,
+        out=out,
+    )
+    table = pa.Table.from_batches(out.batches)
+    assert table.schema.equals(EXPECTED)
+    assert table.to_pydict() == {"a": [1, 2, 3], "b": ["foo", None, "baz"]}
+
+
+def test_read_custom_delimiter_and_skip_rows() -> None:
+    """read() honors delimiter and skip_rows options."""
+    path = _write("# header\n1|a\n2|b\n")
+    out = _CollectOut()
+    ExampleLinesCopyFromFunction.read(
+        path=path,
+        options=ExampleLinesCopyFromArgs(null_string="NA", delimiter="|", skip_rows=1),
+        expected_schema=EXPECTED,
+        params=None,
+        out=out,
+    )
+    assert pa.Table.from_batches(out.batches).to_pydict() == {"a": [1, 2], "b": ["a", "b"]}
+
+
+def test_read_on_error_fail_vs_skip() -> None:
+    """on_error 'fail' raises; 'skip' drops the bad row."""
+    path = _write("1,a\nBADROW\n3,c\n")
+    with pytest.raises(ValueError, match="example_lines: row has"):
+        ExampleLinesCopyFromFunction.read(
+            path=path,
+            options=ExampleLinesCopyFromArgs(null_string="NA"),  # on_error defaults to "fail"
+            expected_schema=EXPECTED,
+            params=None,
+            out=_CollectOut(),
+        )
+
+    out = _CollectOut()
+    ExampleLinesCopyFromFunction.read(
+        path=path,
+        options=ExampleLinesCopyFromArgs(null_string="NA", on_error="skip"),
+        expected_schema=EXPECTED,
+        params=None,
+        out=out,
+    )
+    assert pa.Table.from_batches(out.batches).num_rows == 2
+
+
+def test_catalog_advertises_copy_format() -> None:
+    """The example catalog advertises the example_lines format."""
+    formats = ExampleCatalog().copy_from_formats(attach_opaque_data=b"", transaction_opaque_data=None)
+    by_name = {f.format_name: f for f in formats}
+    assert "example_lines" in by_name
+    fmt = by_name["example_lines"]
+    assert fmt.handler == "example_lines_copy_reader"
+    assert fmt.direction == "from"
+    assert fmt.comment == "Toy delimited-text reader for tests"
+    assert fmt.tags.get("category") == "copy_from"
+    opt_schema = pa.ipc.read_schema(pa.py_buffer(fmt.options))
+    assert set(opt_schema.names) == {"delimiter", "null_string", "skip_rows", "on_error"}
+    assert opt_schema.field("null_string").metadata[b"vgi_doc"] == b"Token parsed as SQL NULL"
+
+
+def test_bind_request_copy_from_wire_roundtrip() -> None:
+    """copy_from survives a BindRequest wire round-trip."""
+    cf = CopyFromContext(format="example_lines", file_path="/p", expected_schema=EXPECTED)
+    br = BindRequest(
+        function_name="h",
+        arguments=Arguments(named={"null_string": pa.scalar("NA")}),
+        function_type=FunctionType.TABLE,
+        copy_from=cf,
+    )
+    restored = BindRequest.deserialize_from_bytes(br.serialize_to_bytes())
+    assert restored.copy_from is not None
+    assert restored.copy_from.format == "example_lines"
+    assert restored.copy_from.file_path == "/p"
+    assert restored.copy_from.expected_schema.equals(EXPECTED)

vgi_python-0.8.8/tests/test_copy_to_function.py

@@ -0,0 +1,120 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Worker-side unit tests for CopyToFunction and the example_lines_out format."""
+
+from __future__ import annotations
+
+import tempfile
+import types
+
+import pyarrow as pa
+
+from vgi._test_fixtures.copy_to import ExampleLinesCopyToArgs, ExampleLinesCopyToFunction
+from vgi._test_fixtures.worker import ExampleCatalog
+
+SCHEMA = pa.schema([("a", pa.int64()), ("b", pa.string())])
+
+
+class _Store:
+    """Minimal in-memory BoundStorage stub (append + ordered log scan)."""
+
+    def __init__(self) -> None:
+        self.log: list[tuple[int, bytes]] = []
+
+    def state_append(self, ns: bytes, key: bytes, val: bytes) -> None:
+        self.log.append((len(self.log), val))
+
+    def state_log_scan(self, ns: bytes, key: bytes, after_id: int = -1, limit: int | None = None) -> list:
+        rows = [(i, v) for (i, v) in self.log if i > after_id]
+        return rows if limit is None else rows[:limit]
+
+
+def _tmp_path() -> str:
+    with tempfile.NamedTemporaryFile("w", suffix=".txt", delete=False) as fh:
+        return fh.name
+
+
+def _read(path: str) -> str:
+    with open(path, encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _params(store: _Store) -> types.SimpleNamespace:
+    bind_call = types.SimpleNamespace(input_schema=SCHEMA)
+    init_call = types.SimpleNamespace(bind_call=bind_call)
+    return types.SimpleNamespace(storage=store, init_call=init_call, execution_id=b"x", args=None)
+
+
+def test_write_then_close_round_trips_with_null_string() -> None:
+    """write() buffers shards; close() concatenates them to a delimited file."""
+    store = _Store()
+    params = _params(store)
+    opts = ExampleLinesCopyToArgs(null_string="NA")
+    out_name = _tmp_path()
+
+    ExampleLinesCopyToFunction.write(
+        batch=pa.record_batch({"a": [1, 2], "b": ["foo", None]}, schema=SCHEMA),
+        options=opts,
+        file_path=out_name,
+        params=params,
+    )
+    ExampleLinesCopyToFunction.write(
+        batch=pa.record_batch({"a": [3], "b": ["baz"]}, schema=SCHEMA),
+        options=opts,
+        file_path=out_name,
+        params=params,
+    )
+    n = ExampleLinesCopyToFunction.close(options=opts, file_path=out_name, params=params)
+    assert n == 3
+    assert _read(out_name) == "1,foo\n2,NA\n3,baz\n"
+
+
+def test_close_honors_delimiter_and_header() -> None:
+    """Non-default delimiter + header row are applied."""
+    store = _Store()
+    params = _params(store)
+    opts = ExampleLinesCopyToArgs(null_string="NA", delimiter="|", header=True)
+    out_name = _tmp_path()
+    ExampleLinesCopyToFunction.write(
+        batch=pa.record_batch({"a": [1], "b": ["x"]}, schema=SCHEMA),
+        options=opts,
+        file_path=out_name,
+        params=params,
+    )
+    n = ExampleLinesCopyToFunction.close(options=opts, file_path=out_name, params=params)
+    assert n == 1
+    assert _read(out_name) == "a|b\n1|x\n"
+
+
+def test_close_empty_input_with_header_writes_header_only() -> None:
+    """An empty COPY with header=true still emits the header row (0 data rows)."""
+    store = _Store()
+    params = _params(store)
+    out_name = _tmp_path()
+    n = ExampleLinesCopyToFunction.close(
+        options=ExampleLinesCopyToArgs(null_string="NA", header=True),
+        file_path=out_name,
+        params=params,
+    )
+    assert n == 0
+    assert _read(out_name) == "a,b\n"
+
+
+def test_catalog_advertises_copy_to_format() -> None:
+    """The example catalog advertises example_lines_out with direction='to'."""
+    formats = ExampleCatalog().copy_from_formats(attach_opaque_data=b"", transaction_opaque_data=None)
+    by = {(f.direction, f.format_name): f for f in formats}
+    assert ("to", "example_lines_out") in by
+    fmt = by[("to", "example_lines_out")]
+    assert fmt.handler == "example_lines_writer"
+    assert fmt.comment == "Toy delimited-text writer for tests"
+    assert fmt.tags.get("category") == "copy_to"
+    opt_schema = pa.ipc.read_schema(pa.py_buffer(fmt.options))
+    assert set(opt_schema.names) == {
+        "delimiter",
+        "null_string",
+        "header",
+        "header_repeat",
+        "on_exists",
+        "fail_on_value",
+    }

vgi_python-0.8.8/tests/test_resolved_secrets.py

@@ -0,0 +1,61 @@
+"""Unit tests for ResolvedSecrets type- and scope-aware selection."""
+
+from vgi.table_function import ResolvedSecrets
+
+
+def _secrets() -> ResolvedSecrets:
+    # Values are plain strings here; ResolvedSecrets also accepts pyarrow Scalars
+    # (it calls .as_py() when present).
+    return ResolvedSecrets(
+        {
+            "my_s3": {"type": "s3", "key_id": "AAA", "scope": "s3://bucket-a"},
+            "my_s3_b": {
+                "type": "s3",
+                "key_id": "BBB",
+                "scope": "s3://bucket-b\ns3://bucket-b2",
+            },
+            "my_gcs": {"type": "gcs", "key_id": "G"},
+        }
+    )
+
+
+def test_type_aware() -> None:
+    """Type-aware accessors find/identify secrets by type."""
+    s = _secrets()
+    assert s.secret_type("my_s3") == "s3"
+    assert s.secret_type("my_gcs") == "gcs"
+    assert len(s.of_type("s3")) == 2
+    assert len(s.of_type("gcs")) == 1
+    assert s.of_type("azure") == []
+
+
+def test_for_scope_of_type_per_bucket() -> None:
+    """Per-bucket scope selection picks the right s3 secret."""
+    s = _secrets()
+    assert s.for_scope_of_type("s3://bucket-a/x.dat", "s3")["key_id"] == "AAA"
+    assert s.for_scope_of_type("s3://bucket-b2/y.dat", "s3")["key_id"] == "BBB"
+    assert s.field_for("s3://bucket-a/x.dat", "key_id") == "AAA"
+
+
+def test_longest_prefix_and_fallback() -> None:
+    """Longest scope prefix wins; unscoped is the fallback."""
+    s = ResolvedSecrets(
+        {
+            "broad": {"type": "s3", "key_id": "broad", "scope": "s3://bucket"},
+            "narrow": {"type": "s3", "key_id": "narrow", "scope": "s3://bucket/data"},
+        }
+    )
+    assert s.for_scope("s3://bucket/data/x.dat")["key_id"] == "narrow"
+    assert s.for_scope("s3://bucket/other/x.dat")["key_id"] == "broad"
+
+    unscoped = ResolvedSecrets({"only": {"type": "s3", "key_id": "only"}})
+    assert unscoped.for_scope("s3://any/x")["key_id"] == "only"
+
+    assert s.for_scope("s3://nope/x") is None
+
+
+def test_dict_access_still_works() -> None:
+    """ResolvedSecrets keeps plain dict access."""
+    s = _secrets()
+    assert s["my_s3"]["key_id"] == "AAA"
+    assert s.get("missing") is None

vgi_python-0.8.8/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.8}/uv.lock

@@ -2250,7 +2250,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.8.5"
+version = "0.8.8"
 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.8/vgi/_test_fixtures/copy_from.py

@@ -0,0 +1,99 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Fixture ``COPY ... FROM`` format reader for VGI integration tests.
+
+``ExampleLinesCopyFromFunction`` registers the SQL format ``example_lines`` — a
+toy delimited-text reader. It exercises the full COPY-FROM path plus the option
+machinery: a defaulted option (``delimiter``), an ``INTEGER`` option with a range
+constraint (``skip_rows``), a required option (``null_string``), and an
+enum/``choices`` option (``on_error``).
+
+Usage::
+
+    CREATE TABLE t (a INTEGER, b VARCHAR);
+    COPY t FROM '/path/data.txt' (FORMAT example_lines, null_string 'NA');
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Annotated, ClassVar
+
+import pyarrow as pa
+
+from vgi.arguments import Arg
+from vgi.copy_from_function import CopyFromFunction
+
+if TYPE_CHECKING:
+    from vgi_rpc.rpc import OutputCollector
+
+    from vgi.table_function import ProcessParams
+
+__all__ = ["ExampleLinesCopyFromFunction"]
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class ExampleLinesCopyFromArgs:
+    """Options for the ``example_lines`` COPY format."""
+
+    null_string: Annotated[str, Arg("null_string", doc="Token parsed as SQL NULL")]
+    delimiter: Annotated[str, Arg("delimiter", default=",", doc="Field separator")] = ","
+    skip_rows: Annotated[int, Arg("skip_rows", default=0, ge=0, doc="Leading lines to skip before data")] = 0
+    on_error: Annotated[
+        str,
+        Arg(
+            "on_error",
+            default="fail",
+            choices=["fail", "skip"],
+            doc="Behavior on a row whose column count does not match the target",
+        ),
+    ] = "fail"
+
+
+class ExampleLinesCopyFromFunction(CopyFromFunction[ExampleLinesCopyFromArgs]):
+    """Toy delimited-text ``COPY ... FROM`` reader (test fixture)."""
+
+    COPY_FROM_FORMAT: ClassVar[str] = "example_lines"
+    COPY_FROM_COMMENT: ClassVar[str | None] = "Toy delimited-text reader for tests"
+
+    class Meta:
+        name = "example_lines_copy_reader"
+        description = "Read a delimited text file into the COPY target table"
+        categories = ["copy", "test"]
+        tags = {"category": "copy_from", "stability": "test"}
+
+    @classmethod
+    def read(
+        cls,
+        *,
+        path: str,
+        options: ExampleLinesCopyFromArgs,
+        expected_schema: pa.Schema,
+        params: ProcessParams[ExampleLinesCopyFromArgs],
+        out: OutputCollector,
+    ) -> None:
+        """Parse ``path`` line-by-line and emit one batch matching ``expected_schema``."""
+        with open(path, encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+        lines = lines[options.skip_rows :]
+
+        ncols = len(expected_schema)
+        rows: list[list[str]] = []
+        for line in lines:
+            if line == "":
+                continue
+            cells = line.split(options.delimiter)
+            if len(cells) != ncols:
+                if options.on_error == "skip":
+                    continue
+                raise ValueError(f"example_lines: row has {len(cells)} fields, expected {ncols}: {line!r}")
+            rows.append(cells)
+
+        # Column-major string arrays, NULL where the cell equals null_string,
+        # then cast each column to the target type (DuckDB inserts no cast).
+        columns = list(zip(*rows)) if rows else [() for _ in range(ncols)]
+        arrays = []
+        for idx, field in enumerate(expected_schema):
+            raw = [None if v == options.null_string else v for v in columns[idx]]
+            arrays.append(pa.array(raw, type=pa.string()).cast(field.type))
+        out.emit(pa.RecordBatch.from_arrays(arrays, schema=expected_schema))