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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.14.1"
+version = "1.14.2"
 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.2}/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.2/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
+    )