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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.4.0
+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.0 → 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.0 → sarj_python_lint-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.4.0"
+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.0 → sarj_python_lint-0.5.0}/src/sarj_python_lint/rules/__init__.py

@@ -5,12 +5,14 @@ from sarj_python_lint.rules.inefficient_string_concat_in_loop import (
     InefficientStringConcatInLoop,
 )
 from sarj_python_lint.rules.no_fat_try_blocks import NoFatTryBlocks
+from sarj_python_lint.rules.no_isinstance_union_chain import NoIsinstanceUnionChain
 from sarj_python_lint.rules.no_secret_in_log import NoSecretInLog
 from sarj_python_lint.rules.no_sentinel_return_on_except import NoSentinelReturnOnExcept
 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,
 )
@@ -23,8 +25,10 @@ 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,
     PydanticAtBoundaries.id: PydanticAtBoundaries,
     NoSentinelReturnOnExcept.id: NoSentinelReturnOnExcept,
     NoUnreachableAfterTerminal.id: NoUnreachableAfterTerminal,

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

@@ -0,0 +1,183 @@
+"""SARJ003: flag `if/elif isinstance(...)` chains that dispatch over a closed union.
+
+A chain of `if isinstance(x, A): ... elif isinstance(x, B): ...` (2+ branches, same
+target, each branch testing one locally-defined class) is almost always dispatch over a
+closed discriminated union. `match`/`case` with `assert_never` in the fallthrough is
+strictly better: pyright reports an error the moment a new variant is added and a branch
+is missed — a plain `isinstance` chain silently falls through.
+
+    # flagged
+    if isinstance(subject, ApiKeySubject):
+        ...
+    elif isinstance(subject, JwtSubject):
+        ...
+
+    # preferred
+    match subject:
+        case ApiKeySubject():
+            ...
+        case JwtSubject():
+            ...
+        case _:
+            assert_never(subject)
+
+This is a heuristic, not a proof the union is closed — so it accepts some false positives.
+Suppress a deliberate boundary chain with `# sarj-noqa: SARJ003 — <reason>`.
+
+Deliberately NOT flagged (boundary/runtime checks, not closed-union dispatch):
+- a single `isinstance` guard (no chain),
+- `isinstance(x, (A, B))` tuple-membership (one check, not a dispatch chain),
+- any chain whose branches test builtins/stdlib types (`dict`, `str`, `list`, `Exception`,
+  `datetime`, ...), the generated-SDK `Unset` sentinel, or `collections.abc`/`typing` ABCs,
+- any chain mixing `isinstance` with a non-`isinstance` condition (e.g. `hasattr`, a
+  comparison, a boolean combination) — a defensive guard, not a clean dispatch.
+
+References:
+- https://docs.python.org/3/library/typing.html#typing.assert_never
+- https://typing.python.org/en/latest/spec/narrowing.html#assert-never-and-exhaustiveness-checking
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+_EXCLUDED_TYPE_NAMES = frozenset(
+    {
+        "dict",
+        "str",
+        "list",
+        "tuple",
+        "set",
+        "frozenset",
+        "int",
+        "float",
+        "bool",
+        "complex",
+        "bytes",
+        "bytearray",
+        "type",
+        "object",
+        "Exception",
+        "BaseException",
+        "NoneType",
+        "Unset",
+        "datetime",
+        "date",
+        "time",
+        "timedelta",
+        "Mapping",
+        "MutableMapping",
+        "Sequence",
+        "MutableSequence",
+        "Iterable",
+        "Iterator",
+        "Collection",
+        "Container",
+        "Set",
+        "Hashable",
+        "Callable",
+    }
+)
+
+
+class NoIsinstanceUnionChain(Rule):
+    """`if/elif isinstance` chains over local classes — prefer match/case + assert_never."""
+
+    id = "no-isinstance-union-chain"
+    code = "SARJ003"
+    description = (
+        "if/elif isinstance chain over local classes — prefer match/case with "
+        "assert_never for compile-time exhaustiveness."
+    )
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        elif_nodes = _collect_elif_nodes(tree)
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.If) or id(node) in elif_nodes:
+                continue
+            count = _qualifying_chain_length(node)
+            if count >= 2:
+                diags.append(
+                    Diagnostic(
+                        path=path,
+                        line=node.lineno,
+                        col=node.col_offset + 1,
+                        code=self.code,
+                        message=(
+                            f"if/elif isinstance chain over {count} types — prefer "
+                            "match/case with assert_never for exhaustiveness."
+                        ),
+                    )
+                )
+        return diags
+
+
+def _collect_elif_nodes(tree: ast.AST) -> set[int]:
+    """ids of `If` nodes that are the sole `orelse` of another `If` (i.e. `elif` arms)."""
+    elifs: set[int] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.If) and len(node.orelse) == 1 and isinstance(node.orelse[0], ast.If):
+            elifs.add(id(node.orelse[0]))
+    return elifs
+
+
+def _qualifying_chain_length(head: ast.If) -> int:
+    """Number of branches if `head` is an all-`isinstance`-on-one-target chain, else 0.
+
+    Returns 0 if any branch is not `isinstance(<same target>, <single local class>)`.
+    """
+    target_dump: str | None = None
+    count = 0
+    current: ast.If | None = head
+    while current is not None:
+        type_arg = _isinstance_single_type(current.test)
+        if type_arg is None:
+            return 0
+        target, type_name = type_arg
+        if type_name in _EXCLUDED_TYPE_NAMES:
+            return 0
+        dumped = ast.dump(target)
+        if target_dump is None:
+            target_dump = dumped
+        elif dumped != target_dump:
+            return 0
+        count += 1
+        if len(current.orelse) == 1 and isinstance(current.orelse[0], ast.If):
+            current = current.orelse[0]
+        else:
+            current = None
+    return count
+
+
+def _isinstance_single_type(test: ast.expr) -> tuple[ast.expr, str] | None:
+    """If `test` is `isinstance(x, SomeClass)` with a single Name/Attribute class, return
+    (target, class_name); else None. Tuple-form `isinstance(x, (A, B))` returns None."""
+    if not isinstance(test, ast.Call):
+        return None
+    if not (isinstance(test.func, ast.Name) and test.func.id == "isinstance"):
+        return None
+    if len(test.args) != 2 or test.keywords:
+        return None
+    target, type_node = test.args
+    name = _class_name(type_node)
+    if name is None:
+        return None
+    return target, name
+
+
+def _class_name(node: ast.expr) -> str | None:
+    """The trailing name of a class reference: `Foo` / `mod.Foo` -> 'Foo'. None for tuples
+    or anything that isn't a plain Name/Attribute (e.g. a subscript or tuple-membership)."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return None

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

{sarj_python_lint-0.4.0 → sarj_python_lint-0.5.0}/src/sarj_python_lint/rules/prefer_discriminated_union.py

@@ -43,6 +43,10 @@ Three triggers:
    (`*Input` / `*Params` / `*Filter` / `*Query` / `Update*` / `Patch*` /
    `Upsert*`) are excluded from this trigger.
 
+   A single-value `Literal` tag (e.g. `type: Literal["complete"]`) marks a model
+   that is already an arm of a discriminated union, so it is excluded too — a
+   multi-value `Literal[...]` is still treated as a poor-man's discriminator.
+
 References:
 - https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions
 - https://en.wikipedia.org/wiki/Tagged_union
@@ -131,6 +135,7 @@ class PreferDiscriminatedUnion(Rule):
         if not (is_model or is_dc):
             return None
         has_status_bool = False
+        has_literal_tag = False
         optional_fields: list[str] = []
         discriminator_fields: list[str] = []
         for stmt in node.body:
@@ -146,6 +151,8 @@ class PreferDiscriminatedUnion(Rule):
                 stmt.annotation, str_enum_names
             ):
                 discriminator_fields.append(name)
+                if _is_single_value_literal(stmt.annotation):
+                    has_literal_tag = True
             if _is_optional(stmt.annotation):
                 if name not in IGNORED_OPTIONAL_FIELDS:
                     optional_fields.append(name)
@@ -164,10 +171,13 @@ class PreferDiscriminatedUnion(Rule):
                 ),
             )
         # Nullable-cluster trigger: discriminator-ish field + 3 or more nullables.
+        # A single-value `Literal` tag (e.g. `type: Literal["complete"]`) marks a
+        # model that is already a discriminated-union arm, not a poor-man's result.
         if (
             discriminator_fields
             and len(optional_fields) >= NULLABLE_CLUSTER_THRESHOLD
             and not _is_dto_class_name(node.name)
+            and not has_literal_tag
         ):
             return Diagnostic(
                 path=path,
@@ -190,6 +200,33 @@ def _is_dto_class_name(name: str) -> bool:
     return name.endswith(DTO_CLASS_NAME_SUFFIXES) or name.startswith(DTO_CLASS_NAME_PREFIXES)
 
 
+def _is_single_value_literal(node: ast.AST | None) -> bool:
+    """Detect a single-constant `Literal[X]` annotation.
+
+    A one-element `Literal` (e.g. `type: Literal["complete"]`) is the canonical
+    tag of a discriminated-union arm, so a model carrying one is already modelled
+    correctly. A multi-value `Literal[...]` is still a poor-man's discriminator.
+    """
+    if node is None:
+        return False
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        try:
+            parsed = ast.parse(node.value, mode="eval")
+        except SyntaxError:
+            return False
+        return _is_single_value_literal(parsed.body)
+    if not isinstance(node, ast.Subscript):
+        return False
+    if _get_name_flat(node.value).rsplit(".", 1)[-1] != "Literal":
+        return False
+    slice_node = node.slice
+    if type(slice_node).__name__ == "Index":
+        slice_node = getattr(slice_node, "value", slice_node)
+    if isinstance(slice_node, ast.Tuple):
+        return len(slice_node.elts) == 1
+    return True
+
+
 def _inherits_basemodel(node: ast.ClassDef) -> bool:
     for base in node.bases:
         if isinstance(base, ast.Name) and base.id == "BaseModel":