sarj-python-lint 0.81.0__tar.gz → 0.81.2__tar.gz

{sarj_python_lint-0.81.0 → sarj_python_lint-0.81.2}/PKG-INFO

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

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

{sarj_python_lint-0.81.0 → sarj_python_lint-0.81.2}/src/sarj_python_lint/rules/_registry.py

@@ -59,6 +59,7 @@ from sarj_python_lint.rules.no_random_uuid_in_sql import NoRandomUuidInSql
 from sarj_python_lint.rules.no_raw_connection_in_tests import NoRawConnectionInTests
 from sarj_python_lint.rules.no_raw_source_text_test_oracle import NoRawSourceTextTestOracle
 from sarj_python_lint.rules.no_redundant_literal_description import NoRedundantLiteralDescription
+from sarj_python_lint.rules.no_redundant_module_alias_exports import NoRedundantModuleAliasExports
 from sarj_python_lint.rules.no_repeated_string_literal import NoRepeatedStringLiteral
 from sarj_python_lint.rules.no_repeated_test_body import NoRepeatedTestBody
 from sarj_python_lint.rules.no_restated_comment import NoRestatedComment
@@ -204,6 +205,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RedundantDocstring.id: RedundantDocstring,
         TrailingValueNarration.id: TrailingValueNarration,
         NoRandomUuidInSql.id: NoRandomUuidInSql,
+        NoRedundantModuleAliasExports.id: NoRedundantModuleAliasExports,
         NoHiddenConstructorFallback.id: NoHiddenConstructorFallback,
         NoFileLevelEscapeHatchSuppression.id: NoFileLevelEscapeHatchSuppression,
         NoFastapiOnEvent.id: NoFastapiOnEvent,

{sarj_python_lint-0.81.0 → sarj_python_lint-0.81.2}/src/sarj_python_lint/rules/no_dunder_all.py

@@ -40,7 +40,8 @@ class NoDunderAll(Rule):
         remediation=(
             "Before deleting `__all__`, replace wildcard-import consumers with explicit imports, retain each intended "
             "binding, and prefix implementation-only bindings with `_`. Use self-aliased imports to mark intentional "
-            "re-exports to static tooling."
+            "facade re-exports to static tooling. For a whole-module compatibility alias, replace the entry in "
+            "`sys.modules` and migrate maintained consumers to the canonical path instead of copying every name."
         ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,

sarj_python_lint-0.81.2/src/sarj_python_lint/rules/no_redundant_module_alias_exports.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import ast
+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,
+    parse_or_none,
+)
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_MIN_ALIAS_STATEMENTS = 4
+
+
+@final
+class NoRedundantModuleAliasExports(Rule):
+    id: str = "no-redundant-module-alias-exports"
+    code: str = "SARJ440"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Do not copy names before replacing a compatibility module.",
+        rationale=(
+            "A compatibility module that replaces itself in `sys.modules` already exposes the canonical module. "
+            "Copying every public attribute first duplicates the API surface and invites drift."
+        ),
+        remediation=(
+            "Delete the forwarding assignments and keep the canonical module import plus the final "
+            "`sys.modules[__name__] = alias` replacement. Import the canonical path inside maintained code."
+        ),
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only otherwise-pure compatibility modules with a final, unconditional self-replacement are checked.",
+            "Forwarding must use exact same-name assignments such as `Thing = canonical.Thing`.",
+            "Conditional, nested, computed, annotated, chained, destructured, or mixed-purpose modules are excluded.",
+            "Generated source, malformed source, and stub files (`.pyi`) are outside this rule's scope.",
+            "No autofix is offered because attribute access can have side effects and circular imports require review.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="self-replacing-compatibility-module",
+                title="Remove bindings that the canonical module replacement supersedes",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "legacy/settings.py",
+                        "import sys\n\n"
+                        "from canonical import settings as _canonical\n\n\n"
+                        "Settings = _canonical.Settings\n"
+                        "load = _canonical.load\n"
+                        "sys.modules[__name__] = _canonical\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("legacy/settings.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="pure-module-alias",
+                title="Replace the compatibility module without copying its attributes",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "legacy/settings.py",
+                        "import sys\n\n"
+                        "from canonical import settings as _canonical\n\n\n"
+                        "sys.modules[__name__] = _canonical\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("legacy/settings.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description: str = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if path.suffix != ".py" or "sys.modules" not in source or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        first_forward = _redundant_forward(tree)
+        if first_forward is None:
+            return []
+        return [
+            Diagnostic(
+                path=path,
+                line=first_forward.lineno,
+                col=first_forward.col_offset + 1,
+                code=self.code,
+                severity=Severity.ERROR,
+                message=(
+                    "Delete the forwarding assignments; this compatibility module already replaces itself with "
+                    "the canonical module."
+                ),
+            )
+        ]
+
+
+def _redundant_forward(tree: ast.Module) -> ast.Assign | None:
+    body = list(tree.body)
+    if body and _is_docstring(body[0]):
+        body.pop(0)
+    while body and isinstance(body[0], ast.ImportFrom) and body[0].module == "__future__":
+        body.pop(0)
+    if len(body) < _MIN_ALIAS_STATEMENTS or not _imports_sys(body[0]):
+        return None
+    alias = _canonical_alias(body[1])
+    if alias is None or not _replaces_current_module(body[-1], alias):
+        return None
+    forwards = body[2:-1]
+    if not forwards:
+        return None
+    for statement in forwards:
+        if not _is_same_name_forward(statement, alias):
+            return None
+    return forwards[0] if isinstance(forwards[0], ast.Assign) else None
+
+
+def _is_docstring(statement: ast.stmt) -> bool:
+    return (
+        isinstance(statement, ast.Expr)
+        and isinstance(statement.value, ast.Constant)
+        and isinstance(statement.value.value, str)
+    )
+
+
+def _imports_sys(statement: ast.stmt) -> bool:
+    return (
+        isinstance(statement, ast.Import)
+        and len(statement.names) == 1
+        and statement.names[0].name == "sys"
+        and (statement.names[0].asname is None)
+    )
+
+
+def _canonical_alias(statement: ast.stmt) -> str | None:
+    match statement:
+        case ast.Import(names=[ast.alias(asname=alias)]) if alias is not None:
+            return alias
+        case ast.ImportFrom(module=module, names=[ast.alias(name=name, asname=alias)]) if (
+            module is not None and name != "*" and alias is not None
+        ):
+            return alias
+        case _:
+            return None
+
+
+def _is_same_name_forward(statement: ast.stmt, alias: str) -> bool:
+    match statement:
+        case ast.Assign(
+            targets=[ast.Name(id=target, ctx=ast.Store())],
+            value=ast.Attribute(value=ast.Name(id=owner, ctx=ast.Load()), attr=attribute, ctx=ast.Load()),
+        ):
+            return owner == alias and target == attribute and target not in {"sys", "__name__", alias}
+        case _:
+            return False
+
+
+def _replaces_current_module(statement: ast.stmt, alias: str) -> bool:
+    match statement:
+        case ast.Assign(
+            targets=[
+                ast.Subscript(
+                    value=ast.Attribute(value=ast.Name(id="sys", ctx=ast.Load()), attr="modules", ctx=ast.Load()),
+                    slice=ast.Name(id="__name__", ctx=ast.Load()),
+                    ctx=ast.Store(),
+                )
+            ],
+            value=ast.Name(id=replacement, ctx=ast.Load()),
+        ):
+            return replacement == alias
+        case _:
+            return False

{sarj_python_lint-0.81.0 → sarj_python_lint-0.81.2}/src/sarj_python_lint/rules/prefer_match_type_dispatch.py

@@ -101,6 +101,7 @@ class PreferMatchTypeDispatch(Rule):
         limitations=(
             "Only three or more adjacent, unguarded `isinstance` branches over the same simple name are checked.",
             "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.",
+            "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.",
         ),
         examples=(
@@ -422,8 +423,6 @@ def _body_terminates(body: list[ast.stmt]) -> bool:
             return True
         case ast.If(body=if_body, orelse=else_body):
             return bool(else_body) and _body_terminates(if_body) and _body_terminates(else_body)
-        case ast.With() | ast.AsyncWith():
-            return _body_terminates(last.body)
         case _:
             return False