cleanups

Author: rustyconover

CLAUDE.md

@@ -23,6 +23,14 @@ uv run coverage html      # Generate HTML report in htmlcov/
 uv run ruff check --fix . && uv run ruff format . && uv run mypy vgi/
 ```
 
+Before running `pytest`, you must run ruff's check and fix commands, otherwise fixing problems
+takes longer:
+
+```bash
+uv run ruff check --fix . && uv run ruff format .
+```
+
+
 ## Project Overview
 
 VGI (Vector Gateway Interface) provides an Apache Arrow-based protocol for connecting DuckDB to external programs. It enables user-defined functions to run in separate processes, communicating via stdin/stdout using Arrow IPC streaming.
@@ -74,7 +82,7 @@ vgi/
   __init__.py              # Package exports
   function.py              # Invocation, OutputSpec, Arguments, FunctionType
   scalar_function.py       # ScalarFunction, ScalarFunctionGenerator
-  table_function.py        # TableFunctionGenerator, CardinalityInfo, Output
+  table_function.py        # TableFunctionGenerator, TableCardinality, Output
   table_in_out_function.py # TableInOutFunction, TableInOutGeneratorFunction
   metadata.py              # Function metadata for introspection
   schema_utils.py          # Schema builder helpers (schema, schema_like)

docs/generator-api.md

@@ -79,7 +79,7 @@ Use `TableFunctionGenerator` when you need to generate data without receiving in
 ```python
 import pyarrow as pa
 from vgi import TableFunctionGenerator, Output, Arg
-from vgi.table_function import CardinalityInfo
+from vgi.table_function import TableCardinality
 
 class MyTableFunction(TableFunctionGenerator):
     """Generate data without input."""
@@ -95,9 +95,9 @@ class MyTableFunction(TableFunctionGenerator):
     def output_schema(self) -> pa.Schema:
         return pa.schema([("value", pa.int64())])
 
-    def cardinality(self) -> CardinalityInfo:
+    def cardinality(self) -> TableCardinality:
         """Optional: provide row count estimate."""
-        return CardinalityInfo(estimate=self.count, max=self.count)
+        return TableCardinality(estimate=self.count, max=self.count)
 
     def process(self):
         """Generate output batches."""

tests/table/test_function.py

@@ -9,7 +9,7 @@
 from tests.conftest import make_invocation, make_schema
 from vgi.function import Arguments
 from vgi.table_function import (
-    CardinalityInfo,
+    TableCardinality,
     Output,
     OutputGenerator,
     TableFunctionGenerator,
@@ -206,8 +206,8 @@ class CardinalityFunction(TableFunctionGenerator):
             def output_schema(self) -> pa.Schema:
                 return make_schema([pa.field("x", pa.int64())])
 
-            def cardinality(self) -> CardinalityInfo:
-                return CardinalityInfo(estimate=100, max=1000)
+            def cardinality(self) -> TableCardinality:
+                return TableCardinality(estimate=100, max=1000)
 
         invocation = make_invocation()
         func = CardinalityFunction(invocation=invocation, logger=structlog.get_logger())

tests/test_protocol_classes.py

@@ -19,7 +19,7 @@
 )
 from vgi.log import Level, Message
 from vgi.table_function import (
-    CardinalityInfo,
+    TableCardinality,
     OutputSpec,
     TableFunctionInitInput,
 )
@@ -477,39 +477,39 @@ def test_repr(self) -> None:
         assert "test message" in repr_str
 
 
-class TestCardinalityInfo:
-    """Tests for CardinalityInfo dataclass."""
+class TestTableCardinality:
+    """Tests for TableCardinality dataclass."""
 
     def test_basic_creation(self) -> None:
-        """CardinalityInfo should store estimate and max values."""
-        info = CardinalityInfo(estimate=100, max=1000)
+        """TableCardinality should store estimate and max values."""
+        info = TableCardinality(estimate=100, max=1000)
         assert info.estimate == 100
         assert info.max == 1000
 
     def test_null_values(self) -> None:
-        """CardinalityInfo should allow null estimate and max."""
-        info = CardinalityInfo(estimate=None, max=None)
+        """TableCardinality should allow null estimate and max."""
+        info = TableCardinality(estimate=None, max=None)
         assert info.estimate is None
         assert info.max is None
 
     def test_partial_values(self) -> None:
-        """CardinalityInfo should allow partial information."""
-        estimate_only = CardinalityInfo(estimate=50, max=None)
+        """TableCardinality should allow partial information."""
+        estimate_only = TableCardinality(estimate=50, max=None)
         assert estimate_only.estimate == 50
         assert estimate_only.max is None
 
-        max_only = CardinalityInfo(estimate=None, max=100)
+        max_only = TableCardinality(estimate=None, max=100)
         assert max_only.estimate is None
         assert max_only.max == 100
 
     def test_exact_cardinality(self) -> None:
-        """CardinalityInfo with equal estimate and max indicates exact count."""
-        exact = CardinalityInfo(estimate=1, max=1)
+        """TableCardinality with equal estimate and max indicates exact count."""
+        exact = TableCardinality(estimate=1, max=1)
         assert exact.estimate == exact.max == 1
 
     def test_frozen(self) -> None:
-        """CardinalityInfo should be immutable (frozen dataclass)."""
-        info = CardinalityInfo(estimate=100, max=1000)
+        """TableCardinality should be immutable (frozen dataclass)."""
+        info = TableCardinality(estimate=100, max=1000)
         with pytest.raises(AttributeError):
             info.estimate = 200  # type: ignore[misc]
 
@@ -573,7 +573,7 @@ def test_serialization_with_cardinality(self) -> None:
             output_schema=make_schema([pa.field("col1", pa.int64())]),
             max_processes=4,
             invocation_id=b"test-id",
-            cardinality=CardinalityInfo(estimate=100, max=1000),
+            cardinality=TableCardinality(estimate=100, max=1000),
         )
 
         serialized = spec.serialize()
@@ -598,7 +598,7 @@ def test_serialize_schema_includes_cardinality_fields(self) -> None:
             output_schema=make_schema([pa.field("col1", pa.int64())]),
             max_processes=1,
             invocation_id=b"test-id",
-            cardinality=CardinalityInfo(estimate=50, max=100),
+            cardinality=TableCardinality(estimate=50, max=100),
         )
 
         schema = spec.serialize_schema()
@@ -611,7 +611,7 @@ def test_serialize_dict_includes_cardinality_values(self) -> None:
             output_schema=make_schema([pa.field("col1", pa.int64())]),
             max_processes=1,
             invocation_id=b"test-id",
-            cardinality=CardinalityInfo(estimate=50, max=100),
+            cardinality=TableCardinality(estimate=50, max=100),
         )
 
         data = spec.serialize_dict()

vgi/__init__.py

@@ -107,7 +107,7 @@ class Meta:
     vgi.client      - Client class for invoking functions on workers
     vgi.log         - Level and Message for function diagnostics
     vgi.ipc_utils   - RecordBatchState for distributed function state
-    vgi.table_function - CardinalityInfo for row count hints
+    vgi.table_function - TableCardinality for row count hints
 
 CLASS HIERARCHY
 ---------------
@@ -148,12 +148,12 @@ class Meta:
     functions_to_arrow,
 )
 from vgi.scalar_function import (
+    RowCountMismatchError,
     ScalarFunction,
     ScalarFunctionGenerator,
     ScalarOutputGenerator,
 )
 from vgi.schema_utils import schema, schema_like
-from vgi.table_function import RowCountMismatchError
 from vgi.table_in_out_function import (
     Output,
     OutputGenerator,

vgi/examples/table.py

@@ -23,7 +23,7 @@
 from vgi.log import Level, Message
 from vgi.metadata import FunctionExample
 from vgi.table_function import (
-    CardinalityInfo,
+    TableCardinality,
     Output,
     OutputGenerator,
     TableFunctionGenerator,
@@ -90,9 +90,9 @@ def output_schema(self) -> pa.Schema:
         """Return output schema with single integer column."""
         return pa.schema([pa.field("n", pa.int64())])
 
-    def cardinality(self) -> CardinalityInfo:
+    def cardinality(self) -> TableCardinality:
         """Return exact cardinality since we know the count."""
-        return CardinalityInfo(estimate=self.count, max=self.count)
+        return TableCardinality(estimate=self.count, max=self.count)
 
     def process(self) -> OutputGenerator:
         """Generate the sequence in batches."""
@@ -159,13 +159,13 @@ def output_schema(self) -> pa.Schema:
         """Return output schema with single integer column."""
         return pa.schema([pa.field("value", pa.int64())])
 
-    def cardinality(self) -> CardinalityInfo:
+    def cardinality(self) -> TableCardinality:
         """Return cardinality based on range parameters."""
         if self.end <= self.start:
             count = 0
         else:
             count = (self.end - self.start + self.step - 1) // self.step
-        return CardinalityInfo(estimate=count, max=count)
+        return TableCardinality(estimate=count, max=count)
 
     def process(self) -> OutputGenerator:
         """Generate the range in batches."""
@@ -232,9 +232,9 @@ def output_schema(self) -> pa.Schema:
         """Return output schema with single integer column."""
         return pa.schema([pa.field("value", pa.int64())])
 
-    def cardinality(self) -> CardinalityInfo:
+    def cardinality(self) -> TableCardinality:
         """Return cardinality of exactly one row."""
-        return CardinalityInfo(estimate=1, max=1)
+        return TableCardinality(estimate=1, max=1)
 
     def process(self) -> OutputGenerator:
         """Emit a single batch with one row."""
@@ -298,9 +298,9 @@ def output_schema(self) -> pa.Schema:
         ]
         return pa.schema(fields)
 
-    def cardinality(self) -> CardinalityInfo:
+    def cardinality(self) -> TableCardinality:
         """Return cardinality estimate."""
-        return CardinalityInfo(estimate=self.count, max=self.count)
+        return TableCardinality(estimate=self.count, max=self.count)
 
     def setup(self) -> None:
         """Initialize random number generator with seed."""
@@ -465,13 +465,13 @@ def output_schema(self) -> pa.Schema:
         """Return output schema with single integer column."""
         return pa.schema([pa.field("value", pa.int64())])
 
-    def cardinality(self) -> CardinalityInfo:
+    def cardinality(self) -> TableCardinality:
         """Return cardinality estimate.
 
         Since work is distributed dynamically via queue, we can only provide
         the total count estimate, not per-worker estimates.
         """
-        return CardinalityInfo(estimate=self.count, max=self.count)
+        return TableCardinality(estimate=self.count, max=self.count)
 
     def perform_init(self, init_input: pa.RecordBatch) -> InitResult:
         """Populate the work queue with range chunks."""
@@ -582,9 +582,9 @@ def output_schema(self) -> pa.Schema:
         """Return the projected schema based on init_data."""
         return self.apply_projection(self.FULL_SCHEMA)
 
-    def cardinality(self) -> CardinalityInfo:
+    def cardinality(self) -> TableCardinality:
         """Return exact cardinality since we know the count."""
-        return CardinalityInfo(estimate=self.count, max=self.count)
+        return TableCardinality(estimate=self.count, max=self.count)
 
     def _get_projected_column_indices(self) -> list[int]:
         """Get the column indices to generate.

vgi/examples/table_in_out.py

@@ -34,7 +34,7 @@
 from vgi.ipc_utils import RecordBatchState
 from vgi.log import Level, Message
 from vgi.metadata import FunctionExample
-from vgi.table_function import CardinalityInfo
+from vgi.table_function import TableCardinality
 from vgi.table_in_out_function import (
     Output,
     OutputGenerator,
@@ -357,9 +357,9 @@ class Meta:
 
     data: TableInput = Arg[TableInput](0, doc="Input table with numeric columns")  # type: ignore[assignment]
 
-    def cardinality(self) -> CardinalityInfo | None:
+    def cardinality(self) -> TableCardinality | None:
         """Return cardinality estimate of exactly 1 row."""
-        return CardinalityInfo(estimate=1, max=1)
+        return TableCardinality(estimate=1, max=1)
 
     def __init__(
         self, invocation: Invocation, logger: structlog.stdlib.BoundLogger
@@ -676,9 +676,9 @@ def __init__(
         super().__init__(invocation=invocation, logger=logger)
         self.sums: dict[str, pa.Scalar[Any]] = {}
 
-    def cardinality(self) -> CardinalityInfo | None:
+    def cardinality(self) -> TableCardinality | None:
         """Return cardinality estimate of exactly 1 row."""
-        return CardinalityInfo(estimate=1, max=1)
+        return TableCardinality(estimate=1, max=1)
 
     @property
     def output_schema(self) -> pa.Schema: