sarj-python-lint 1.14.1__tar.gz → 1.14.3__tar.gz

{sarj_python_lint-1.14.1 → sarj_python_lint-1.14.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.14.1
+Version: 1.14.3
 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-1.14.1 → sarj_python_lint-1.14.3}/pyproject.toml

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

{sarj_python_lint-1.14.1 → sarj_python_lint-1.14.3}/src/sarj_python_lint/rules/_registry.py

@@ -88,6 +88,7 @@ from sarj_python_lint.rules.no_unique_violation_message_match import (
     NoUniqueViolationMessageMatch,
 )
 from sarj_python_lint.rules.no_unnecessary_docstring import NoUnnecessaryDocstring
+from sarj_python_lint.rules.no_unused_underscored_keyword_parameter import NoUnusedUnderscoredKeywordParameter
 from sarj_python_lint.rules.no_unused_value_marker import NoUnusedValueMarker
 from sarj_python_lint.rules.no_vague_suppression_description import (
     NoVagueSuppressionDescription,
@@ -306,6 +307,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoTypedDocSections.id: NoTypedDocSections,
         NoUnnecessaryDocstring.id: NoUnnecessaryDocstring,
         NoUnusedValueMarker.id: NoUnusedValueMarker,
+        NoUnusedUnderscoredKeywordParameter.id: NoUnusedUnderscoredKeywordParameter,
         PreferNominalIdTypes.id: PreferNominalIdTypes,
         NoAnyMappingTypes.id: NoAnyMappingTypes,
         NoUniqueViolationMessageMatch.id: NoUniqueViolationMessageMatch,

{sarj_python_lint-1.14.1 → sarj_python_lint-1.14.3}/src/sarj_python_lint/rules/no_injected_module_loader.py

@@ -185,17 +185,21 @@ def _shadowed(default: ast.expr, function: ast.AST, context: PythonFileContext)
     parent = context.parents.get(child)
     class_scope_visible = True
     while parent is not None:
-        if isinstance(parent, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
-            return True
-        if isinstance(parent, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
-            if _in_scope_body(parent, child):
-                if root.id in scope_bindings(parent):
-                    return True
-                class_scope_visible = False
-        elif isinstance(parent, ast.ClassDef) and _in_scope_body(parent, child):
-            if class_scope_visible and _class_prefix_shadows(parent, child, root.id):
+        match parent:
+            case ast.ListComp() | ast.SetComp() | ast.DictComp() | ast.GeneratorExp():
                 return True
-            class_scope_visible = False
+            case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.Lambda():
+                if _in_scope_body(parent, child):
+                    if root.id in scope_bindings(parent):
+                        return True
+                    class_scope_visible = False
+            case ast.ClassDef():
+                if _in_scope_body(parent, child):
+                    if class_scope_visible and _class_prefix_shadows(parent, child, root.id):
+                        return True
+                    class_scope_visible = False
+            case _:
+                pass
         child = parent
         parent = context.parents.get(parent)
     return False

sarj_python_lint-1.14.3/src/sarj_python_lint/rules/no_unused_underscored_keyword_parameter.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import ast
+from itertools import chain
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+@final
+class NoUnusedUnderscoredKeywordParameter(Rule):
+    id = "no-unused-underscored-keyword-parameter"
+    code = "SARJ475"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Remove unused underscore-prefixed keyword-only parameters instead of hiding them from lint.",
+        rationale=(
+            "A keyword-only parameter requires callers to use its declared name. Prefixing an unused input with an "
+            "underscore silences unused-argument lint while retaining an input whose value has no effect. Removing "
+            "the dead input and its callers keeps the callable's interface honest."
+        ),
+        remediation=(
+            "Remove the unused keyword-only parameter and update callers together. If an external contract requires "
+            "the input, preserve its required spelling and use a narrow, reasoned unused-argument suppression."
+        ),
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only underscore-prefixed keyword-only declarations are checked; positional and variadic callback slots are excluded.",
+            "Decorated functions other than unshadowed builtin staticmethod/classmethod, inherited methods, and intentional stubs are excluded.",
+            "Any reference within the body counts as use, including nested scopes; shadowing and reassignment can produce false negatives.",
+            "Functions accessing locals, vars, eval, or exec through recognized builtin bindings are excluded.",
+            "Call sites, lambda parameters, unknown dynamic reflection, and cross-module callback contracts are not resolved.",
+            "Generated and vendored files are excluded; test source is checked.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="discarded-keyword-input",
+                title="An ignored keyword input is kept just to silence unused-argument lint",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/sink.py", "def emit(*, _email=None):\n    return 'ready'\n"),),
+                focus_path=PurePosixPath("app/sink.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="removed-keyword-input",
+                title="The callable exposes only inputs it uses",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/sink.py", "def emit():\n    return 'ready'\n"),),
+                focus_path=PurePosixPath("app/sink.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.generated or "_" not in context.source or context.tree is None:
+            return []
+        findings: list[Diagnostic] = []
+        for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
+            for argument in _unused_parameters(context, function):
+                if is_suppressed(context.source_lines, argument.lineno, self.code):
+                    continue
+                findings.append(
+                    Diagnostic(
+                        path=context.path,
+                        line=argument.lineno,
+                        col=argument.col_offset + 1,
+                        code=self.code,
+                        severity=Severity.WARNING,
+                        message=(
+                            f"keyword-only parameter `{argument.arg}` is never referenced; remove the unused input "
+                            "and its callers instead of hiding it from unused-argument lint"
+                        ),
+                    )
+                )
+        return sorted(findings, key=lambda item: (item.line, item.col))
+
+
+def _unused_parameters(
+    context: PythonFileContext, function: ast.FunctionDef | ast.AsyncFunctionDef
+) -> tuple[ast.arg, ...]:
+    candidates = [argument for argument in function.args.kwonlyargs if argument.arg.startswith("_")]
+    if not candidates or _has_contract(context, function) or _is_stub(function):
+        return ()
+    body = list(chain.from_iterable(ast.walk(statement) for statement in function.body))
+    if _reads_dynamic_locals(context, body):
+        return ()
+    references = {node.id for node in body if isinstance(node, ast.Name)}
+    return tuple(argument for argument in candidates if argument.arg not in references)
+
+
+def _has_contract(context: PythonFileContext, function: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    parent = context.parents.get(function)
+    while parent is not None and not isinstance(
+        parent, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef | ast.Module
+    ):
+        parent = context.parents.get(parent)
+    if isinstance(parent, ast.ClassDef) and parent.bases:
+        return True
+    return any(
+        not (
+            isinstance(decorator, ast.Name)
+            and decorator.id in {"staticmethod", "classmethod"}
+            and context.imports.builtin_is_unshadowed(decorator.id)
+        )
+        for decorator in function.decorator_list
+    )
+
+
+def _is_stub(function: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    body = function.body
+    if (
+        body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+    ):
+        body = body[1:]
+    if len(body) != 1:
+        return False
+    match body[0]:
+        case ast.Pass() | ast.Return(value=None) | ast.Return(value=ast.Constant(value=None)):
+            return True
+        case ast.Expr(value=ast.Constant(value=value)):
+            return value is Ellipsis
+        case ast.Raise(exc=exception):
+            if isinstance(exception, ast.Call):
+                exception = exception.func
+            return isinstance(exception, ast.Name) and exception.id == "NotImplementedError"
+        case _:
+            return False
+
+
+def _reads_dynamic_locals(context: PythonFileContext, body: list[ast.AST]) -> bool:
+    return any(
+        isinstance(node, ast.expr)
+        and (
+            (
+                isinstance(node, ast.Name)
+                and node.id in {"locals", "vars", "eval", "exec"}
+                and context.module_imports.builtin_is_unshadowed(node.id)
+            )
+            or context.module_imports.resolved_symbol(node, sources=frozenset({"builtins"}))
+            in {"locals", "vars", "eval", "exec"}
+        )
+        for node in body
+    )

{sarj_python_lint-1.14.1 → sarj_python_lint-1.14.3}/src/sarj_python_lint/rules/prefer_match_type_dispatch.py

@@ -100,6 +100,7 @@ class PreferMatchTypeDispatch(Rule):
         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.",
+            "A terminating sibling prefix may precede a two-arm if/elif tail whose bodies can fall through. Preserve nested checks inside case bodies rather than moving them into case guards.",
             "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.",
@@ -194,6 +195,36 @@ class PreferMatchTypeDispatch(Rule):
                 expected_count=0,
                 public=True,
             ),
+            RuleExample(
+                example_id="terminal-prefix-with-conditional-tail",
+                title="A terminating prefix and conditional if/elif tail dispatch on the same AST node",
+                outcome=ExampleOutcome.MATCH,
+                scenario="mixed-type-dispatch",
+                files=(
+                    ExampleFile.python(
+                        "app/bindings.py",
+                        "import ast\ndef has_binding(node, name):\n    if isinstance(node, ast.ListComp):\n        return True\n    if isinstance(node, ast.FunctionDef):\n        if name in bindings(node):\n            return True\n    elif isinstance(node, ast.ClassDef):\n        if name in bindings(node):\n            return True\n    return False\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/bindings.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="class-patterns-with-nested-checks",
+                title="Class patterns preserve the nested checks within their case bodies",
+                outcome=ExampleOutcome.NO_MATCH,
+                scenario="mixed-type-dispatch",
+                files=(
+                    ExampleFile.python(
+                        "app/bindings.py",
+                        "import ast\ndef has_binding(node, name):\n    match node:\n        case ast.ListComp():\n            return True\n        case ast.FunctionDef():\n            if name in bindings(node):\n                return True\n        case ast.ClassDef():\n            if name in bindings(node):\n                return True\n    return False\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/bindings.py"),
+                expected_count=0,
+                public=True,
+            ),
         ),
     )
     description: str = documentation.summary
@@ -330,24 +361,23 @@ def _sibling_findings(
     def collect_block(statements: list[ast.stmt]) -> None:
         index = 0
         while index < len(statements):
-            run: list[ast.If] = []
-            cursor = index
-            subject: str | None = None
-            seen: set[str] = set()
-            while cursor < len(statements):
-                statement = statements[cursor]
-                if not isinstance(statement, ast.If) or statement.orelse or not _body_terminates(statement.body):
-                    break
-                branch = _type_branch(statement.test, imports, local_classes, unsafe_bindings)
-                if branch is None or (subject is not None and branch.subject != subject) or bool(seen & branch.types):
-                    break
-                run.append(statement)
-                subject = branch.subject
-                seen.update(branch.types)
-                cursor += 1
+            run = _terminal_prefix(statements, index, imports, local_classes, unsafe_bindings)
+            cursor = index + len(run)
+            if run and cursor < len(statements):
+                tail_statement = statements[cursor]
+                if isinstance(tail_statement, ast.If):
+                    tail = _two_arm_ladder(tail_statement)
+                    if tail and _dispatch([*run, *tail], imports, local_classes, unsafe_bindings) is not None:
+                        run.extend(tail)
+                        cursor += 1
             dispatch = _dispatch(run, imports, local_classes, unsafe_bindings)
             if dispatch is not None:
-                findings.append(_diagnostic(path, code, run[0], dispatch, "terminating isinstance sequence"))
+                shape = (
+                    "terminating isinstance prefix with if/elif tail"
+                    if run[-2].orelse
+                    else "terminating isinstance sequence"
+                )
+                findings.append(_diagnostic(path, code, run[0], dispatch, shape))
             index = max(cursor, index + 1)
 
     for owner in all_nodes:
@@ -356,6 +386,38 @@ def _sibling_findings(
     return findings
 
 
+def _terminal_prefix(
+    statements: list[ast.stmt],
+    index: int,
+    imports: ImportIndex,
+    local_classes: frozenset[str],
+    unsafe_bindings: frozenset[str],
+) -> list[ast.If]:
+    run: list[ast.If] = []
+    subject: str | None = None
+    seen: set[str] = set()
+    for cursor in range(index, len(statements)):
+        statement = statements[cursor]
+        if not isinstance(statement, ast.If) or statement.orelse or not _body_terminates(statement.body):
+            break
+        branch = _type_branch(statement.test, imports, local_classes, unsafe_bindings)
+        if branch is None or (subject is not None and branch.subject != subject) or bool(seen & branch.types):
+            break
+        run.append(statement)
+        subject = branch.subject
+        seen.update(branch.types)
+    return run
+
+
+def _two_arm_ladder(statement: ast.If) -> tuple[ast.If, ast.If] | None:
+    if len(statement.orelse) != 1 or not isinstance(statement.orelse[0], ast.If):
+        return None
+    second = statement.orelse[0]
+    if len(second.orelse) == 1 and isinstance(second.orelse[0], ast.If):
+        return None
+    return statement, second
+
+
 def _dispatch(
     branches: list[ast.If],
     imports: ImportIndex,

{sarj_python_lint-1.14.1 → sarj_python_lint-1.14.3}/src/sarj_python_lint/rules/require_pydantic_for_external_json.py

@@ -324,18 +324,19 @@ def _module_rebound_names(tree: ast.Module) -> frozenset[str]:
 def _suite_rebound_names(statements: list[ast.stmt]) -> frozenset[str]:
     names: set[str] = set()
     for statement in statements:
-        if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            continue
-        if isinstance(statement, ast.ClassDef):
-            names.add(statement.name)
-        elif isinstance(statement, ast.Import | ast.ImportFrom):
-            names.update(alias.asname or alias.name.partition(".")[0] for alias in statement.names)
-        else:
-            names.update(
-                node.id
-                for node in walk_ast(statement)
-                if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store)
-            )
+        match statement:
+            case ast.FunctionDef() | ast.AsyncFunctionDef():
+                continue
+            case ast.ClassDef():
+                names.add(statement.name)
+            case ast.Import() | ast.ImportFrom():
+                names.update(alias.asname or alias.name.partition(".")[0] for alias in statement.names)
+            case _:
+                names.update(
+                    node.id
+                    for node in walk_ast(statement)
+                    if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store)
+                )
     return frozenset(names)