chore: adopt vgi-python ruff/mypy/pydoclint code-quality config

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

Author: rustyconover

.github/workflows/ci.yml

@@ -56,7 +56,10 @@ jobs:
         run: uv run ruff check .
 
       - name: Type check (mypy)
-        run: uv run mypy vgi_vision/
+        run: uv run mypy vgi_vision/ vision_worker.py
+
+      - name: Docstring lint (pydoclint)
+        run: uv run pydoclint vgi_vision/ vision_worker.py
 
   # Resolve the latest published haybarn release once, so the whole matrix tests
   # the same version (and we never hardcode/pin it).

conftest.py

@@ -1,2 +1,5 @@
-# Presence of this file puts the repo root on sys.path so tests can
-# `import vision_worker` and `import vgi_vision`.
+"""Pytest configuration.
+
+Presence of this file puts the repo root on ``sys.path`` so tests can
+``import vision_worker`` and ``import vgi_vision``.
+"""

pyproject.toml

@@ -43,6 +43,7 @@ dev = [
     "pytest>=8",
     "ruff",
     "mypy",
+    "pydoclint",
 ]
 
 
@@ -54,12 +55,36 @@ build-backend = "hatchling.build"
 packages = ["vgi_vision"]
 
 [tool.ruff]
-line-length = 110
+line-length = 120
 target-version = "py313"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B"]
+select = ["E", "F", "I", "UP", "B", "SIM", "D"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pydoclint]
+style = "google"
+arg_type_hints_in_docstring = false
+check_return_types = false
+check_yield_types = false
+check_class_attributes = true
+skip_checking_raises = true
+allow_init_docstring = true
 
 [tool.mypy]
 python_version = "3.13"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = ["onnxruntime.*"]
 ignore_missing_imports = true

tests/test_client_integration.py

@@ -49,9 +49,7 @@ def test_top_label_scalar_end_to_end() -> None:
     # The image arrives as the (sole) input column; its BINARY type selects the
     # blob overload of top_label. No positional const arg is passed -- the column
     # is the argument (mirrors DuckDB's `top_label(image)` over a BLOB column).
-    batch = pa.RecordBatch.from_pydict(
-        {"image": pa.array([png_bytes((200, 30, 30)), None], type=pa.binary())}
-    )
+    batch = pa.RecordBatch.from_pydict({"image": pa.array([png_bytes((200, 30, 30)), None], type=pa.binary())})
     with _client() as client:
         results = list(
             client.scalar_function(

uv.lock

@@ -206,7 +206,7 @@ def labels() -> list[str]:
 
 @lru_cache(maxsize=1)
 def _input_name() -> str:
-    return _session().get_inputs()[0].name
+    return str(_session().get_inputs()[0].name)
 
 
 # ---------------------------------------------------------------------------
@@ -244,7 +244,8 @@ def _softmax(logits: np.ndarray) -> np.ndarray:
     """Numerically-stable softmax over the last axis."""
     z = logits - np.max(logits)
     e = np.exp(z)
-    return e / np.sum(e)
+    result: np.ndarray = e / np.sum(e)
+    return result
 
 
 def classify_image(data: bytes | None, top_k: int = 5) -> list[tuple[str, float]] | None:

vgi_vision/model.py

@@ -49,6 +49,8 @@ class TopLabelFunction(ScalarFunction):
     """``top_label(image)`` -- the #1 predicted ImageNet label for a BLOB image."""
 
     class Meta:
+        """VGI function metadata."""
+
         name = "top_label"
         description = "The #1 predicted ImageNet label for an image BLOB (NULL if not an image)"
         categories = ["vision", "classification"]
@@ -63,6 +65,7 @@ class Meta:
     def compute(
         cls, image: Annotated[pa.BinaryArray, Param(doc="Image bytes (PNG/JPEG/...).")]
     ) -> Annotated[pa.StringArray, Returns()]:
+        """Return the top label for each image BLOB in the array."""
         out = [None if b is None else model.top_label_for(b) for b in image.to_pylist()]
         return pa.array(out, type=pa.string())
 
@@ -71,6 +74,8 @@ class TopLabelPathFunction(ScalarFunction):
     """``top_label(path)`` -- like ``top_label(image)`` but reads a file path."""
 
     class Meta:
+        """VGI function metadata."""
+
         name = "top_label"
         description = "The #1 predicted ImageNet label for an image file path (NULL if unreadable)"
         categories = ["vision", "classification"]
@@ -85,6 +90,7 @@ class Meta:
     def compute(
         cls, path: Annotated[pa.StringArray, Param(doc="Filesystem path to an image file.")]
     ) -> Annotated[pa.StringArray, Returns()]:
+        """Return the top label for the image at each filesystem path in the array."""
         out = [None if p is None else model.top_label_for(_read_path(p)) for p in path.to_pylist()]
         return pa.array(out, type=pa.string())
 

vgi_vision/scalars.py

@@ -30,13 +30,13 @@
 from vgi.metadata import FunctionExample
 from vgi.table_function import (
     BindParams,
-    OutputCollector,
     ProcessParams,
     TableCardinality,
     TableFunctionGenerator,
     bind_fixed_schema,
     init_single_worker,
 )
+from vgi_rpc.rpc import OutputCollector
 
 from . import model
 from .scalars import _read_path
@@ -99,6 +99,8 @@ class ClassifyFunction(TableFunctionGenerator[_ClassifyBlobArgs]):
     FIXED_SCHEMA: ClassVar[pa.Schema] = _CLASSIFY_SCHEMA
 
     class Meta:
+        """VGI function metadata."""
+
         name = "classify"
         description = "Top-5 ImageNet predictions (label, confidence) for an image BLOB"
         categories = ["vision", "classification"]
@@ -111,10 +113,12 @@ class Meta:
 
     @classmethod
     def cardinality(cls, params: BindParams[_ClassifyBlobArgs]) -> TableCardinality:
+        """Estimate the output row count (the default top-k)."""
         return TableCardinality(estimate=_DEFAULT_TOP_K, max=_DEFAULT_TOP_K)
 
     @classmethod
     def process(cls, params: ProcessParams[_ClassifyBlobArgs], state: None, out: OutputCollector) -> None:
+        """Classify the image BLOB and emit the top-5 predictions."""
         preds = model.classify_image(params.args.image, top_k=_DEFAULT_TOP_K)
         _emit_classify(preds, out, params.output_schema)
 
@@ -128,6 +132,8 @@ class ClassifyTopKFunction(TableFunctionGenerator[_ClassifyBlobTopKArgs]):
     FIXED_SCHEMA: ClassVar[pa.Schema] = _CLASSIFY_SCHEMA
 
     class Meta:
+        """VGI function metadata."""
+
         name = "classify"
         description = "Top-k ImageNet predictions (label, confidence) for an image BLOB"
         categories = ["vision", "classification"]
@@ -140,11 +146,13 @@ class Meta:
 
     @classmethod
     def cardinality(cls, params: BindParams[_ClassifyBlobTopKArgs]) -> TableCardinality:
+        """Estimate the output row count (the requested top-k)."""
         k = max(1, params.args.top_k)
         return TableCardinality(estimate=k, max=k)
 
     @classmethod
     def process(cls, params: ProcessParams[_ClassifyBlobTopKArgs], state: None, out: OutputCollector) -> None:
+        """Classify the image BLOB and emit the top-k predictions."""
         preds = model.classify_image(params.args.image, top_k=params.args.top_k)
         _emit_classify(preds, out, params.output_schema)
 
@@ -174,6 +182,8 @@ class ClassifyPathFunction(TableFunctionGenerator[_ClassifyPathArgs]):
     FIXED_SCHEMA: ClassVar[pa.Schema] = _CLASSIFY_SCHEMA
 
     class Meta:
+        """VGI function metadata."""
+
         name = "classify"
         description = "Top-5 ImageNet predictions for an image file path"
         categories = ["vision", "classification"]
@@ -186,10 +196,12 @@ class Meta:
 
     @classmethod
     def cardinality(cls, params: BindParams[_ClassifyPathArgs]) -> TableCardinality:
+        """Estimate the output row count (the default top-k)."""
         return TableCardinality(estimate=_DEFAULT_TOP_K, max=_DEFAULT_TOP_K)
 
     @classmethod
     def process(cls, params: ProcessParams[_ClassifyPathArgs], state: None, out: OutputCollector) -> None:
+        """Read the image off disk, classify it, and emit the top-5 predictions."""
         preds = model.classify_image(_read_path(params.args.path), top_k=_DEFAULT_TOP_K)
         _emit_classify(preds, out, params.output_schema)
 
@@ -203,6 +215,8 @@ class ClassifyPathTopKFunction(TableFunctionGenerator[_ClassifyPathTopKArgs]):
     FIXED_SCHEMA: ClassVar[pa.Schema] = _CLASSIFY_SCHEMA
 
     class Meta:
+        """VGI function metadata."""
+
         name = "classify"
         description = "Top-k ImageNet predictions for an image file path"
         categories = ["vision", "classification"]
@@ -215,11 +229,13 @@ class Meta:
 
     @classmethod
     def cardinality(cls, params: BindParams[_ClassifyPathTopKArgs]) -> TableCardinality:
+        """Estimate the output row count (the requested top-k)."""
         k = max(1, params.args.top_k)
         return TableCardinality(estimate=k, max=k)
 
     @classmethod
     def process(cls, params: ProcessParams[_ClassifyPathTopKArgs], state: None, out: OutputCollector) -> None:
+        """Read the image off disk, classify it, and emit the top-k predictions."""
         preds = model.classify_image(_read_path(params.args.path), top_k=params.args.top_k)
         _emit_classify(preds, out, params.output_schema)
 
@@ -243,6 +259,8 @@ class ImageClassesFunction(TableFunctionGenerator[_NoArgs]):
     FIXED_SCHEMA: ClassVar[pa.Schema] = _CLASSES_SCHEMA
 
     class Meta:
+        """VGI function metadata."""
+
         name = "image_classes"
         description = "The model's ImageNet label set: (idx, label), 1000 rows"
         categories = ["vision", "classification"]
@@ -255,10 +273,12 @@ class Meta:
 
     @classmethod
     def cardinality(cls, params: BindParams[_NoArgs]) -> TableCardinality:
+        """Estimate the output row count (the model's full label set)."""
         return TableCardinality(estimate=model.NUM_CLASSES, max=model.NUM_CLASSES)
 
     @classmethod
     def process(cls, params: ProcessParams[_NoArgs], state: None, out: OutputCollector) -> None:
+        """Emit every ``(idx, label)`` the classifier can predict."""
         rows = model.class_table()
         out.emit(
             pa.RecordBatch.from_pydict(