sarj-python-lint 0.84.2__tar.gz → 0.84.3__tar.gz

{sarj_python_lint-0.84.2 → sarj_python_lint-0.84.3}/PKG-INFO

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

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

{sarj_python_lint-0.84.2 → sarj_python_lint-0.84.3}/src/sarj_python_lint/rules/_registry.py

@@ -34,7 +34,7 @@ from sarj_python_lint.rules.no_copied_inherited_docstring import NoCopiedInherit
 from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
     NoCorsWildcardWithCredentials,
 )
-from sarj_python_lint.rules.no_deleted_only_override_parameter import NoDeletedOnlyOverrideParameter
+from sarj_python_lint.rules.no_delete_statement import NoDeleteStatement
 from sarj_python_lint.rules.no_dunder_all import NoDunderAll
 from sarj_python_lint.rules.no_duplicate_dunder_all_entry import NoDuplicateDunderAllEntry
 from sarj_python_lint.rules.no_excessive_cognitive_complexity import NoExcessiveCognitiveComplexity
@@ -77,6 +77,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_value_marker import NoUnusedValueMarker
 from sarj_python_lint.rules.no_vague_annotations import NoVagueAnnotations
 from sarj_python_lint.rules.no_vague_suppression_description import (
     NoVagueSuppressionDescription,
@@ -252,7 +253,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferSelfDocumentingConstant.id: PreferSelfDocumentingConstant,
         NoDuplicateDunderAllEntry.id: NoDuplicateDunderAllEntry,
         NoDunderAll.id: NoDunderAll,
-        NoDeletedOnlyOverrideParameter.id: NoDeletedOnlyOverrideParameter,
+        NoDeleteStatement.id: NoDeleteStatement,
         NoCopiedInheritedDocstring.id: NoCopiedInheritedDocstring,
         RedundantClassDocstring.id: RedundantClassDocstring,
         RedundantModuleDocstring.id: RedundantModuleDocstring,
@@ -264,6 +265,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoRedundantLiteralDescription.id: NoRedundantLiteralDescription,
         NoTypedDocSections.id: NoTypedDocSections,
         NoUnnecessaryDocstring.id: NoUnnecessaryDocstring,
+        NoUnusedValueMarker.id: NoUnusedValueMarker,
         PreferNominalIdTypes.id: PreferNominalIdTypes,
         NoVagueAnnotations.id: NoVagueAnnotations,
         NoUniqueViolationMessageMatch.id: NoUniqueViolationMessageMatch,

sarj_python_lint-0.84.3/src/sarj_python_lint/rules/no_delete_statement.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+    parse_or_none,
+)
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@final
+class NoDeleteStatement(Rule):
+    id = "no-delete-statement"
+    code = "SARJ442"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Avoid `del` statements; prefer constructing an immutable replacement value.",
+        rationale=(
+            "Deleting a name, attribute, or collection entry introduces lifetime or in-place mutation semantics "
+            "that are harder to follow than explicit value construction."
+        ),
+        remediation=(
+            "Remove unused-value deletion markers. Rebuild collections with comprehensions, copies, or immutable "
+            "value helpers such as dataclasses.replace. When an external API or deliberate lifetime boundary "
+            "requires deletion, add an exact SARJ442 suppression on the statement and explain why."
+        ),
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        aliases=("no-deleted-only-override-parameter",),
+        limitations=(
+            "Every authored Python del statement is reported once, regardless of how many targets it contains.",
+            "The rule does not automatically rewrite deletion because the correct immutable replacement depends on ownership and value semantics.",
+            "Generated and vendored files are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="delete-mapping-entry",
+                title="Build a mapping without the removed entry",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/request.py",
+                        "payload = dict(raw_payload)\ndel payload['secret']\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/request.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="immutable-mapping-filter",
+                title="Construct the desired mapping directly",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/request.py",
+                        "payload = {key: value for key, value in raw_payload.items() if key != 'secret'}\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/request.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if "del" not in source or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        source_lines = source.splitlines()
+        return [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                severity=Severity.WARNING,
+                message=(
+                    "`del` introduces mutation or hidden lifetime behavior — construct the desired value "
+                    "immutably, or add an exact SARJ442 suppression explaining why deletion is required."
+                ),
+            )
+            for node in ast.walk(tree)
+            if isinstance(node, ast.Delete) and not is_suppressed(source_lines, node.lineno, self.code)
+        ]

{sarj_python_lint-0.84.2 → sarj_python_lint-0.84.3}/src/sarj_python_lint/rules/no_hidden_constructor_fallback.py

@@ -442,7 +442,6 @@ class _RuntimeConfigResolver:
             and binding.symbol is not None
             and self._is_settings_symbol(binding.module, binding.symbol, seen | {key})
         )
-        del module_path
         self._settings_cache[key] = result
         return result
 

{sarj_python_lint-0.84.2 → sarj_python_lint-0.84.3}/src/sarj_python_lint/rules/no_psycopg_execution_outside_injected_owner.py

@@ -404,7 +404,7 @@ def _function_scopes(tree: ast.Module) -> list[_FunctionScope]:
 
         @override
         def visit_Lambda(self, node: ast.Lambda) -> None:
-            del node
+            return
 
     Collector().visit(tree)
     return scopes
@@ -623,19 +623,19 @@ class _FunctionAnalyzer:
 
             @override
             def visit_Lambda(self, node: ast.Lambda) -> None:
-                del node
+                return
 
             @override
             def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
-                del node
+                return
 
             @override
             def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
-                del node
+                return
 
             @override
             def visit_ClassDef(self, node: ast.ClassDef) -> None:
-                del node
+                return
 
         Visitor().visit(node)
 

sarj_python_lint-0.84.3/src/sarj_python_lint/rules/no_unused_value_marker.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+    parse_or_none,
+)
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@final
+class NoUnusedValueMarker(Rule):
+    id = "no-unused-value-marker"
+    code = "SARJ452"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Do not use standalone assignments to `_` to discard values.",
+        rationale=(
+            "A standalone `_ = value` assignment adds a binding without clarifying intent. A side-effecting call can "
+            "be invoked directly, while an unused parameter should be addressed at its declaration."
+        ),
+        remediation=(
+            "Invoke calls directly instead of assigning their result to `_`. Remove or rename locally owned unused "
+            "values; when an external interface requires the exact unused parameter, put a narrow reasoned linter "
+            "suppression on its declaration."
+        ),
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Plain and annotated assignments whose standalone target is `_` are reported, including chained assignments.",
+            "Unpacking placeholders, loop targets, wildcard imports, and underscore-prefixed names are excluded.",
+            "Generated and vendored files are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="unused-parameter-marker",
+                title="Do not manufacture a use for interface parameters",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/adapter.py",
+                        "def render(root: Path, manifest: Path) -> str:\n    _ = root, manifest\n    return 'ready'\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/adapter.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="discarded-call-result",
+                title="Invoke a call directly when its result is intentionally unused",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/adapter.py",
+                        "_ = refresh_cache()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/adapter.py"),
+                expected_count=1,
+                public=True,
+                scenario="call-result",
+            ),
+            RuleExample(
+                example_id="direct-call",
+                title="Run the call without creating a discard binding",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/adapter.py",
+                        "refresh_cache()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/adapter.py"),
+                expected_count=0,
+                public=True,
+                scenario="call-result",
+            ),
+            RuleExample(
+                example_id="unpacking-placeholder",
+                title="Keep a conventional placeholder inside unpacking",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/adapter.py",
+                        "name, _ = load_pair()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/adapter.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if "_" not in source or "=" not in source or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        source_lines = source.splitlines()
+        return [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                severity=Severity.WARNING,
+                message=(
+                    "standalone assignment to `_` discards a value through an unnecessary binding — invoke calls "
+                    "directly or address unused values at their declaration."
+                ),
+            )
+            for node in ast.walk(tree)
+            if isinstance(node, (ast.Assign, ast.AnnAssign))
+            and _is_unused_value_marker(node)
+            and not is_suppressed(source_lines, node.lineno, self.code)
+        ]
+
+
+def _is_unused_value_marker(node: ast.Assign | ast.AnnAssign) -> bool:
+    if isinstance(node, ast.AnnAssign):
+        return node.value is not None and isinstance(node.target, ast.Name) and node.target.id == "_"
+    return any(isinstance(target, ast.Name) and target.id == "_" for target in node.targets)

sarj_python_lint-0.84.2/src/sarj_python_lint/rules/no_deleted_only_override_parameter.py

@@ -1,257 +0,0 @@
-from __future__ import annotations
-
-import ast
-from pathlib import PurePosixPath
-from typing import TYPE_CHECKING, ClassVar, final
-
-from sarj_python_lint.rule_base import (
-    AutofixPolicy,
-    Diagnostic,
-    ExampleFile,
-    ExampleOutcome,
-    Rule,
-    RuleCategory,
-    RuleDocumentation,
-    RuleExample,
-    Severity,
-    is_suppressed,
-    parse_or_none,
-)
-from sarj_python_lint.rules._paths import is_generated
-
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-_OVERRIDE_MODULES = frozenset({"typing", "typing_extensions"})
-
-
-@final
-class NoDeletedOnlyOverrideParameter(Rule):
-    id = "no-deleted-only-override-parameter"
-    code = "SARJ442"
-    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="Do not use direct deletion as the only reference to an override parameter.",
-        rationale=(
-            "Deleting an otherwise unread override parameter is commonly used as an unused-value marker, but "
-            "`@override` already preserves the interface contract without requiring a synthetic reference."
-        ),
-        remediation=(
-            "Keep the override signature and remove the deletion marker. If deletion intentionally shortens the "
-            "reference lifetime, retain it with an exact suppression that explains the lifetime boundary."
-        ),
-        category=RuleCategory.STYLE,
-        autofix=AutofixPolicy.NONE,
-        limitations=(
-            "Only direct methods of module-level classes decorated by a proven runtime import of typing.override or typing_extensions.override are checked.",
-            "A parameter is reported only when every occurrence in the method is a direct bare-name deletion; any load, rebinding, nested occurrence, attribute deletion, or subscription deletion excludes it.",
-            "Removing a deletion can change reference lifetime, finalization, frame tracing, or locals() visibility, so the rule has no autofix and supports an exact reasoned suppression.",
-            "Generated files are excluded.",
-        ),
-        examples=(
-            RuleExample(
-                example_id="override-parameter-delete-marker",
-                title="Remove a deletion used only as an override parameter marker",
-                outcome=ExampleOutcome.MATCH,
-                files=(
-                    ExampleFile.python(
-                        "app/handler.py",
-                        "from typing import override\n\n"
-                        "class Handler(BaseHandler):\n"
-                        "    @override\n"
-                        "    def handle(self, request: Request) -> None:\n"
-                        "        del request\n"
-                        "        emit_ready()\n",
-                    ),
-                ),
-                focus_path=PurePosixPath("app/handler.py"),
-                expected_count=1,
-                public=True,
-            ),
-            RuleExample(
-                example_id="override-uses-parameter",
-                title="Keep an override parameter that contributes to behavior",
-                outcome=ExampleOutcome.NO_MATCH,
-                files=(
-                    ExampleFile.python(
-                        "app/handler.py",
-                        "from typing import override\n\n"
-                        "class Handler(BaseHandler):\n"
-                        "    @override\n"
-                        "    def handle(self, request: Request) -> None:\n"
-                        "        dispatch(request)\n",
-                    ),
-                ),
-                focus_path=PurePosixPath("app/handler.py"),
-                expected_count=0,
-                public=True,
-            ),
-        ),
-    )
-    description = documentation.summary
-
-    def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if "del" not in source or "override" not in source or is_generated(path, source):
-            return []
-        tree = parse_or_none(path, source)
-        if tree is None:
-            return []
-        direct_aliases, module_aliases = _proven_override_imports(tree)
-        if not direct_aliases and not module_aliases:
-            return []
-        source_lines = source.splitlines()
-        diagnostics: list[Diagnostic] = []
-        for statement in tree.body:
-            if not isinstance(statement, ast.ClassDef):
-                continue
-            class_bound = _class_bound_names(statement)
-            available_direct = direct_aliases - class_bound
-            available_modules = module_aliases - class_bound
-            for method in statement.body:
-                if not isinstance(method, (ast.FunctionDef, ast.AsyncFunctionDef)) or not _is_override(
-                    method, available_direct, available_modules
-                ):
-                    continue
-                diagnostics.extend(_method_diagnostics(path, source_lines, method))
-        diagnostics.sort(key=lambda item: (item.line, item.col))
-        return diagnostics
-
-
-def _proven_override_imports(tree: ast.Module) -> tuple[frozenset[str], frozenset[str]]:
-    direct: set[str] = set()
-    modules: set[str] = set()
-    conflicting: set[str] = set()
-    for statement in tree.body:
-        if isinstance(statement, ast.ImportFrom) and statement.module in _OVERRIDE_MODULES:
-            _collect_override_aliases(statement, direct, conflicting)
-            continue
-        if isinstance(statement, ast.Import):
-            for alias in statement.names:
-                name = alias.asname or alias.name.split(".")[0]
-                if alias.name in _OVERRIDE_MODULES and name not in modules:
-                    modules.add(name)
-                else:
-                    conflicting.add(name)
-            continue
-        conflicting.update(_statement_bound_names(statement))
-    return frozenset(direct - conflicting), frozenset(modules - conflicting)
-
-
-def _statement_bound_names(statement: ast.stmt) -> set[str]:
-    names: set[str] = set()
-    if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
-        names.add(statement.name)
-    for node in ast.walk(statement):
-        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
-            names.add(node.id)
-        elif isinstance(node, ast.alias):
-            names.add(node.asname or node.name.split(".")[0])
-    return names
-
-
-def _class_bound_names(node: ast.ClassDef) -> frozenset[str]:
-    names: set[str] = set()
-    for statement in node.body:
-        if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            names.add(statement.name)
-        elif not isinstance(statement, ast.ClassDef):
-            names.update(_statement_bound_names(statement))
-    return frozenset(names)
-
-
-def _is_override(
-    method: ast.FunctionDef | ast.AsyncFunctionDef,
-    direct_aliases: frozenset[str],
-    module_aliases: frozenset[str],
-) -> bool:
-    for decorator in method.decorator_list:
-        if isinstance(decorator, ast.Name) and decorator.id in direct_aliases:
-            return True
-        if (
-            isinstance(decorator, ast.Attribute)
-            and decorator.attr == "override"
-            and isinstance(decorator.value, ast.Name)
-            and decorator.value.id in module_aliases
-        ):
-            return True
-    return False
-
-
-def _method_diagnostics(
-    path: Path,
-    source_lines: list[str],
-    method: ast.FunctionDef | ast.AsyncFunctionDef,
-) -> list[Diagnostic]:
-    delete_targets = _direct_delete_targets(method.body)
-    parameters = {
-        argument.arg
-        for argument in (
-            *method.args.posonlyargs,
-            *method.args.args,
-            *method.args.kwonlyargs,
-            *(() if method.args.vararg is None else (method.args.vararg,)),
-            *(() if method.args.kwarg is None else (method.args.kwarg,)),
-        )
-    }
-    direct_nodes = {id(node) for nodes in delete_targets.values() for node in nodes}
-    other_occurrences = {
-        node.id
-        for statement in method.body
-        for node in ast.walk(statement)
-        if isinstance(node, ast.Name) and id(node) not in direct_nodes
-    }
-    diagnostics: list[Diagnostic] = []
-    for name in sorted(parameters.intersection(delete_targets) - other_occurrences):
-        target = min(delete_targets[name], key=lambda node: (node.lineno, node.col_offset))
-        if is_suppressed(source_lines, target.lineno, NoDeletedOnlyOverrideParameter.code):
-            continue
-        diagnostics.append(
-            Diagnostic(
-                path=path,
-                line=target.lineno,
-                col=target.col_offset + 1,
-                code=NoDeletedOnlyOverrideParameter.code,
-                severity=Severity.WARNING,
-                message=(
-                    f"override parameter `{name}` is referenced only by direct deletion — remove the unused-marker "
-                    "deletion, or suppress this warning with a reason when early reference release is intentional."
-                ),
-            )
-        )
-    return diagnostics
-
-
-def _direct_delete_targets(statements: list[ast.stmt]) -> dict[str, list[ast.Name]]:
-    targets: dict[str, list[ast.Name]] = {}
-
-    def visit(node: ast.AST) -> None:
-        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)):
-            return
-        if isinstance(node, ast.Delete):
-            for target in node.targets:
-                for name in _bare_delete_names(target):
-                    targets.setdefault(name.id, []).append(name)
-        for child in ast.iter_child_nodes(node):
-            visit(child)
-
-    for statement in statements:
-        visit(statement)
-    return targets
-
-
-def _bare_delete_names(target: ast.expr) -> list[ast.Name]:
-    if isinstance(target, ast.Name):
-        return [target]
-    if isinstance(target, (ast.Tuple, ast.List)):
-        return [name for item in target.elts for name in _bare_delete_names(item)]
-    return []
-
-
-def _collect_override_aliases(statement: ast.ImportFrom, direct: set[str], conflicting: set[str]) -> None:
-    for alias in statement.names:
-        name = alias.asname or alias.name
-        if alias.name == "override" and name not in direct:
-            direct.add(name)
-        else:
-            conflicting.add(name)