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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.8.7
+Version: 0.8.9
 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
@@ -172,7 +172,6 @@ Requires-Dist: duckdb>=1.5.3; extra == 'dev'
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: numpy>=2.4.1; extra == 'dev'
 Requires-Dist: pyarrow-stubs; extra == 'dev'
-Requires-Dist: pydoclint; extra == 'dev'
 Requires-Dist: pymssql>=2.3.0; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'

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

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.8.7"
+version = "0.8.9"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [
@@ -77,7 +77,11 @@ dev = [
     "duckdb>=1.5.3",
     "mypy",
     "pyarrow-stubs",
-    "pydoclint",
+    # pydoclint is intentionally NOT a project dependency: it pulls
+    # docstring-parser-fork, which clobbers the canonical docstring-parser
+    # (a vgi-rpc dependency) in the shared `docstring_parser` namespace,
+    # non-deterministically breaking imports. tests/test_docstrings.py runs it
+    # in an isolated env via `uvx pydoclint` instead.
     "pytest",
     "pytest-cov",
     "pytest-examples",
@@ -142,7 +146,9 @@ quote-style = "double"
 # Docstring consistency gate (complements ruff's `D` rules, which only check
 # docstring *shape*, not whether documented args/attributes match the code).
 # Enforced families: DOC001 (parse), DOC101/102/103 (arg<->signature), DOC4xx
-# (yields), DOC60x (dataclass attributes). Run via `uv run pydoclint vgi/`.
+# (yields), DOC60x (dataclass attributes). pydoclint is NOT a project dependency
+# (it pulls docstring-parser-fork, which clobbers vgi-rpc's docstring-parser);
+# run it isolated: `uvx --python $(which python) pydoclint --config pyproject.toml vgi/`.
 style = "google"
 # We keep types in signatures, not docstrings (Google style) — so don't ask for
 # them in docstrings, and don't try to match return/yield *types* against prose.
@@ -162,7 +168,7 @@ allow_init_docstring = true
 # No baseline: vgi/ is fully clean under this config, so the gate enforces
 # every in-scope violation with no grandfathered exceptions. If a future change
 # needs to defer cleanup, freeze the current state and re-add `baseline`:
-#   uv run pydoclint --generate-baseline=True --baseline=.pydoclint-baseline vgi/
+#   uvx pydoclint --config pyproject.toml --generate-baseline=True --baseline=.pydoclint-baseline vgi/
 
 [tool.mypy]
 python_version = "3.13"

{vgi_python-0.8.7 → vgi_python-0.8.9}/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.9/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.9/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.9/tests/test_docstrings.py

@@ -0,0 +1,65 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Docstring-consistency gate.
+
+Runs pydoclint over the ``vgi/`` package as part of the test suite. pydoclint
+complements ruff's ``D`` rules: ruff checks docstring *shape*, while pydoclint
+verifies that documented arguments, return values, yields, and dataclass
+attributes actually match the code. Configuration lives in ``[tool.pydoclint]``
+in ``pyproject.toml`` — this test invokes the same CLI, so there is no
+duplicated rule set.
+
+pydoclint runs through ``uvx`` (an isolated, ephemeral environment) rather than
+as a project dependency. It requires ``docstring-parser-fork`` while ``vgi-rpc``
+(a runtime dependency) requires the upstream ``docstring-parser``; both own the
+``docstring_parser`` import namespace, so installing pydoclint into the project
+env clobbers it non-deterministically and breaks unrelated imports (e.g.
+``conftest`` collection). Running via uvx keeps the fork out of the project tree.
+"""
+
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_REPO_ROOT = Path(__file__).resolve().parents[1]
+
+# A real violation line looks like ``    42: DOC101: ...``. If pydoclint exits
+# non-zero without emitting any such code, it failed to *run* rather than finding
+# violations.
+_VIOLATION_RE = re.compile(r"\bDOC\d{3}\b")
+
+
+def test_pydoclint_clean() -> None:
+    """``vgi/`` must pass the pydoclint docstring gate (config in pyproject.toml)."""
+    uvx = shutil.which("uvx") or shutil.which("uv")
+    if uvx is None:  # pragma: no cover - uv is always present in dev/CI
+        pytest.skip("uv/uvx is not available to run pydoclint")
+
+    # `uvx pydoclint ...` == `uv tool run pydoclint ...`; both run pydoclint in an
+    # isolated env so docstring-parser-fork never enters the project tree.
+    # Pin the ephemeral env to *this* interpreter (``--python sys.executable``):
+    # pydoclint parses with its own runtime's AST, so it must run on a Python new
+    # enough for the repo's syntax (PEP 695 generics need 3.12+); uvx's default
+    # interpreter may be older and would report spurious DOC002 syntax errors.
+    base = [uvx] if Path(uvx).name == "uvx" else [uvx, "tool", "run"]
+    cmd = [*base, "--python", sys.executable, "pydoclint", "--config", "pyproject.toml", "vgi/"]
+    result = subprocess.run(cmd, cwd=_REPO_ROOT, capture_output=True, text=True)
+    output = result.stdout + result.stderr
+
+    if result.returncode == 0:
+        return
+
+    if not _VIOLATION_RE.search(output):  # pragma: no cover - env-dependent (e.g. offline uvx)
+        pytest.skip(f"pydoclint could not run via uvx:\n{output}")
+
+    pytest.fail(
+        "pydoclint found docstring violations:\n\n"
+        f"{output}\n"
+        "Fix the docstrings, or run `uvx pydoclint --config pyproject.toml "
+        "--generate-baseline=True --baseline=.pydoclint-baseline vgi/` "
+        "to defer them (see [tool.pydoclint] in pyproject.toml)."
+    )

vgi_python-0.8.9/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.7 → vgi_python-0.8.9}/uv.lock

@@ -516,15 +516,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a7/5f/ed01f9a3cdffbd5a008556fc7b2a08ddb1cc6ace7effa7340604b1d16699/docstring_parser-0.18.0-py3-none-any.whl", hash = "sha256:b3fcbed555c47d8479be0796ef7e19c2670d428d72e96da63f3a40122860374b", size = 22484, upload-time = "2026-04-14T04:09:18.638Z" },
 ]
 
-[[package]]
-name = "docstring-parser-fork"
-version = "0.0.14"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/66/bf/27f9cab2f0cd1d17a4420572088bbc19f36d726fbcf165edf226a8926dbc/docstring_parser_fork-0.0.14.tar.gz", hash = "sha256:a2743a63d8d36c09650594f7b4ab5b2758fee8629dcf794d1b221b23179baa5c", size = 34551, upload-time = "2025-09-07T17:27:38.272Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/bf/50/98b146aea0f1cd7531d25f12bea69fa9ce8d1662124f93fb30dc4511b65e/docstring_parser_fork-0.0.14-py3-none-any.whl", hash = "sha256:4c544f234ef2cc2749a3df32b70c437d77888b1099143a1ad5454452c574b9af", size = 43063, upload-time = "2025-09-07T17:27:37.012Z" },
-]
-
 [[package]]
 name = "duckdb"
 version = "1.5.4"
@@ -1657,19 +1648,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f6/d2/42dd53d0a85c27606f316d3aa5d2869c4e8470a5ed6dec30e4a1abe19192/pydantic_core-2.46.4-cp314-cp314t-win_arm64.whl", hash = "sha256:4fcbe087dbc2068af7eda3aa87634eba216dbda64d1ae73c8684b621d33f6596", size = 2017325, upload-time = "2026-05-06T13:40:52.723Z" },
 ]
 
-[[package]]
-name = "pydoclint"
-version = "0.8.7"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "click" },
-    { name = "docstring-parser-fork" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/bf/2e/e4df6b0cbb281cb6cf355f5d90b8c66939c7f3cd799c075fab23e0983dfb/pydoclint-0.8.7.tar.gz", hash = "sha256:1ce5055dfdaf2bc3c999d3ffd5494556b903b7090bb5fadac90819107f90629b", size = 199793, upload-time = "2026-06-22T01:24:20.117Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/e9/d4/15fe5c3e66bbf3f60eb9c6ef7c2dca3931302f9acf317e65d70e7d8b338a/pydoclint-0.8.7-py3-none-any.whl", hash = "sha256:40f6b80e59129fe753f6a2f9edd76e4259c970eedc1ce3663adc43f54af439d3", size = 82963, upload-time = "2026-06-22T01:24:19.102Z" },
-]
-
 [[package]]
 name = "pygments"
 version = "2.20.0"
@@ -2250,7 +2228,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.8.7"
+version = "0.8.9"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -2272,7 +2250,6 @@ dev = [
     { name = "mypy" },
     { name = "numpy" },
     { name = "pyarrow-stubs" },
-    { name = "pydoclint" },
     { name = "pymssql" },
     { name = "pytest" },
     { name = "pytest-cov" },
@@ -2346,7 +2323,6 @@ requires-dist = [
     { name = "platformdirs" },
     { name = "pyarrow" },
     { name = "pyarrow-stubs", marker = "extra == 'dev'" },
-    { name = "pydoclint", marker = "extra == 'dev'" },
     { name = "pymssql", marker = "extra == 'azure'", specifier = ">=2.3.0" },
     { name = "pytest", marker = "extra == 'dev'" },
     { name = "pytest-cov", marker = "extra == 'dev'" },

vgi_python-0.8.9/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, strict=True)) 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))