sarj-python-lint 1.7.1__tar.gz → 1.7.3__tar.gz

{sarj_python_lint-1.7.1 → sarj_python_lint-1.7.3}/PKG-INFO

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

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

{sarj_python_lint-1.7.1 → sarj_python_lint-1.7.3}/src/sarj_python_lint/rules/no_service_behavior_in_settings.py

@@ -17,7 +17,6 @@ from sarj_python_lint.rule_base import (
     Severity,
     is_suppressed,
 )
-from sarj_python_lint.rules._ast_index import walk as walk_ast
 from sarj_python_lint.rules._paths import is_test_path, is_test_support_path
 
 
@@ -66,7 +65,7 @@ class NoServiceBehaviorInSettings(Rule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Only direct module classes named *Settings, *Config, *Configuration, or *Options are checked.",
-            "A finding requires a typed collaborator field and an ordinary public method that calls that field; pure computations, properties, validators, serializers, factories, generated files, and tests are excluded.",
+            "A finding requires a typed collaborator field and an ordinary public method that calls that field; pure computations, properties, validators, serializers, factories, generated files, and tests are excluded. Nested scopes, containers of collaborators, class objects, and methods that rebind self are not inferred.",
             "The rule does not require every data object to use a particular record library and does not infer behavior from a filename alone.",
         ),
         examples=(
@@ -180,10 +179,19 @@ def _collaborator_fields(node: ast.ClassDef) -> frozenset[str]:
 def _is_collaborator_annotation(annotation: ast.expr | None) -> bool:
     if annotation is None:
         return False
-    return any(
-        _COLLABORATOR_RE.search(_dotted_tail(candidate) or "") is not None
-        for candidate in walk_ast(annotation)
-        if isinstance(candidate, (ast.Name, ast.Attribute))
+    if isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+        return _is_collaborator_annotation(annotation.left) or _is_collaborator_annotation(annotation.right)
+    if isinstance(annotation, ast.Subscript):
+        wrapper = _dotted_tail(annotation.value)
+        if wrapper in {"Optional", "Union"}:
+            members = annotation.slice.elts if isinstance(annotation.slice, ast.Tuple) else [annotation.slice]
+            return any(_is_collaborator_annotation(member) for member in members)
+        if wrapper == "Annotated" and isinstance(annotation.slice, ast.Tuple) and annotation.slice.elts:
+            return _is_collaborator_annotation(annotation.slice.elts[0])
+        return _is_collaborator_annotation(annotation.value)
+    return (
+        isinstance(annotation, (ast.Name, ast.Attribute))
+        and _COLLABORATOR_RE.search(_dotted_tail(annotation) or "") is not None
     )
 
 
@@ -198,9 +206,22 @@ def _is_behavioral_method(method: ast.FunctionDef | ast.AsyncFunctionDef) -> boo
 
 
 def _calls_collaborator(method: ast.FunctionDef | ast.AsyncFunctionDef, fields: frozenset[str]) -> bool:
+    nodes: list[ast.AST] = []
+    pending: list[ast.AST] = list(method.body)
+    while pending:
+        node = pending.pop()
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)):
+            continue
+        nodes.append(node)
+        pending.extend(ast.iter_child_nodes(node))
+    if any(
+        isinstance(node, ast.Name) and node.id == "self" and isinstance(node.ctx, (ast.Store, ast.Del))
+        for node in nodes
+    ):
+        return False
     return any(
         (field := _self_field(call.func)) is not None and field in fields
-        for call in walk_ast(method)
+        for call in nodes
         if isinstance(call, ast.Call)
     )
 

{sarj_python_lint-1.7.1 → sarj_python_lint-1.7.3}/src/sarj_python_lint/rules/no_unnecessary_docstring.py

@@ -219,14 +219,14 @@ def _is_syntax_required(owner: ast.Module | ast.ClassDef | ast.FunctionDef | ast
 def _owner_keys(tree: ast.Module) -> dict[int, str]:
     keys = {id(tree): "__doc__"}
 
-    def visit(body: list[ast.stmt], prefix: tuple[str, ...]) -> None:
-        for statement in body:
-            if isinstance(statement, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
-                qualified = (*prefix, statement.name)
-                keys[id(statement)] = ".".join(qualified)
-                visit(statement.body, qualified)
-
-    visit(tree.body, ())
+    def visit(node: ast.AST, prefix: tuple[str, ...]) -> None:
+        if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+            prefix = (*prefix, node.name)
+            keys[id(node)] = ".".join(prefix)
+        for child in ast.iter_child_nodes(node):
+            visit(child, prefix)
+
+    visit(tree, ())
     return keys
 
 

{sarj_python_lint-1.7.1 → sarj_python_lint-1.7.3}/src/sarj_python_lint/rules/prefer_injected_dependency_over_monkeypatch.py

@@ -63,6 +63,36 @@ class PreferInjectedDependencyOverMonkeypatch(Rule):
             "A nested function that captures a monkeypatch handle from an outer scope is not inferred.",
         ),
         examples=(
+            RuleExample(
+                example_id="patched-constructor-failure",
+                title="Avoid replacing the SDK constructor lookup",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_adapter.py",
+                        "import pytest\nfrom unittest.mock import patch\ndef test_constructor_failure():\n    with patch('transport.Client', side_effect=ConnectionError):\n        with pytest.raises(AdapterUnavailable):\n            open_adapter()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_adapter.py"),
+                expected_count=1,
+                public=True,
+                scenario="constructor-failure",
+            ),
+            RuleExample(
+                example_id="injected-constructor-failure",
+                title="Inject a factory to exercise constructor failure",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_adapter.py",
+                        "import pytest\ndef unavailable_client():\n    raise ConnectionError\ndef test_constructor_failure():\n    with pytest.raises(AdapterUnavailable):\n        open_adapter(client_factory=unavailable_client)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_adapter.py"),
+                expected_count=0,
+                public=True,
+                scenario="constructor-failure",
+            ),
             RuleExample(
                 example_id="patched-first-party-collaborator",
                 title="Test replaces an application collaborator",

{sarj_python_lint-1.7.1 → sarj_python_lint-1.7.3}/src/sarj_python_lint/rules/prefer_monkeypatch_for_process_state_in_test.py

@@ -60,12 +60,43 @@ class PreferMonkeypatchForProcessStateInTest(Rule):
         category=RuleCategory.TESTING,
         autofix=AutofixPolicy.NONE,
         limitations=(
+            "Teardown after a single direct yield in a module-level, import-proven pytest or pytest-asyncio fixture is excluded: registering undo operations during cleanup can restore the temporary state. Nested fixtures, conditional/delegated yields and out-of-line cleanup ownership are not inferred.",
             "Only maintained test paths are analyzed; generated files, production code, and module/class bootstrap mutations are excluded.",
             "The rule covers os.chdir, sys.path.insert(0, ...), and direct sys.modules set, delete, or unused pop operations with an equivalent pytest restoring helper.",
             "Environment variables remain owned by Ruff TID251/B003; argv, locale, timezone, warning filters, and process APIs without an equivalent helper are outside this rule.",
             "Imports and import aliases are resolved conservatively. Indirect container aliases and dynamically selected modules are not inferred.",
         ),
         examples=(
+            RuleExample(
+                example_id="fixture-cleanup-unscoped",
+                title="Restore setup mutations even when setup fails",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_plugins.py",
+                        "import sys\nimport pytest\n@pytest.fixture\ndef fresh_plugin():\n    sys.modules.pop('temporary_plugin', None)\n    yield\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_plugins.py"),
+                expected_count=1,
+                public=True,
+                scenario="fixture-cleanup",
+            ),
+            RuleExample(
+                example_id="yield-fixture-cleanup",
+                title="Do not undo fixture teardown",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_plugins.py",
+                        "import sys\nimport pytest\n@pytest.fixture\ndef fresh_plugin():\n    yield\n    sys.modules.pop('temporary_plugin', None)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_plugins.py"),
+                expected_count=0,
+                public=True,
+                scenario="fixture-cleanup",
+            ),
             RuleExample(
                 example_id="direct-module-registry-mutation",
                 title="Test installs a module without guaranteed restoration",
@@ -112,7 +143,7 @@ class PreferMonkeypatchForProcessStateInTest(Rule):
         mutations = [
             mutation
             for function in _functions(tree, node_index=context.node_index)
-            for mutation in _function_mutations(function, module_imports)
+            for mutation in _function_mutations(function, module_imports, module_level=function in tree.body)
         ]
         diagnostics = [
             Diagnostic(
@@ -143,6 +174,8 @@ def _functions(
 def _function_mutations(
     function: ast.FunctionDef | ast.AsyncFunctionDef,
     module_imports: ImportIndex,
+    *,
+    module_level: bool,
 ) -> list[_Mutation]:
     local_tree = ast.Module(body=function.body, type_ignores=[])
     local_imports = ImportIndex.from_tree(local_tree)
@@ -155,9 +188,33 @@ def _function_mutations(
             continue
         mutations.append(mutation)
     restored = _restored_mutations(nodes, mutations, module_imports, local_imports)
+    if module_level:
+        restored.update(_fixture_teardown_nodes(function, nodes, module_imports))
     return [mutation for mutation in mutations if mutation.node not in restored]
 
 
+def _fixture_teardown_nodes(
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    nodes: tuple[ast.AST, ...],
+    module_imports: ImportIndex,
+) -> set[ast.AST]:
+    if not any(
+        module_imports.resolves(
+            decorator.func if isinstance(decorator, ast.Call) else decorator,
+            sources=frozenset({"pytest", "pytest_asyncio"}),
+            symbol="fixture",
+        )
+        for decorator in function.decorator_list
+    ):
+        return set()
+    if sum(isinstance(node, ast.Yield | ast.YieldFrom) for node in nodes) != 1:
+        return set()
+    for index, statement in enumerate(function.body):
+        if isinstance(statement, ast.Expr) and isinstance(statement.value, ast.Yield):
+            return set(_descendants(function.body[index + 1 :]))
+    return set()
+
+
 def _lexical_nodes(function: ast.FunctionDef | ast.AsyncFunctionDef) -> Iterator[ast.AST]:
     stack: list[ast.AST] = [node for node in reversed(function.body) if not isinstance(node, _SCOPE_NODES)]
     while stack:

{sarj_python_lint-1.7.1 → sarj_python_lint-1.7.3}/src/sarj_python_lint/rules/require_explicit_psycopg_transaction.py

@@ -55,7 +55,7 @@ class RequireExplicitPsycopgTransaction(Rule):
             "Inspects literal SQL, simple local/module constants, and psycopg.sql.SQL wrappers. Dynamic SQL and unsupported SQL syntax are excluded.",
             "A locking SELECT followed by a write on the same connection outside transaction() is reported; a single statement containing a mutation is treated as atomic. Multiple writes on a reachable local path are a warning because independent writes can be intentional.",
             "Loops, exception handlers, match statements, comprehensions, and nested closures are not analyzed as execution paths. Manual BEGIN/commit protocols are not inferred. Tests, support fixtures, and generated files are excluded.",
-            "The rule cannot prove isolation level, database constraints, or application-level atomicity; fault-injection integration tests remain necessary.",
+            "Non-autocommit connections can already provide implicit transaction protection. A manual commit is not itself evidence of a defect or of safety in autocommit mode; document the proven connection configuration when retaining that protocol. The rule cannot prove isolation level, database constraints, or application-level atomicity; fault-injection integration tests remain necessary.",
         ),
         examples=(
             RuleExample(