sarj-python-lint 1.28.1__tar.gz → 1.28.3__tar.gz

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.28.1
+Version: 1.28.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/
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
 Requires-Dist: packaging==26.3
 Requires-Dist: ruff>=0.16.10
-Requires-Dist: sarj-rule-contracts==0.2.2
+Requires-Dist: sarj-rule-contracts==0.2.3
 Requires-Dist: sqlglot==30.19.0
 Requires-Dist: typer==0.27.2
 Description-Content-Type: text/markdown

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.28.1"
+version = "1.28.3"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -15,7 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
-dependencies = ["sarj-rule-contracts==0.2.2", "packaging==26.3", "ruff>=0.16.10", "sqlglot==30.19.0", "typer==0.27.2"]
+dependencies = ["sarj-rule-contracts==0.2.3", "packaging==26.3", "ruff>=0.16.10", "sqlglot==30.19.0", "typer==0.27.2"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/_file_context.py

@@ -57,6 +57,10 @@ class PythonFileContext:
     def nodes[NodeT: ast.AST](self, *types: type[NodeT]) -> list[NodeT]:
         return [node for node in self.node_index.query(types) if isinstance(node, types)]
 
+    @cached_property
+    def has_wildcard_import(self) -> bool:
+        return any(alias.name == "*" for node in self.nodes(ast.ImportFrom) for alias in node.names)
+
     @property
     def parents(self) -> Mapping[ast.AST, ast.AST]:
         return self.node_index.parents

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/rules/_resource_provenance.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import ast
 from collections import defaultdict
+from functools import cached_property
 from typing import TYPE_CHECKING, final
 
 
@@ -44,6 +45,15 @@ class ResourceProvenance:
                 if root is not None:
                     self.mutated.add(root)
 
+    @cached_property
+    def builtin_namespace_untouched(self) -> bool:
+        return not any(
+            (isinstance(node, ast.Import) and any(alias.name == "builtins" for alias in node.names))
+            or (isinstance(node, ast.ImportFrom) and node.module == "builtins")
+            or (isinstance(node, ast.Name) and node.id == "__builtins__")
+            for node in self.context.nodes(ast.Import, ast.ImportFrom, ast.Name)
+        )
+
     def scope(self, node: ast.AST) -> ast.AST | None:
         parent = self.context.parents.get(node)
         while parent is not None and not isinstance(parent, _SCOPES):

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/rules/duplicate_adjacent_exception_handler.py

@@ -59,8 +59,8 @@ class DuplicateAdjacentExceptionHandler(ProjectRule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Only ordinary try statements with adjacent handlers, identical exception bindings, executable ASTs and comments are compared; exception groups and bare re-raise/pass handlers are excluded.",
-            "Handler types must be simple names or tuples of unshadowed builtin or statically resolved first-party Exception subclasses, with unconditional stable declarations/imports.",
-            "Dynamic namespace access, unknown external exception classes, generated/vendor sources, different comments, and intervening handlers are excluded. No autofix preserves intentional translation seams.",
+            "Handler types must be simple names or tuples of unshadowed builtin or statically resolved first-party Exception subclasses, with stable declarations/imports initialized before the enclosing module statement. Declarations after a callable's definition are unresolved and excluded.",
+            "Dynamic or explicit builtin namespace access, unknown external exception classes, generated/vendor sources, different comments, and intervening handlers are excluded. Unseen external builtin mutations are not resolved. No autofix preserves intentional translation seams.",
         ),
         examples=tuple(
             RuleExample(
@@ -88,6 +88,8 @@ class DuplicateAdjacentExceptionHandler(ProjectRule):
         project = context.session.project or ProjectIndexSet.single(context.path, context.source)
         unit = project.unit_or_source(context.path, context.source, tree)
         provenance = ResourceProvenance(context)
+        if not provenance.builtin_namespace_untouched:
+            return []
         comments = scan_comments(context.source)
         findings: list[Diagnostic] = []
         for statement in context.nodes(ast.Try):
@@ -176,7 +178,11 @@ def _first_party_exception(
     from sarj_python_lint._file_context import PythonFileContext  # ruff: ignore[import-outside-top-level] -- defer until the rule registry finishes loading.
 
     binding = provenance.binding(expression.id, expression)
-    if not isinstance(binding, ast.ClassDef | ast.alias) or unit is None:
+    if (
+        not isinstance(binding, ast.ClassDef | ast.alias)
+        or unit is None
+        or not _initialized_before(binding, expression, context)
+    ):
         return False
     if isinstance(binding, ast.alias):
         statement = context.parents.get(binding)
@@ -200,6 +206,7 @@ def _first_party_exception(
     )
     return (
         declaration is not None
+        and definition_provenance.builtin_namespace_untouched
         and stable_class(definition_context, declaration, definition_provenance)
         and len(declaration.bases) == 1
         and _safe_types(
@@ -211,3 +218,16 @@ def _first_party_exception(
             seen=seen | {summary.symbol},
         )
     )
+
+
+def _initialized_before(binding: ast.ClassDef | ast.alias, read: ast.Name, context: PythonFileContext) -> bool:
+    declaration = context.parents.get(binding) if isinstance(binding, ast.alias) else binding
+    boundary: ast.AST = read
+    while (parent := context.parents.get(boundary)) is not None and parent is not context.tree:
+        boundary = parent
+    return (
+        isinstance(declaration, ast.stmt)
+        and context.parents.get(declaration) is context.tree
+        and isinstance(boundary, ast.stmt)
+        and (declaration.end_lineno or declaration.lineno) < boundary.lineno
+    )

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/rules/no_conftest_test_module_import.py

@@ -131,11 +131,12 @@ def _pytest_plugin_test_targets(tree: ast.Module) -> list[_PluginTarget]:
     for statement in tree.body:
         value: ast.expr | None = None
         match statement:
-            case (
-                ast.Assign(targets=[ast.Name(id="pytest_plugins")])
-                | ast.AnnAssign(target=ast.Name(id="pytest_plugins"))
+            case ast.Assign(targets=targets) if any(
+                isinstance(target, ast.Name) and target.id == "pytest_plugins" for target in targets
             ):
                 value = statement.value
+            case ast.AnnAssign(target=ast.Name(id="pytest_plugins")):
+                value = statement.value
             case _:
                 continue
         findings.extend(

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/rules/opaque_parametrize_case_needs_id.py

@@ -57,10 +57,10 @@ class OpaqueParametrizeCaseNeedsId(Rule):
     code: str = "SARJ042"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary="Opaque static pytest parameter cases rely on argument-name-and-index fallback IDs.",
-        rationale="Fallback IDs such as `payload0` are hard to diagnose and silently change when the table is reordered.",
+        summary="Opaque static pytest parameter cases lack table-local semantic IDs.",
+        rationale="Without a semantic naming owner, fallback IDs such as `payload0` are hard to diagnose and silently change when the table is reordered.",
         remediation=(
-            "Give each opaque row a semantic `pytest.param(..., id=...)`, or use a semantic callable `ids=` when one "
+            "Check the owning pytest_make_parametrize_id hook before adding IDs; reuse an existing semantic naming owner. Otherwise give each opaque row a semantic `pytest.param(..., id=...)`, or use a semantic callable `ids=` when one "
             "mapping applies to the entire table."
         ),
         category=RuleCategory.TESTING,
@@ -129,10 +129,12 @@ class OpaqueParametrizeCaseNeedsId(Rule):
 
 
 def _message(count: int) -> str:
-    subject = "case relies" if count == 1 else "cases rely"
+    subject = "case lacks" if count == 1 else "cases lack"
     return (
-        f"{count} {subject} on pytest's argument-name-and-index fallback (for example, `payload0`), which renumbers "
-        'when rows are reordered. Add semantic `pytest.param(..., id="...")` values or a semantic callable `ids=`.'
+        f"{count} {subject} a table-local semantic ID. Check the owning `pytest_make_parametrize_id` hook before "
+        'adding IDs; reuse an existing semantic naming owner, or add semantic `pytest.param(..., id="...")` values '
+        "or a semantic callable `ids=`. Without a semantic ID, pytest may use an argument-name-and-index fallback "
+        "(for example, `payload0`), which renumbers when rows are reordered."
     )
 
 

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/rules/prefer_match_exception_dispatch.py

@@ -177,7 +177,7 @@ class PreferMatchExceptionDispatch(Rule):
         imports = context.imports
         if (
             not imports.builtin_is_unshadowed("isinstance")
-            or _has_wildcard_import(tree, node_index=context.node_index)
+            or context.has_wildcard_import
             or _has_local_import(tree, node_index=context.node_index)
         ):
             return []
@@ -412,13 +412,6 @@ def _body_terminates(body: list[ast.stmt]) -> bool:
             return False
 
 
-def _has_wildcard_import(tree: ast.Module, *, node_index: NodeIndex | None = None) -> bool:
-    return any(
-        isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names)
-        for node in walk_ast(tree, index=node_index)
-    )
-
-
 def _has_local_import(tree: ast.Module, *, node_index: NodeIndex | None = None) -> bool:
     module_imports = {id(statement) for statement in tree.body if isinstance(statement, (ast.Import, ast.ImportFrom))}
     return any(

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/rules/prefer_namedtuple_over_tuple_return.py

@@ -16,12 +16,10 @@ from sarj_python_lint.rule_base import (
     Severity,
     parse_or_none,
 )
-from sarj_python_lint.rules._ast_index import walk as walk_ast
 
 
 if TYPE_CHECKING:
     from sarj_python_lint._file_context import PythonFileContext
-    from sarj_python_lint.rules._ast_index import NodeIndex
     from sarj_python_lint.rules._imports import ImportIndex
 
 
@@ -101,7 +99,7 @@ class PreferNamedtupleOverTupleReturn(Rule):
         if context.generated or _is_documentation_path(path):
             return []
         tree = context.tree
-        if tree is None or _has_wildcard_import(tree, node_index=context.node_index):
+        if tree is None or context.has_wildcard_import:
             return []
         imports = context.imports
         diagnostics: list[Diagnostic] = []
@@ -127,13 +125,6 @@ def _is_documentation_path(path: Path) -> bool:
     return any(part.lower() in _DOCUMENTATION_DIR_NAMES for part in path.parts)
 
 
-def _has_wildcard_import(tree: ast.Module, *, node_index: NodeIndex | None = None) -> bool:
-    return any(
-        isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names)
-        for node in walk_ast(tree, index=node_index)
-    )
-
-
 def _is_public_record_tuple(annotation: ast.expr, imports: ImportIndex) -> bool:
     annotation = _unwrap_return_annotation(annotation, imports)
     if not isinstance(annotation, ast.Subscript) or not isinstance(annotation.slice, ast.Tuple):

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/rules/prefer_nominal_id_types.py

@@ -27,7 +27,6 @@ if TYPE_CHECKING:
     from pathlib import Path
 
     from sarj_python_lint._file_context import PythonFileContext
-    from sarj_python_lint.rules._ast_index import NodeIndex
     from sarj_python_lint.rules._imports import ImportIndex
 
 
@@ -221,7 +220,7 @@ class PreferNominalIdTypes(Rule):
         if _is_excluded_path(path) or context.generated:
             return []
         tree = context.tree
-        if tree is None or _has_wildcard_import(tree, node_index=context.node_index):
+        if tree is None or context.has_wildcard_import:
             return []
 
         imports = context.imports
@@ -311,13 +310,6 @@ def _is_excluded_path(path: Path) -> bool:
     )
 
 
-def _has_wildcard_import(tree: ast.Module, *, node_index: NodeIndex | None = None) -> bool:
-    return any(
-        isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names)
-        for node in walk_ast(tree, index=node_index)
-    )
-
-
 def _boundary_nodes(
     tree: ast.Module,
     imports: ImportIndex,

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/rules/prefer_non_nullable_collection.py

@@ -23,7 +23,6 @@ if TYPE_CHECKING:
     from collections.abc import Iterator
 
     from sarj_python_lint._file_context import PythonFileContext
-    from sarj_python_lint.rules._ast_index import NodeIndex
     from sarj_python_lint.rules._imports import ImportIndex
 
 
@@ -99,7 +98,7 @@ class PreferNonNullableCollection(Rule):
         if is_test_path(path) or is_test_support_path(path) or context.generated:
             return []
         tree = context.tree
-        if tree is None or _has_wildcard_import(tree, node_index=context.node_index):
+        if tree is None or context.has_wildcard_import:
             return []
 
         imports = context.imports
@@ -125,13 +124,6 @@ class PreferNonNullableCollection(Rule):
         return sorted(diagnostics, key=lambda diagnostic: (diagnostic.line, diagnostic.col))
 
 
-def _has_wildcard_import(tree: ast.Module, *, node_index: NodeIndex | None = None) -> bool:
-    return any(
-        isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names)
-        for node in walk_ast(tree, index=node_index)
-    )
-
-
 def _eligible_functions(tree: ast.Module, imports: ImportIndex) -> list[ast.FunctionDef | ast.AsyncFunctionDef]:
     functions: list[ast.FunctionDef | ast.AsyncFunctionDef] = []
     for statement in tree.body:

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/rules/redundant_test_constructor_forwarder.py

@@ -61,7 +61,10 @@ class RedundantTestConstructorForwarder(ProjectRule):
                 example_id=name,
                 title=title,
                 outcome=outcome,
-                files=(ExampleFile.python("tests/test_record.py", source),),
+                files=(
+                    ExampleFile.python("tests/__init__.py", "# Example test package.\n"),
+                    ExampleFile.python("tests/test_record.py", source),
+                ),
                 focus_path=PurePosixPath("tests/test_record.py"),
                 expected_count=count,
                 public=True,

{sarj_python_lint-1.28.1 → sarj_python_lint-1.28.3}/src/sarj_python_lint/rules/repeated_unimplemented_test_contract.py

@@ -60,6 +60,7 @@ class RepeatedUnimplementedTestContract(ProjectRule):
                 title="Two test fakes repeat one unconfigured operation",
                 outcome=ExampleOutcome.MATCH,
                 files=(
+                    ExampleFile.python("tests/__init__.py", "# Example test package.\n"),
                     ExampleFile.python(
                         "tests/test_store.py",
                         "from abc import ABC, abstractmethod\nclass Store(ABC):\n    @abstractmethod\n    def read(self, key: str) -> str:\n        pass\nclass First(Store):\n    def read(self, key: str) -> str:\n        raise NotImplementedError\nclass Second(Store):\n    def read(self, key: str) -> str:\n        raise NotImplementedError\n",
@@ -74,6 +75,7 @@ class RepeatedUnimplementedTestContract(ProjectRule):
                 title="Configured fake behavior belongs to the leaf",
                 outcome=ExampleOutcome.NO_MATCH,
                 files=(
+                    ExampleFile.python("tests/__init__.py", "# Example test package.\n"),
                     ExampleFile.python(
                         "tests/test_store.py",
                         "from abc import ABC, abstractmethod\nclass Store(ABC):\n    @abstractmethod\n    def read(self, key: str) -> str:\n        pass\nclass First(Store):\n    def read(self, key: str) -> str:\n        raise NotImplementedError\nclass Second(Store):\n    def read(self, key: str) -> str:\n        return key\n",