worker: unwrap sealed attach envelope on all bind-call paths; fix lint debt

Unwrap attach_opaque_data to plaintext on table_function_cardinality,
table_function_statistics, dynamic_to_string, and the streaming init
path so function bodies always see the unsealed value, matching the
existing bind() behavior. ts_client now emits a TS property as optional
iff the field is wire-nullable, not merely Python-defaulted.

Also clears the repo's standing ruff debt: shard_key docstring args on
FunctionStorage protocol methods, D205/D400/D401 docstring reflows,
test-method docstrings, an F402 loop-var shadow, and E501 wraps of the
repeated stateful-catalog warning string.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: rustyconover

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi"
-version = "0.7.4"
+version = "0.8.0"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 requires-python = ">=3.13"

tests/test_filter_pushdown_extension.py

@@ -51,6 +51,7 @@ class TestBoolColumnBool8Literal:
     """
 
     def test_eq_true(self) -> None:
+        """EQ against a bool8 literal matches the plain-bool column."""
         batch = _batch_with_bool("flag", [True, False, None, True])
         f = ConstantFilter(
             column_name="flag",
@@ -62,6 +63,7 @@ def test_eq_true(self) -> None:
         assert result.to_pylist() == [True, False, None, True]
 
     def test_eq_false(self) -> None:
+        """EQ against a false bool8 literal."""
         batch = _batch_with_bool("flag", [True, False, None, True])
         f = ConstantFilter(
             column_name="flag",
@@ -72,6 +74,7 @@ def test_eq_false(self) -> None:
         assert f.evaluate(batch).to_pylist() == [False, True, None, False]
 
     def test_ne_true(self) -> None:
+        """NE against a bool8 literal."""
         batch = _batch_with_bool("flag", [True, False, None, True])
         f = ConstantFilter(
             column_name="flag",
@@ -95,6 +98,7 @@ class TestBool8ColumnBool8Literal:
     """
 
     def test_eq_true(self) -> None:
+        """EQ with bool8 on both sides of the kernel."""
         batch = _batch_with_bool8("flag", [True, False, None, True])
         f = ConstantFilter(
             column_name="flag",
@@ -105,6 +109,7 @@ def test_eq_true(self) -> None:
         assert f.evaluate(batch).to_pylist() == [True, False, None, True]
 
     def test_eq_false(self) -> None:
+        """EQ against a false literal with bool8 on both sides."""
         batch = _batch_with_bool8("flag", [True, False, None, True])
         f = ConstantFilter(
             column_name="flag",
@@ -128,11 +133,13 @@ class TestPlainTypesUnchanged:
     """
 
     def test_int32_eq(self) -> None:
+        """Plain int32 EQ flows through normalisation unchanged."""
         batch = pa.RecordBatch.from_pydict({"n": pa.array([1, 2, 3, 4], type=pa.int32())})
         f = ConstantFilter(column_name="n", column_index=0, op=ComparisonOp.EQ, value=pa.scalar(2, type=pa.int32()))
         assert f.evaluate(batch).to_pylist() == [False, True, False, False]
 
     def test_string_eq(self) -> None:
+        """Plain string EQ flows through normalisation unchanged."""
         batch = pa.RecordBatch.from_pydict({"s": ["a", "b", "c"]})
         f = ConstantFilter(column_name="s", column_index=0, op=ComparisonOp.EQ, value=pa.scalar("b"))
         assert f.evaluate(batch).to_pylist() == [False, True, False]
@@ -158,6 +165,7 @@ class TestInFilterExtension:
     """
 
     def test_in_bool_with_bool8_values(self) -> None:
+        """IN with bool8 values against a plain-bool column."""
         batch = _batch_with_bool("flag", [True, False, None, True])
         # Build the values array as a bool8 extension array
         storage = pa.array([1], type=pa.int8())
@@ -173,11 +181,14 @@ def test_in_bool_with_bool8_values(self) -> None:
 
 
 class TestPlainLiteralBool8Column:
-    """Defensive: if some future code path emits a plain bool literal but
-    the column happens to be bool8, normalisation should still align them.
+    """Defensive symmetry check: plain bool literal against a bool8 column.
+
+    If some future code path emits a plain bool literal but the column
+    happens to be bool8, normalisation should still align them.
     """
 
     def test_plain_bool_literal_bool8_column(self) -> None:
+        """Plain bool literal against a bool8 column."""
         batch = _batch_with_bool8("flag", [True, False, None, True])
         f = ConstantFilter(
             column_name="flag",
@@ -197,8 +208,10 @@ def test_plain_bool_literal_bool8_column(self) -> None:
 
 
 def test_pyarrow_kernel_gap_still_present() -> None:
-    """Documents the underlying PyArrow gap. If this passes in a future
-    PyArrow release the normalisation helper is over-defensive but harmless.
+    """Document the underlying PyArrow gap.
+
+    If this passes in a future PyArrow release the normalisation helper
+    is over-defensive but harmless.
     """
     import pyarrow.compute as pc
 
@@ -245,6 +258,7 @@ class TestUuidExtension:
     ]
 
     def test_eq(self) -> None:
+        """EQ with arrow.uuid on both sides."""
         batch = pa.RecordBatch.from_arrays([_uuid_array(self.UUIDS)], names=["id"])
         f = ConstantFilter(
             column_name="id",
@@ -255,6 +269,7 @@ def test_eq(self) -> None:
         assert f.evaluate(batch).to_pylist() == [False, True, None, False]
 
     def test_ne(self) -> None:
+        """NE with arrow.uuid on both sides."""
         batch = pa.RecordBatch.from_arrays([_uuid_array(self.UUIDS)], names=["id"])
         f = ConstantFilter(
             column_name="id",
@@ -265,6 +280,7 @@ def test_ne(self) -> None:
         assert f.evaluate(batch).to_pylist() == [True, False, None, True]
 
     def test_in(self) -> None:
+        """IN with an arrow.uuid values array."""
         batch = pa.RecordBatch.from_arrays([_uuid_array(self.UUIDS)], names=["id"])
         values = _uuid_array(
             [
@@ -282,8 +298,10 @@ def test_in(self) -> None:
 
 
 def test_pyarrow_interval_kernel_gap() -> None:
-    """PyArrow has no ``equal`` kernel for any of the interval types
-    (``month_day_nano_interval``, ``day_time_interval``, ``month_interval``).
+    """PyArrow has no ``equal`` kernel for any interval type.
+
+    The affected types are ``month_day_nano_interval``,
+    ``day_time_interval``, and ``month_interval``.
 
     This means a filter pushdown like ``WHERE col = INTERVAL '1 day'``
     cannot be evaluated on the worker side regardless of whether we strip

uv.lock

@@ -273,8 +273,10 @@ def window(
 
 
 class WindowSumBatchFunction(AggregateFunction[SumState]):
-    """Windowed running-sum that overrides ``window_batch`` to return a
-    pre-built ``pa.Array`` rather than a Python list.
+    """Windowed running-sum returning a pre-built ``pa.Array``.
+
+    Overrides ``window_batch`` to return a pre-built ``pa.Array`` rather
+    than a Python list.
 
     Functionally equivalent to :class:`WindowSumFunction`. The point of this
     fixture is to exercise the framework's polymorphic batch return: when

vgi/_test_fixtures/aggregate/window.py

@@ -476,11 +476,12 @@ def process(
 
 
 class BrokenReturningInsert(TableInOutGenerator[None, None]):
-    """Misbehaving INSERT handler: claims RETURNING support but always emits a
-    (count BIGINT) batch — same shape that triggered the original SIGSEGV in
-    the kafka worker. Used to verify the C++ extension's runtime schema
-    validator throws a clean IOException instead of crashing inside
-    ArrowToDuckDB.
+    """Misbehaving INSERT handler that lies about its RETURNING support.
+
+    Claims RETURNING support but always emits a (count BIGINT) batch —
+    same shape that triggered the original SIGSEGV in the kafka worker.
+    Used to verify the C++ extension's runtime schema validator throws a
+    clean IOException instead of crashing inside ArrowToDuckDB.
     """
 
     class Meta:

vgi/_test_fixtures/simple_writable.py

@@ -75,9 +75,11 @@ class _CountryPartitionedArgs:
 
 @dataclass(kw_only=True)
 class _CountryPartitionedState(ArrowSerializableDataclass):
-    """Per-worker cursor. ``current_country`` is set after the worker
-    pops a queue item; ``current_idx`` advances through emitted rows
-    until the per-country quota is reached, then it pops the next item.
+    """Per-worker cursor over countries.
+
+    ``current_country`` is set after the worker pops a queue item;
+    ``current_idx`` advances through emitted rows until the per-country
+    quota is reached, then it pops the next item.
     """
 
     current_country: str | None = None

vgi/_test_fixtures/table/partition_columns.py

@@ -420,7 +420,7 @@ def window_prepare(
         window_state: Any,
         params: ProcessParams[Any],
     ) -> Any:
-        """Optional hook: derive per-partition state for the window() loop.
+        """Derive per-partition state for the window() loop (optional hook).
 
         Called once per partition, after ``window_init`` (or after the state
         is rehydrated from storage on a cold reload), before any

vgi/aggregate_function.py

@@ -160,7 +160,8 @@ def catalog_version(
     )
     if is_stateful and catalog_name:
         click.echo(
-            "Warning: Using --catalog with a stateful catalog. Consider using --attach-opaque-data for session persistence.",
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
             err=True,
         )
     version = client.catalog_version(

vgi/client/cli_catalog.py

@@ -53,7 +53,8 @@ def schema_list(
     )
     if is_stateful and catalog_name:
         click.echo(
-            "Warning: Using --catalog with a stateful catalog. Consider using --attach-opaque-data for session persistence.",
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
             err=True,
         )
     for schema_info in client.schemas(
@@ -92,7 +93,8 @@ def schema_get(
     )
     if is_stateful and catalog_name:
         click.echo(
-            "Warning: Using --catalog with a stateful catalog. Consider using --attach-opaque-data for session persistence.",
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
             err=True,
         )
     schema_info = client.schema_get(
@@ -139,7 +141,8 @@ def schema_create(
     )
     if is_stateful and catalog_name:
         click.echo(
-            "Warning: Using --catalog with a stateful catalog. Consider using --attach-opaque-data for session persistence.",
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
             err=True,
         )
     tags_dict = parse_json_option(tags, "--tags")
@@ -186,7 +189,8 @@ def schema_drop(
     )
     if is_stateful and catalog_name:
         click.echo(
-            "Warning: Using --catalog with a stateful catalog. Consider using --attach-opaque-data for session persistence.",
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
             err=True,
         )
     client.schema_drop(
@@ -238,7 +242,8 @@ def schema_contents(
     )
     if is_stateful and catalog_name:
         click.echo(
-            "Warning: Using --catalog with a stateful catalog. Consider using --attach-opaque-data for session persistence.",
+            "Warning: Using --catalog with a stateful catalog. "
+            "Consider using --attach-opaque-data for session persistence.",
             err=True,
         )