sarj-python-lint 0.81.8__tar.gz → 0.81.11__tar.gz

{sarj_python_lint-0.81.8 → sarj_python_lint-0.81.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 0.81.8
+Version: 0.81.11
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://code-standards.sarj.ai/rules/python/
 Project-URL: Documentation, https://code-standards.sarj.ai/rules/python/

{sarj_python_lint-0.81.8 → sarj_python_lint-0.81.11}/pyproject.toml

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

{sarj_python_lint-0.81.8 → sarj_python_lint-0.81.11}/src/sarj_python_lint/rules/no_raw_connection_in_tests.py

@@ -42,7 +42,7 @@ class NoRawConnectionInTests(Rule):
         category=RuleCategory.TESTING,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Only test paths outside conftest.py and conventional shared test-support modules are inspected.",
+            "Only collected test modules outside conftest.py, conventional shared test-support modules, and migration-test trees are inspected.",
             "A receiver is reported only when a parameter, annotated local, or constructor call proves it is a psycopg ConnectionPool or AsyncConnectionPool.",
             "Pytest fixtures may use a connection internally for setup and cleanup, but fixtures that return or yield the connection remain reportable.",
         ),
@@ -81,12 +81,16 @@ class NoRawConnectionInTests(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if (
-            not is_test_path(path)
-            or path.name == "conftest.py"
-            or is_test_support_path(path)
-            or is_generated(path, source)
-        ):
+        excluded_path = any(
+            (
+                not is_test_path(path),
+                path.name == "conftest.py",
+                is_test_support_path(path),
+                _is_non_collected_test_support(path),
+                _is_migration_test(path),
+            )
+        )
+        if excluded_path or is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:
@@ -120,6 +124,18 @@ class NoRawConnectionInTests(Rule):
         return sorted(diagnostics, key=lambda item: (item.line, item.col))
 
 
+def _is_non_collected_test_support(path: Path) -> bool:
+    return "tests" in path.parts and not (path.name.startswith("test_") or path.name.endswith("_test.py"))
+
+
+def _is_migration_test(path: Path) -> bool:
+    parts = path.parts
+    return any(
+        part == "tests" and index + 1 < len(parts) and parts[index + 1] == "migrations"
+        for index, part in enumerate(parts)
+    )
+
+
 def _proven_pool_names(scope: ast.Module | ast.FunctionDef | ast.AsyncFunctionDef) -> frozenset[str]:
     names: set[str] = set()
     if isinstance(scope, (ast.FunctionDef, ast.AsyncFunctionDef)):

{sarj_python_lint-0.81.8 → sarj_python_lint-0.81.11}/src/sarj_python_lint/rules/prefer_match_type_dispatch.py

@@ -26,7 +26,6 @@ if TYPE_CHECKING:
 
 _MIN_BRANCHES = 3
 _ISINSTANCE_ARGS = 2
-_NESTED_TYPE_CHECKS = 2
 _BUILTIN_TYPES = frozenset(
     {
         "bool",
@@ -88,24 +87,21 @@ class PreferMatchTypeDispatch(Rule):
     id: str = "prefer-match-type-dispatch"
     code: str = "SARJ080"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="Prefer `match` for structural runtime type dispatch and nested class guards.",
+        summary="Prefer `match` for structural runtime type dispatch.",
         rationale=(
             "A long mutually exclusive `isinstance` dispatch repeats its subject and hides the closed list of "
-            "runtime shapes. A chained guard that separately checks an object and one of its attributes similarly "
-            "spells one structural invariant as unrelated boolean calls; class patterns express both shapes and "
-            "can bind the narrowed values in one construct."
+            "runtime shapes. Class patterns make the alternatives explicit without repeating the dispatch subject."
         ),
         remediation=(
             "Replace the branches with `match subject` and one class-pattern arm per distinct type; combine types "
-            "that share behavior with an OR-pattern. For a nested guard, use a nested class pattern and bind any "
-            "narrowed attribute that later code consumes."
+            "that share behavior with an OR-pattern."
         ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(
             "General dispatch requires three or more adjacent, unguarded `isinstance` branches over the same simple name. Two arms are checked only for an exact `ast.Name.id` / `ast.Attribute.attr` projection followed by a None-returning fallback.",
-            "Nested-guard findings require exactly two negated checks joined by `or`: an imported or module-local class for a simple name, followed by an imported or module-local class for an attribute rooted at that name, with an unconditional built-in `TypeError` raise.",
             "The checked types must be unshadowed builtins, unshadowed module-local classes, or proven stdlib ast classes; unresolved imports, runtime type groups, repeated type references, generated files, and non-terminating sibling checks are excluded.",
+            "Nested attribute-validation guards are excluded: converting them to keyword class patterns can turn attribute errors into match fallthrough, and an imported isinstance operand may be a runtime tuple rather than a class.",
             "A terminal-looking context-manager body does not prove a sibling branch terminates: exceptions can be suppressed. An unconditional return or raise after the context manager remains eligible.",
             "Declared support for Python before 3.10 suppresses this recommendation when proven by the nearest project metadata or exact installed-distribution ownership. Missing or ambiguous target metadata retains advisory behavior; it does not prove a modern target.",
         ),
@@ -154,47 +150,6 @@ class PreferMatchTypeDispatch(Rule):
                 expected_count=0,
                 public=True,
             ),
-            RuleExample(
-                example_id="nested-class-type-guard",
-                title="Separate type checks describe one nested runtime shape",
-                outcome=ExampleOutcome.MATCH,
-                scenario="nested-class-guard",
-                files=(
-                    ExampleFile.python(
-                        "app/scheduler.py",
-                        "from app.models import ActiveSettings, CustomScenario\n\n"
-                        "def schedule(settings):\n"
-                        "    if not isinstance(settings, ActiveSettings) or not isinstance(settings.scenario, CustomScenario):\n"
-                        "        raise TypeError('custom scenario required')\n"
-                        "    return settings.scenario.id\n",
-                    ),
-                ),
-                focus_path=PurePosixPath("app/scheduler.py"),
-                expected_count=1,
-                public=True,
-            ),
-            RuleExample(
-                example_id="nested-class-pattern",
-                title="One class pattern checks and binds the nested runtime shape",
-                outcome=ExampleOutcome.NO_MATCH,
-                scenario="nested-class-guard",
-                files=(
-                    ExampleFile.python(
-                        "app/scheduler.py",
-                        "from app.models import ActiveSettings, CustomScenario\n\n"
-                        "def schedule(settings):\n"
-                        "    match settings:\n"
-                        "        case ActiveSettings(scenario=CustomScenario() as scenario):\n"
-                        "            pass\n"
-                        "        case _:\n"
-                        "            raise TypeError('custom scenario required')\n"
-                        "    return scenario.id\n",
-                    ),
-                ),
-                focus_path=PurePosixPath("app/scheduler.py"),
-                expected_count=0,
-                public=True,
-            ),
             RuleExample(
                 example_id="two-arm-ast-projection",
                 title="Two isinstance returns project one AST identifier shape",
@@ -277,16 +232,6 @@ class PreferMatchTypeDispatch(Rule):
                 unsafe_bindings=unsafe_bindings,
             )
         )
-        findings.extend(
-            _nested_guard_findings(
-                all_nodes,
-                path,
-                self.code,
-                imports,
-                local_classes,
-                unsafe_bindings=unsafe_bindings,
-            )
-        )
         findings.extend(
             _two_arm_ast_projection_findings(
                 all_nodes,
@@ -441,62 +386,6 @@ def _dispatch(
     return _Dispatch(subjects.pop(), len(branches))
 
 
-def _nested_guard_findings(
-    all_nodes: tuple[ast.AST, ...],
-    path: Path,
-    code: str,
-    imports: ImportIndex,
-    local_classes: frozenset[str],
-    *,
-    unsafe_bindings: frozenset[str],
-) -> list[Diagnostic]:
-    findings: list[Diagnostic] = []
-    for node in all_nodes:
-        if (
-            not isinstance(node, ast.If)
-            or node.orelse
-            or not _raises_builtin_type_error(node.body, imports, unsafe_bindings)
-            or "isinstance" in unsafe_bindings
-        ):
-            continue
-        test = node.test
-        if (
-            not isinstance(test, ast.BoolOp)
-            or not isinstance(test.op, ast.Or)
-            or len(test.values) != _NESTED_TYPE_CHECKS
-        ):
-            continue
-        first = _negated_isinstance(test.values[0])
-        second = _negated_isinstance(test.values[1])
-        if first is None or second is None:
-            continue
-        first_subject, first_type = first
-        second_subject, second_type = second
-        if not isinstance(first_subject, ast.Name):
-            continue
-        attribute = _attribute_path(second_subject, root=first_subject.id)
-        if (
-            attribute is None
-            or not _is_class_pattern_type(first_type, imports, local_classes)
-            or not _is_class_pattern_type(second_type, imports, local_classes)
-        ):
-            continue
-        findings.append(
-            Diagnostic(
-                path=path,
-                line=node.lineno,
-                col=node.col_offset + 1,
-                code=code,
-                severity=Severity.WARNING,
-                message=(
-                    f"nested isinstance guard on '{first_subject.id}.{attribute}' — use one match/case class "
-                    "pattern and bind the narrowed attribute consumed after the guard."
-                ),
-            )
-        )
-    return findings
-
-
 def _two_arm_ast_projection_findings(
     all_nodes: tuple[ast.AST, ...],
     path: Path,
@@ -602,42 +491,6 @@ def _returns_none(statement: ast.stmt) -> bool:
     )
 
 
-def _raises_builtin_type_error(body: list[ast.stmt], imports: ImportIndex, unsafe_bindings: frozenset[str]) -> bool:
-    if not imports.builtin_is_unshadowed("TypeError") or "TypeError" in unsafe_bindings or not body:
-        return False
-    final_statement = body[-1]
-    if not isinstance(final_statement, ast.Raise) or final_statement.exc is None:
-        return False
-    exception = final_statement.exc.func if isinstance(final_statement.exc, ast.Call) else final_statement.exc
-    return isinstance(exception, ast.Name) and exception.id == "TypeError"
-
-
-def _negated_isinstance(node: ast.expr) -> tuple[ast.expr, ast.expr] | None:
-    if not isinstance(node, ast.UnaryOp) or not isinstance(node.op, ast.Not):
-        return None
-    call = node.operand
-    if not (
-        isinstance(call, ast.Call)
-        and isinstance(call.func, ast.Name)
-        and call.func.id == "isinstance"
-        and len(call.args) == _ISINSTANCE_ARGS
-        and not call.keywords
-    ):
-        return None
-    return call.args[0], call.args[1]
-
-
-def _attribute_path(node: ast.expr, *, root: str) -> str | None:
-    parts: list[str] = []
-    current = node
-    while isinstance(current, ast.Attribute):
-        parts.append(current.attr)
-        current = current.value
-    if not isinstance(current, ast.Name) or current.id != root or not parts:
-        return None
-    return ".".join(reversed(parts))
-
-
 def _is_class_pattern_type(
     node: ast.expr,
     imports: ImportIndex,

{sarj_python_lint-0.81.8 → sarj_python_lint-0.81.11}/src/sarj_python_lint/rules/prefer_walrus_awaited_none_guard.py

@@ -5,7 +5,7 @@ from io import StringIO
 from itertools import pairwise
 from pathlib import PurePosixPath
 import tokenize
-from typing import TYPE_CHECKING, ClassVar, NamedTuple, final, override
+from typing import TYPE_CHECKING, ClassVar, Literal, NamedTuple, final, override
 
 from sarj_python_lint.rule_base import (
     AutofixPolicy,
@@ -28,11 +28,13 @@ if TYPE_CHECKING:
 
 
 _MAX_COMBINED_LINE_LENGTH = 120
+type _NameFlow = Literal["ambiguous", "loaded", "none", "rebound", "terminal"]
 
 
 class _WalrusCandidate(NamedTuple):
     name: str
     awaited: ast.Await
+    is_not_none: bool
 
 
 @final
@@ -40,20 +42,23 @@ class PreferWalrusAwaitedNoneGuard(Rule):
     id = "prefer-walrus-awaited-none-guard"
     code = "SARJ432"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="Bind a compact awaited lookup in its immediately following None guard.",
+        summary="Bind a compact awaited lookup in its immediately following terminal None guard.",
         rationale=(
-            "When an awaited lookup and its mandatory absence guard are adjacent, binding in the condition keeps "
-            "the operation and the reason for the temporary name in one compact expression."
+            "When an awaited lookup and its terminal None guard are adjacent, binding in the condition keeps "
+            "the operation, branch decision, and temporary name in one compact expression."
         ),
         remediation=(
             "Rewrite `value = await lookup(); if value is None: return` as "
-            "`if (value := await lookup()) is None: return`."
+            "`if (value := await lookup()) is None: return`. Preserve `is not None` when the terminal branch "
+            "returns or raises with the bound value. Keep two statements when the assignment is an intentional "
+            "debugging or tracing boundary."
         ),
         category=RuleCategory.STYLE,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Only one-line awaited calls followed immediately by an exact `is None` guard containing one return are checked.",
-            "The combined condition must fit 120 columns; comments, else branches, rebinding, generated files, and broader assignment-expression preferences are excluded.",
+            "Only one-line awaited calls followed immediately by an exact `is None` or `is not None` guard containing one return or raise are checked.",
+            "A negative guard requires a later use on the surviving path; a positive guard must consume the binding in its terminal statement and leave no later use before rebinding.",
+            "The combined condition must fit 120 columns; comments, else branches, ambiguous name flow, generated files, and broader assignment-expression preferences are excluded.",
         ),
         examples=(
             RuleExample(
@@ -99,6 +104,8 @@ class PreferWalrusAwaitedNoneGuard(Rule):
     def check(self, path: Path, source: str) -> list[Diagnostic]:
         if path.suffix == ".pyi" or is_generated(path, source):
             return []
+        if any(token not in source for token in ("await", "None", "if", "=")):
+            return []
         tree = parse_or_none(path, source)
         if tree is None:
             return []
@@ -110,8 +117,11 @@ class PreferWalrusAwaitedNoneGuard(Rule):
                 candidate = _candidate(assignment, guard, source, source_lines, comment_lines)
                 if candidate is None:
                     continue
-                name, awaited = candidate
-                if not _used_before_rebinding(body[index + 2 :], name):
+                name, awaited, is_not_none = candidate
+                later_flow = _name_flow(body[index + 2 :], name)
+                if (is_not_none and later_flow in {"ambiguous", "loaded"}) or (
+                    not is_not_none and later_flow != "loaded"
+                ):
                     continue
                 if is_suppressed(source_lines, assignment.lineno, self.code) or is_suppressed(
                     source_lines, guard.lineno, self.code
@@ -128,8 +138,9 @@ class PreferWalrusAwaitedNoneGuard(Rule):
                         code=self.code,
                         severity=Severity.WARNING,
                         message=(
-                            f"`{name}` only separates an awaited lookup from its None guard; "
-                            f"bind it as `if ({name} := {expression.strip()}) is None:`"
+                            f"`{name}` only separates an awaited lookup from its terminal None guard; "
+                            f"bind it as `if ({name} := {expression.strip()}) "
+                            f"is {'not ' if is_not_none else ''}None:`"
                         ),
                     )
                 )
@@ -157,36 +168,50 @@ def _candidate(
         and guard.test.end_lineno == guard.lineno
         and not guard.orelse
         and len(guard.body) == 1
-        and isinstance(guard.body[0], ast.Return)
+        and isinstance(guard.body[0], (ast.Return, ast.Raise))
     ):
         return None
     name = assignment.targets[0].id
-    if not _is_none_guard(guard.test, name) or _loads_name(assignment.value, name) or _loads_name(guard.body[0], name):
+    is_not_none = _none_guard_kind(guard.test, name)
+    if is_not_none is None or _loads_name(assignment.value, name):
+        return None
+    terminal = guard.body[0]
+    usage = _NameUsage(name)
+    usage.visit(terminal)
+    if usage.rebound or (is_not_none != usage.loaded):
         return None
-    if comment_lines.intersection(range(assignment.lineno, guard.lineno + 1)):
+    terminal_end = terminal.end_lineno or terminal.lineno
+    if comment_lines.intersection(range(assignment.lineno, terminal_end + 1)):
         return None
     expression = ast.get_source_segment(source, assignment.value)
     if expression is None:
         return None
     original_line = source_lines[assignment.lineno - 1]
     indentation = original_line[: len(original_line) - len(original_line.lstrip())].expandtabs(8)
-    combined = f"{indentation}if ({name} := {expression.strip()}) is None:"
+    combined = f"{indentation}if ({name} := {expression.strip()}) is {'not ' if is_not_none else ''}None:"
+    if terminal.lineno == guard.lineno:
+        terminal_source = ast.get_source_segment(source, terminal)
+        if terminal_source is None:
+            return None
+        combined = f"{combined} {terminal_source.strip()}"
     if len(combined) > _MAX_COMBINED_LINE_LENGTH:
         return None
-    return _WalrusCandidate(name, assignment.value)
+    return _WalrusCandidate(name, assignment.value, is_not_none)
 
 
-def _is_none_guard(test: ast.expr, name: str) -> bool:
-    return (
+def _none_guard_kind(test: ast.expr, name: str) -> bool | None:
+    if not (
         isinstance(test, ast.Compare)
         and isinstance(test.left, ast.Name)
         and test.left.id == name
         and len(test.ops) == 1
-        and isinstance(test.ops[0], ast.Is)
+        and isinstance(test.ops[0], (ast.Is, ast.IsNot))
         and len(test.comparators) == 1
         and isinstance(test.comparators[0], ast.Constant)
         and test.comparators[0].value is None
-    )
+    ):
+        return None
+    return isinstance(test.ops[0], ast.IsNot)
 
 
 def _loads_name(node: ast.AST, name: str) -> bool:
@@ -195,15 +220,19 @@ def _loads_name(node: ast.AST, name: str) -> bool:
     )
 
 
-def _used_before_rebinding(statements: list[ast.stmt], name: str) -> bool:
+def _name_flow(statements: list[ast.stmt], name: str) -> _NameFlow:
     for statement in statements:
         usage = _NameUsage(name)
         usage.visit(statement)
+        if usage.loaded and usage.rebound:
+            return "ambiguous"
         if usage.rebound:
-            return False
+            return "rebound"
         if usage.loaded:
-            return True
-    return False
+            return "loaded"
+        if isinstance(statement, (ast.Break, ast.Continue, ast.Raise, ast.Return)):
+            return "terminal"
+    return "none"
 
 
 @final
@@ -234,6 +263,10 @@ class _NameUsage(ast.NodeVisitor):
     def visit_Lambda(self, node: ast.Lambda) -> None:
         _ = node
 
+    @override
+    def visit_GeneratorExp(self, node: ast.GeneratorExp) -> None:
+        _ = node
+
     def visit_Import(self, node: ast.Import) -> None:
         self.rebound |= any((alias.asname or alias.name.split(".", maxsplit=1)[0]) == self.name for alias in node.names)