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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.3.0
+Version: 0.4.1
 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

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

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

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

@@ -5,6 +5,7 @@ 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
@@ -25,6 +26,7 @@ REGISTRY: dict[str, type[Rule]] = {
     PreferDiscriminatedUnion.id: PreferDiscriminatedUnion,
     PreferStrEnum.id: PreferStrEnum,
     NoFatTryBlocks.id: NoFatTryBlocks,
+    NoIsinstanceUnionChain.id: NoIsinstanceUnionChain,
     PydanticAtBoundaries.id: PydanticAtBoundaries,
     NoSentinelReturnOnExcept.id: NoSentinelReturnOnExcept,
     NoUnreachableAfterTerminal.id: NoUnreachableAfterTerminal,

sarj_python_lint-0.4.1/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.3.0 → sarj_python_lint-0.4.1}/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":

{sarj_python_lint-0.3.0 → sarj_python_lint-0.4.1}/src/sarj_python_lint/rules/prefer_str_enum.py

@@ -40,30 +40,22 @@ from pathlib import Path
 from sarj_python_lint.rule_base import Diagnostic, Rule
 
 #: Field / variable name tokens that strongly suggest a closed enumeration.
+#: Kept deliberately HIGH-PRECISION — only words that are almost always a fixed
+#: set. Broader/free-form-prone tokens (type, provider, level, mode, category,
+#: channel, method, strategy, format, source, language, environment, …) were
+#: removed: they over-fired on free-form strings. Those cases are still caught
+#: when corroborated — via a sibling `choices`/`states` attribute or a
+#: comparison cluster against literal values.
 CHOICE_NAME_TOKENS = frozenset(
     {
         "status",
         "state",
-        "type",
         "kind",
-        "provider",
-        "language",
-        "lang",
         "role",
         "priority",
-        "level",
-        "mode",
-        "category",
+        "severity",
         "direction",
-        "environment",
-        "env",
         "tier",
-        "severity",
-        "channel",
-        "method",
-        "strategy",
-        "format",
-        "source",
         "stage",
     }
 )

{sarj_python_lint-0.3.0 → sarj_python_lint-0.4.1}/src/sarj_python_lint/rules/pydantic_at_boundaries.py

@@ -27,15 +27,16 @@ Purely annotation-based (no type inference), checked on function definitions
 (sync + async):
 
 1. Return annotation that is ``dict[str, Any]`` / ``dict[str, object]`` /
-   bare ``dict`` / ``Dict``, ``list[dict[str, Any]]``, or a ``tuple[...]``
-   with 2+ distinct element types.
+   bare ``dict`` / ``Dict``, or ``list[dict[str, Any]]``.
 2. FastAPI route handlers (``@router.get(...)`` / ``@app.post(...)`` etc.)
    with no return annotation and no ``response_model=`` in the decorator.
 
-Not flagged: fully-concrete dict value types (``dict[str, str]``),
-homogeneous tuples (``tuple[int, ...]``, ``tuple[str, str]``), heterogeneous
-tuple returns from private (``_``-prefixed) non-route functions, ``@overload``
-stubs, and test files.
+Deliberately NOT flagged (kept high-precision for real boundaries):
+private / ``_``-prefixed functions (internal, not a public contract), pydantic
+``@model_validator`` / ``@field_validator`` hooks (raw dict in/out is their
+API), ``tuple[...]`` returns (multiple return values are idiomatic Python),
+fully-concrete dict value types (``dict[str, str]``), ``@overload`` stubs, and
+test files.
 
 References:
 - https://docs.pydantic.dev/latest/concepts/models/
@@ -53,7 +54,6 @@ from sarj_python_lint.rule_base import Diagnostic, Rule
 _HTTP_METHODS = {"get", "post", "put", "patch", "delete"}
 _DICT_NAMES = {"dict", "Dict"}
 _LIST_NAMES = {"list", "List"}
-_TUPLE_NAMES = {"tuple", "Tuple"}
 _ANY_VALUE_NAMES = {"Any", "object"}
 
 
@@ -65,12 +65,12 @@ class _RouteInfo:
 
 
 class PydanticAtBoundaries(Rule):
-    """Untyped dict / heterogeneous tuple return — define a pydantic model."""
+    """Untyped dict return at a public boundary — define a pydantic model."""
 
     id = "pydantic-at-boundaries"
     code = "SARJ008"
     description = (
-        "Function returns an untyped dict or heterogeneous tuple — "
+        "Public function/route returns an untyped dict — "
         "define a pydantic model (or frozen dataclass)."
     )
 
@@ -87,6 +87,15 @@ class PydanticAtBoundaries(Rule):
                 continue
             if _is_overload(node):
                 continue
+            # Private/internal functions are not public boundaries — their
+            # return shape is an implementation detail, not a data contract.
+            if node.name.startswith("_"):
+                continue
+            # Pydantic validator hooks (`@model_validator`/`@field_validator`)
+            # take and return raw dict/values by contract — that's the API, not
+            # a missing model.
+            if _is_validator(node):
+                continue
             route = _route_info(node)
             returns = _resolve_annotation(node.returns)
             if returns is None:
@@ -108,10 +117,6 @@ class PydanticAtBoundaries(Rule):
             kind = _classify_return(returns)
             if kind is None:
                 continue
-            # Private functions returning heterogeneous tuples are common and
-            # fine-ish; untyped dicts are flagged everywhere.
-            if kind == "tuple" and route is None and node.name.startswith("_"):
-                continue
             ann_text = ast.unparse(returns)
             diags.append(
                 Diagnostic(
@@ -141,6 +146,19 @@ def _is_overload(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
     return False
 
 
+_VALIDATOR_DECORATORS = {"model_validator", "field_validator", "validator", "root_validator"}
+
+
+def _is_validator(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    """A pydantic validator hook — dict/value in-and-out is its required contract."""
+    for dec in node.decorator_list:
+        target = dec.func if isinstance(dec, ast.Call) else dec
+        name = _flat_name(target) if isinstance(target, (ast.Name, ast.Attribute)) else ""
+        if name in _VALIDATOR_DECORATORS:
+            return True
+    return False
+
+
 def _route_info(node: ast.FunctionDef | ast.AsyncFunctionDef) -> _RouteInfo | None:
     """Detect a FastAPI route decorator: `@<router|app|*_router>.<method>(...)`."""
     for dec in node.decorator_list:
@@ -199,8 +217,8 @@ def _classify_return(node: ast.expr) -> str | None:
         return "dict" if inner == "dict" else None
     if base in _DICT_NAMES:
         return "dict" if _is_untyped_dict_args(node.slice) else None
-    if base in _TUPLE_NAMES:
-        return "tuple" if _is_heterogeneous_tuple_args(node.slice) else None
+    # Heterogeneous tuple returns are NOT flagged — multiple return values are
+    # idiomatic Python, not a missing data contract.
     return None
 
 
@@ -211,15 +229,6 @@ def _is_untyped_dict_args(slice_node: ast.expr) -> bool:
     return _flat_name(slice_node.elts[1]) in _ANY_VALUE_NAMES
 
 
-def _is_heterogeneous_tuple_args(slice_node: ast.expr) -> bool:
-    """`tuple[...]` is flagged when it has 2+ distinct element types."""
-    if not isinstance(slice_node, ast.Tuple):
-        return False  # single-element `tuple[X]`
-    # `tuple[X, ...]` is a homogeneous variadic tuple.
-    if any(isinstance(elt, ast.Constant) and elt.value is Ellipsis for elt in slice_node.elts):
-        return False
-    distinct = {ast.unparse(elt) for elt in slice_node.elts}
-    return len(distinct) >= 2
 
 
 def _flat_name(node: ast.expr) -> str: