sarj-python-lint 0.81.1__tar.gz → 0.81.3__tar.gz

{sarj_python_lint-0.81.1 → sarj_python_lint-0.81.3}/PKG-INFO

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

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

{sarj_python_lint-0.81.1 → sarj_python_lint-0.81.3}/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.1 → sarj_python_lint-0.81.3}/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.3/src/sarj_python_lint/rules/no_redundant_module_alias_exports.py

@@ -0,0 +1,203 @@
+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,
+    parse_or_none,
+)
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_SYS_SOURCES = frozenset({"sys"})
+
+
+@final
+class NoRedundantModuleAliasExports(Rule):
+    id: str = "no-redundant-module-alias-exports"
+    code: str = "SARJ440"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Do not replace the current module through `sys.modules`.",
+        rationale=(
+            "Replacing the current module mutates import identity at runtime in a way static tools cannot model. "
+            "It makes introspection, reloads, circular imports, state, and monkeypatch behavior surprising."
+        ),
+        remediation=(
+            "Import the canonical path inside maintained code. If a compatibility module is still required, expose "
+            "its supported names with explicit same-name imports grouped by source module."
+        ),
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only module-scope assignments through an unconditional, unshadowed stdlib `sys` import are checked.",
+            "Assignments inside functions, classes, and `TYPE_CHECKING` branches are excluded.",
+            "Literal-key registrations, child-module registrations, method calls, reads, and arbitrary registries are excluded.",
+            "Generated source, malformed source, and stub files (`.pyi`) are outside this rule's scope.",
+            "No autofix is offered because the intended compatibility surface and identity requirements need review.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="current-module-replacement",
+                title="Do not replace a compatibility module at runtime",
+                outcome=ExampleOutcome.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=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="explicit-compatibility-exports",
+                title="Expose the supported compatibility surface explicitly",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "legacy/settings.py",
+                        "from canonical.settings import (\n    Settings as Settings,\n    load as load,\n)\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 "modules" not in source or "__name__" not in source or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        imports = ImportIndex.from_tree(tree, module_scope_only=True)
+        if not imports.builtin_is_unshadowed("__name__"):
+            return []
+        direct_sys_bindings = _direct_sys_bindings(tree)
+        findings = [
+            Diagnostic(
+                path=path,
+                line=target.lineno,
+                col=target.col_offset + 1,
+                code=self.code,
+                message=(
+                    "Do not replace the current module through `sys.modules[__name__]`; expose compatibility names "
+                    "with explicit imports and update maintained callers to the canonical module."
+                ),
+            )
+            for statement in _module_statements(tree.body)
+            for target in _assignment_targets(statement)
+            if _is_current_module_target(target, imports, direct_sys_bindings)
+        ]
+        return sorted(findings, key=lambda finding: (finding.line, finding.col, finding.code))
+
+
+def _direct_sys_bindings(tree: ast.Module) -> frozenset[str]:
+    bindings: set[str] = set()
+    for statement in tree.body:
+        match statement:
+            case ast.Import(names=names):
+                bindings.update(alias.asname or "sys" for alias in names if alias.name == "sys")
+            case ast.ImportFrom(module="sys", level=0, names=names):
+                bindings.update(alias.asname or "modules" for alias in names if alias.name == "modules")
+            case _:
+                pass
+    return frozenset(bindings)
+
+
+def _module_statements(statements: list[ast.stmt]) -> list[ast.stmt]:
+    result: list[ast.stmt] = []
+    pending = list(reversed(statements))
+    while pending:
+        statement = pending.pop()
+        result.append(statement)
+        pending.extend(reversed(_module_control_flow_bodies(statement)))
+    return result
+
+
+def _module_control_flow_bodies(statement: ast.stmt) -> list[ast.stmt]:
+    match statement:
+        case ast.If() if _is_type_checking_guard(statement.test):
+            return list(statement.orelse)
+        case ast.If() | ast.For() | ast.AsyncFor() | ast.While():
+            return [*statement.body, *statement.orelse]
+        case ast.With() | ast.AsyncWith():
+            return list(statement.body)
+        case ast.Try() | ast.TryStar():
+            return [
+                *statement.body,
+                *(nested for handler in statement.handlers for nested in handler.body),
+                *statement.orelse,
+                *statement.finalbody,
+            ]
+        case ast.Match():
+            return [nested for match_case in statement.cases for nested in match_case.body]
+        case _:
+            return []
+
+
+def _assignment_targets(statement: ast.stmt) -> list[ast.expr]:
+    match statement:
+        case ast.Assign(targets=targets):
+            return [nested for target in targets for nested in _nested_targets(target)]
+        case ast.AnnAssign(target=target):
+            return _nested_targets(target)
+        case _:
+            return []
+
+
+def _nested_targets(target: ast.expr) -> list[ast.expr]:
+    if isinstance(target, (ast.Tuple, ast.List)):
+        return [nested for element in target.elts for nested in _nested_targets(element)]
+    return [target]
+
+
+def _is_current_module_target(
+    target: ast.expr,
+    imports: ImportIndex,
+    direct_sys_bindings: frozenset[str],
+) -> bool:
+    match target:
+        case ast.Subscript(
+            value=value,
+            slice=ast.Name(id="__name__", ctx=ast.Load()),
+            ctx=ast.Store(),
+        ):
+            root = value.value if isinstance(value, ast.Attribute) else value
+            return (
+                isinstance(root, ast.Name)
+                and root.id in direct_sys_bindings
+                and imports.resolves(value, sources=_SYS_SOURCES, symbol="modules")
+            )
+        case _:
+            return False
+
+
+def _is_type_checking_guard(node: ast.expr) -> bool:
+    return (isinstance(node, ast.Name) and node.id == "TYPE_CHECKING") or (
+        isinstance(node, ast.Attribute)
+        and isinstance(node.value, ast.Name)
+        and node.value.id in {"typing", "typing_extensions"}
+        and node.attr == "TYPE_CHECKING"
+    )