sarj-python-lint 0.4.1__tar.gz → 0.5.0__tar.gz

{sarj_python_lint-0.4.1 → sarj_python_lint-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.4.1
+Version: 0.5.0
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://github.com/sarj-ai/standards/tree/main/packages/python
 Project-URL: Repository, https://github.com/sarj-ai/standards
@@ -36,6 +36,7 @@ uv tool install sarj-python-lint
     - id: sarj-prefer-str-enum
     - id: sarj-no-fat-try-blocks
     - id: sarj-pydantic-at-boundaries
+    - id: sarj-prefer-class-row
 ```
 
 ## CLI

{sarj_python_lint-0.4.1 → sarj_python_lint-0.5.0}/README.md

@@ -18,6 +18,7 @@ uv tool install sarj-python-lint
     - id: sarj-prefer-str-enum
     - id: sarj-no-fat-try-blocks
     - id: sarj-pydantic-at-boundaries
+    - id: sarj-prefer-class-row
 ```
 
 ## CLI

{sarj_python_lint-0.4.1 → sarj_python_lint-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.4.1"
+version = "0.5.0"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]

{sarj_python_lint-0.4.1 → sarj_python_lint-0.5.0}/src/sarj_python_lint/rules/__init__.py

@@ -12,6 +12,7 @@ from sarj_python_lint.rules.no_sequential_await import NoSequentialAwait
 from sarj_python_lint.rules.no_unreachable_after_terminal import (
     NoUnreachableAfterTerminal,
 )
+from sarj_python_lint.rules.prefer_class_row import PreferClassRow
 from sarj_python_lint.rules.prefer_constant_time_secret_compare import (
     PreferConstantTimeSecretCompare,
 )
@@ -24,6 +25,7 @@ REGISTRY: dict[str, type[Rule]] = {
     NoSequentialAwait.id: NoSequentialAwait,
     InefficientStringConcatInLoop.id: InefficientStringConcatInLoop,
     PreferDiscriminatedUnion.id: PreferDiscriminatedUnion,
+    PreferClassRow.id: PreferClassRow,
     PreferStrEnum.id: PreferStrEnum,
     NoFatTryBlocks.id: NoFatTryBlocks,
     NoIsinstanceUnionChain.id: NoIsinstanceUnionChain,

sarj_python_lint-0.5.0/src/sarj_python_lint/rules/prefer_class_row.py

@@ -0,0 +1,85 @@
+"""SARJ013: psycopg `row_factory=dict_row` where a validated model row is intended.
+
+The repo standard is to map each DB row straight into a pydantic model with
+`class_row(Model)`, so every row is validated at the database boundary and the
+cursor is typed `Cursor[Model]`. `dict_row` instead hands back an unvalidated
+`dict[str, Any]` that callers then feed to `Model.model_validate(...)` by hand —
+an extra step that is easy to forget and leaves the value untyped in between.
+
+Flags any `row_factory=dict_row` keyword argument (typically on
+`conn.cursor(...)`). If you genuinely need a plain mapping — an ad-hoc
+aggregate, a `COUNT(*)`, or a dynamic projection with no model — suppress with
+`# sarj-noqa: prefer-class-row — <reason>`.
+
+Replace:
+    async with conn.cursor(row_factory=dict_row) as cur:
+        await cur.execute(..., RETURNING id, status)
+        row = await cur.fetchone()
+        return Task.model_validate(row)
+
+with:
+    async with conn.cursor(row_factory=class_row(Task)) as cur:
+        await cur.execute(..., RETURNING id, status)
+        return one(await cur.fetchone())
+
+References:
+- https://www.psycopg.org/psycopg3/docs/api/rows.html#psycopg.rows.class_row
+- https://docs.pydantic.dev/latest/concepts/models/#validating-data
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+
+_ROW_FACTORY_KW = "row_factory"
+_BANNED_FACTORY = "dict_row"
+
+
+class PreferClassRow(Rule):
+    """`row_factory=dict_row` returns unvalidated dicts — prefer `class_row(Model)`."""
+
+    id = "prefer-class-row"
+    code = "SARJ013"
+    description = "psycopg row_factory=dict_row returns unvalidated dicts — prefer class_row(Model)."
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.keyword):
+                continue
+            if node.arg != _ROW_FACTORY_KW:
+                continue
+            if _factory_name(node.value) != _BANNED_FACTORY:
+                continue
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.value.lineno,
+                    col=node.value.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        "`row_factory=dict_row` yields unvalidated dict rows — "
+                        "prefer `class_row(YourModel)` to validate at the DB boundary "
+                        "(suppress with `# sarj-noqa: prefer-class-row` for genuine ad-hoc shapes)"
+                    ),
+                )
+            )
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _factory_name(node: ast.expr) -> str | None:
+    """Resolve a `row_factory=` value to its callable name (`dict_row`, …)."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return None