sarj-python-lint 1.24.0__tar.gz → 1.25.1__tar.gz

{sarj_python_lint-1.24.0 → sarj_python_lint-1.25.1}/PKG-INFO

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

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

{sarj_python_lint-1.24.0 → sarj_python_lint-1.25.1}/src/sarj_python_lint/rules/prefer_collection_comprehension.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import ast
+from collections import defaultdict
 from dataclasses import dataclass
 from enum import StrEnum
 from io import StringIO
@@ -21,11 +22,11 @@ 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._ast_index import children, walk as walk_ast
 
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterable, Iterator
 
     from sarj_python_lint._file_context import PythonFileContext
     from sarj_python_lint.rules._ast_index import NodeIndex
@@ -74,6 +75,15 @@ class _LoopReplacement:
     allow_multiline: bool = False
 
 
+@dataclass(frozen=True)
+class _OwnerBindings:
+    names: dict[str, list[ast.Name | ast.arg]]
+    external: frozenset[str]
+    local_nodes: frozenset[int]
+    captured: frozenset[str]
+    observes_namespace: bool
+
+
 @final
 class PreferCollectionComprehension(Rule):
     id = "prefer-collection-comprehension"
@@ -96,13 +106,14 @@ class PreferCollectionComprehension(Rule):
             "Only function-local, adjacent empty initializers and one synchronous single-purpose loop are checked.",
             (
                 "The rule fills gaps left by Ruff PERF401, PERF403, and FURB142: derived dict projections, "
-                "constructor-valued dict projections, destructured list projections, narrowly filtered computed list candidates, and filtered set "
+                "constructor-valued and filtered dict projections, destructured list projections, narrowly filtered computed list candidates, and filtered set "
                 "builders."
             ),
             (
                 "Comments, loop-target leakage, try blocks, aliases, complex projections, and replacements that "
                 "do not fit a 120-column line or a simple formatter-style multiline comprehension are excluded. "
-                "No autofix is offered because dict key/value evaluation order can differ."
+                "Namespace observers, explicit inspect/sys frame access, and collections referenced by nested functions "
+                "are excluded. No autofix is offered because dict key/value evaluation order can differ."
             ),
             (
                 "Attribute projections can invoke properties or descriptors, so reviewers should keep the loop "
@@ -241,32 +252,51 @@ class PreferCollectionComprehension(Rule):
         source_lines = context.source_lines
         comments = _comment_lines(source)
         diagnostics: list[Diagnostic] = []
+        set_shadowed = _set_is_shadowed(tree, node_index=context.node_index)
+        namespace_observers = _namespace_observer_calls(context)
         for owner in (node for node in context.nodes(ast.AST) if isinstance(node, _Callable)):
-            for block in _statement_blocks(owner.body):
-                for init, loop in pairwise(block):
-                    finding = _candidate(
-                        tree,
-                        owner,
-                        init=init,
-                        loop=loop,
-                        source_lines=source_lines,
-                        comments=comments,
-                        node_index=context.node_index,
-                    )
-                    if finding is None:
-                        continue
-                    diagnostics.append(
-                        Diagnostic(
-                            path=path,
-                            line=loop.lineno,
-                            col=loop.col_offset + 1,
-                            code=self.code,
-                            message=_message(finding),
-                        )
+            for finding, loop in _owner_candidates(
+                owner, source_lines, comments, namespace_observers, set_shadowed=set_shadowed
+            ):
+                diagnostics.append(
+                    Diagnostic(
+                        path=path,
+                        line=loop.lineno,
+                        col=loop.col_offset + 1,
+                        code=self.code,
+                        message=_message(finding),
                     )
+                )
         return sorted(diagnostics, key=lambda diagnostic: (diagnostic.line, diagnostic.col))
 
 
+def _owner_candidates(
+    owner: _Callable,
+    source_lines: list[str],
+    comments: frozenset[int],
+    namespace_observers: frozenset[int],
+    *,
+    set_shadowed: bool,
+) -> Iterator[tuple[_Candidate, ast.For]]:
+    bindings = None
+    for block in _statement_blocks(owner.body):
+        for init, loop in pairwise(block):
+            if not isinstance(init, _Init) or not isinstance(loop, ast.For) or _initialized_collection(init) is None:
+                continue
+            if bindings is None:
+                bindings = _owner_bindings(owner, namespace_observers)
+            finding = _candidate(
+                bindings,
+                init=init,
+                loop=loop,
+                source_lines=source_lines,
+                comments=comments,
+                set_shadowed=set_shadowed,
+            )
+            if finding is not None:
+                yield finding, loop
+
+
 def _statement_blocks(body: list[ast.stmt]) -> Iterator[list[ast.stmt]]:
     yield body
     for statement in body:
@@ -286,14 +316,13 @@ def _statement_blocks(body: list[ast.stmt]) -> Iterator[list[ast.stmt]]:
 
 
 def _candidate(
-    tree: ast.Module,
-    owner: _Callable,
+    bindings: _OwnerBindings,
     *,
     init: ast.stmt,
     loop: ast.stmt,
     source_lines: list[str],
     comments: frozenset[int],
-    node_index: NodeIndex | None = None,
+    set_shadowed: bool,
 ) -> _Candidate | None:
     if not isinstance(init, _Init) or not isinstance(loop, ast.For) or loop.orelse:
         return None
@@ -301,7 +330,9 @@ def _candidate(
     if initialized is None:
         return None
     name = initialized.name
-    if initialized.kind is _CollectionKind.SET and _set_is_shadowed(tree, node_index=node_index):
+    if bindings.observes_namespace or name in bindings.captured:
+        return None
+    if initialized.kind is _CollectionKind.SET and set_shadowed:
         return None
     if _has_comment(init, loop, comments) or is_suppressed(
         source_lines, loop.lineno, PreferCollectionComprehension.code
@@ -310,19 +341,19 @@ def _candidate(
     bound_names = _bound_names(loop.target)
     if not bound_names or _contains_starred(loop.target) or name in bound_names:
         return None
-    if _target_binding_is_observable(owner, bound_names, loop):
+    if _target_binding_is_observable(bindings, bound_names, loop):
         return None
-    if (
-        _loads_name(loop.iter, name)
-        or _contains_prohibited_expression(loop.iter)
-        or _declares_external(owner, frozenset({name}))
-    ):
+    if _loads_name(loop.iter, name) or _contains_prohibited_expression(loop.iter) or name in bindings.external:
         return None
 
-    replacement = _loop_replacement(loop, name, initialized.kind, bound_names, owner)
-    if replacement is None or not _replacement_fits(
-        init, name, replacement.expression, allow_multiline=replacement.allow_multiline
-    ):
+    try:
+        replacement = _loop_replacement(loop, name, initialized.kind, bound_names, bindings)
+        fits = replacement is not None and _replacement_fits(
+            init, name, replacement.expression, allow_multiline=replacement.allow_multiline
+        )
+    except RecursionError, SyntaxError:
+        return None
+    if replacement is None or not fits:
         return None
     return _Candidate(kind=replacement.kind, name=name, action=replacement.action)
 
@@ -354,40 +385,56 @@ def _loop_replacement(
     name: str,
     initialized_kind: _CollectionKind,
     bound_names: frozenset[str],
-    owner: _Callable,
+    bindings: _OwnerBindings,
 ) -> _LoopReplacement | None:
-    if initialized_kind is _CollectionKind.DICT and len(loop.body) == 1:
-        match loop.body[0]:
-            case ast.Assign(targets=[ast.Subscript(value=ast.Name(id=target), slice=key)], value=value) if (
-                target == name
-            ):
-                if _valid_dict_projection(key, value, name, bound_names):
-                    return _LoopReplacement(
-                        _CollectionKind.DICT,
-                        f"{{{ast.unparse(key)}: {ast.unparse(value)} for {ast.unparse(loop.target)} "
-                        f"in {ast.unparse(loop.iter)}}}",
-                        allow_multiline=isinstance(value, ast.Call),
-                    )
-            case _:
-                pass
+    if initialized_kind is _CollectionKind.DICT:
+        return _dict_replacement(loop, name, bound_names)
     if initialized_kind is _CollectionKind.LIST:
-        replacement = _list_replacement(loop, name, bound_names, owner)
+        replacement = _list_replacement(loop, name, bound_names, bindings)
         if replacement is not None:
             return replacement
-    if initialized_kind is _CollectionKind.SET and len(loop.body) == 1:
+    if initialized_kind is _CollectionKind.SET:
         return _set_replacement(loop, name, bound_names)
     return None
 
 
+def _dict_replacement(loop: ast.For, name: str, bound_names: frozenset[str]) -> _LoopReplacement | None:
+    condition = ""
+    filtered = _filtered_statement_parts(loop.body)
+    if filtered is not None:
+        statement, test, inverted = filtered
+        if _loads_name(test, name) or _contains_prohibited_expression(test):
+            return None
+        condition = f" if {_condition_source(test, inverted=inverted)}"
+    elif len(loop.body) == 1:
+        statement = loop.body[0]
+    else:
+        return None
+    match statement:
+        case ast.Assign(targets=[ast.Subscript(value=ast.Name(id=target), slice=key)], value=value) if target == name:
+            pass
+        case _:
+            return None
+    if not _valid_dict_projection(key, value, name, bound_names):
+        return None
+    return _LoopReplacement(
+        _CollectionKind.DICT,
+        f"{{{ast.unparse(key)}: {ast.unparse(value)} for {ast.unparse(loop.target)} "
+        f"in {_comprehension_expression_source(loop.iter)}{condition}}}",
+        "filters and populates" if filtered is not None else "populates",
+        allow_multiline=isinstance(value, ast.Call),
+    )
+
+
 def _list_replacement(
-    loop: ast.For, name: str, bound_names: frozenset[str], owner: _Callable
+    loop: ast.For, name: str, bound_names: frozenset[str], bindings: _OwnerBindings
 ) -> _LoopReplacement | None:
     if len(bound_names) > 1 and len(loop.body) == 1:
         expression = _single_method_argument(loop.body[0], name, "append")
         if expression is not None and not _loads_name(expression, name) and _simple_projection(expression, bound_names):
             return _LoopReplacement(
                 _CollectionKind.LIST,
-                f"[{ast.unparse(expression)} for {ast.unparse(loop.target)} in {ast.unparse(loop.iter)}]",
+                f"[{ast.unparse(expression)} for {ast.unparse(loop.target)} in {_comprehension_expression_source(loop.iter)}]",
             )
 
     filtered = _filtered_list_parts(loop.body, name)
@@ -402,32 +449,36 @@ def _list_replacement(
             condition = _condition_source(test, inverted=inverted)
             return _LoopReplacement(
                 _CollectionKind.LIST,
-                f"[{ast.unparse(expression)} for {ast.unparse(loop.target)} in {ast.unparse(loop.iter)} "
+                f"[{ast.unparse(expression)} for {ast.unparse(loop.target)} in {_comprehension_expression_source(loop.iter)} "
                 f"if {condition}]",
                 "filters and appends to",
                 allow_multiline=True,
             )
 
-    return _computed_list_replacement(loop, name, bound_names, owner)
+    return _computed_list_replacement(loop, name, bound_names, bindings)
 
 
-def _filtered_list_parts(body: list[ast.stmt], name: str) -> tuple[ast.expr, ast.expr, bool] | None:
+def _filtered_statement_parts(body: list[ast.stmt]) -> tuple[ast.stmt, ast.expr, bool] | None:
     match body:
         case [ast.If(test=test, body=[statement], orelse=[])]:
-            expression = _single_method_argument(statement, name, "append")
-            if expression is not None:
-                return expression, test, False
+            return statement, test, False
         case [ast.If(test=test, body=[ast.Continue()], orelse=[]), statement]:
-            expression = _single_method_argument(statement, name, "append")
-            if expression is not None:
-                return expression, test, True
+            return statement, test, True
         case _:
-            pass
-    return None
+            return None
+
+
+def _filtered_list_parts(body: list[ast.stmt], name: str) -> tuple[ast.expr, ast.expr, bool] | None:
+    parts = _filtered_statement_parts(body)
+    if parts is None:
+        return None
+    statement, test, inverted = parts
+    expression = _single_method_argument(statement, name, "append")
+    return (expression, test, inverted) if expression is not None else None
 
 
 def _computed_list_replacement(
-    loop: ast.For, name: str, bound_names: frozenset[str], owner: _Callable
+    loop: ast.For, name: str, bound_names: frozenset[str], bindings: _OwnerBindings
 ) -> _LoopReplacement | None:
     match loop.body:
         case [ast.Assign(targets=[ast.Name(id=candidate)], value=value), *tail]:
@@ -437,7 +488,7 @@ def _computed_list_replacement(
 
     if candidate == name or candidate in bound_names:
         return None
-    if _target_binding_is_observable(owner, frozenset({candidate}), loop):
+    if _target_binding_is_observable(bindings, frozenset({candidate}), loop):
         return None
     if _loads_name(value, name) or _contains_prohibited_expression(value):
         return None
@@ -459,7 +510,7 @@ def _computed_list_replacement(
     condition = assignment if condition_kind == "truthy" else f"{assignment} is not None"
     return _LoopReplacement(
         _CollectionKind.LIST,
-        f"[{ast.unparse(expression)} for {ast.unparse(loop.target)} in {ast.unparse(loop.iter)} if {condition}]",
+        f"[{ast.unparse(expression)} for {ast.unparse(loop.target)} in {_comprehension_expression_source(loop.iter)} if {condition}]",
         "computes, filters, and appends to",
         allow_multiline=True,
     )
@@ -517,9 +568,14 @@ def _dotted_name(node: ast.expr) -> bool:
             return False
 
 
+def _comprehension_expression_source(iterable: ast.expr) -> str:
+    source = ast.unparse(iterable)
+    return f"({source})" if isinstance(iterable, ast.IfExp) else source
+
+
 def _condition_source(test: ast.expr, *, inverted: bool) -> str:
     if not inverted:
-        return ast.unparse(test)
+        return _comprehension_expression_source(test)
     return ast.unparse(ast.UnaryOp(op=ast.Not(), operand=test))
 
 
@@ -597,41 +653,95 @@ def _contains_prohibited_expression(node: ast.AST) -> bool:
     return any(isinstance(item, _PROHIBITED_EXPRESSION_NODES) for item in walk_ast(node))
 
 
-def _target_binding_is_observable(owner: _Callable, names: frozenset[str], loop: ast.For) -> bool:
-    if _declares_external(owner, names) or any(_loads_name(loop.iter, name) for name in names):
+def _owner_bindings(owner: _Callable, namespace_observers: frozenset[int]) -> _OwnerBindings:
+    nodes = tuple(walk_ast(owner))
+    names: defaultdict[str, list[ast.Name | ast.arg]] = defaultdict(list)
+    for node in nodes:
+        if isinstance(node, ast.Name):
+            names[node.id].append(node)
+        elif isinstance(node, ast.arg):
+            names[node.arg].append(node)
+    return _OwnerBindings(
+        names=dict(names),
+        external=frozenset(
+            name for node in nodes if isinstance(node, (ast.Global, ast.Nonlocal)) for name in node.names
+        ),
+        local_nodes=frozenset(_comprehension_local_nodes(nodes, frozenset(names))),
+        captured=_captured_names(owner),
+        observes_namespace=any(id(node) in namespace_observers for node in nodes),
+    )
+
+
+def _namespace_observer_calls(context: PythonFileContext) -> frozenset[int]:
+    observers = {
+        "builtins": {"locals", "vars", "eval", "exec"},
+        "inspect": {"currentframe"},
+        "sys": {"_getframe"},
+    }
+    # Explicit aliases remain conservative exclusions even when another scope shadows them.
+    modules: defaultdict[str, set[str]] = defaultdict(set)
+    symbols = observers["builtins"].copy()
+    for node in context.nodes(ast.Import):
+        for alias in node.names:
+            if alias.name in observers:
+                modules[alias.asname or alias.name].update(observers[alias.name])
+    for node in context.nodes(ast.ImportFrom):
+        if node.module not in observers:
+            continue
+        symbols.update(alias.asname or alias.name for alias in node.names if alias.name in observers[node.module])
+    return frozenset(
+        id(call) for call in context.nodes(ast.Call) if _is_namespace_observer(call.func, symbols, modules)
+    )
+
+
+def _is_namespace_observer(function: ast.expr, symbols: set[str], modules: dict[str, set[str]]) -> bool:
+    match function:
+        case ast.Name(id=name):
+            return name in symbols
+        case ast.Attribute(value=ast.Name(id=module), attr=symbol):
+            return module in modules and symbol in modules[module]
+        case _:
+            return False
+
+
+def _captured_names(owner: _Callable) -> frozenset[str]:
+    captured: set[str] = set()
+    pending: list[tuple[ast.AST, bool]] = [(owner, False)]
+    while pending:
+        node, nested = pending.pop()
+        nested = nested or (node is not owner and isinstance(node, (_Callable, ast.Lambda, ast.ClassDef)))
+        if nested and isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+            captured.add(node.id)
+        pending.extend((child, nested) for child in children(node))
+    return frozenset(captured)
+
+
+def _target_binding_is_observable(bindings: _OwnerBindings, names: frozenset[str], loop: ast.For) -> bool:
+    if not bindings.external.isdisjoint(names) or any(_loads_name(loop.iter, name) for name in names):
         return True
     end_line = loop.end_lineno or loop.lineno
-    comprehension_locals = _comprehension_local_nodes(owner, names)
-    for node in walk_ast(owner):
-        if isinstance(node, ast.arg) and node.arg in names:
-            return True
-        if id(node) in comprehension_locals:
-            continue
-        if (
-            isinstance(node, ast.Name)
-            and node.id in names
-            and (
-                getattr(node, "lineno", loop.lineno) < loop.lineno
-                or (getattr(node, "lineno", 0) > end_line and isinstance(node.ctx, (ast.Load, ast.Del)))
-            )
-        ):
-            return True
+    for name in names:
+        for node in bindings.names.get(name, []):
+            if isinstance(node, ast.arg):
+                return True
+            if id(node) in bindings.local_nodes:
+                continue
+            if node.lineno < loop.lineno or (node.lineno > end_line and isinstance(node.ctx, (ast.Load, ast.Del))):
+                return True
     return False
 
 
-def _comprehension_local_nodes(owner: _Callable, names: frozenset[str]) -> set[int]:
+def _comprehension_local_nodes(nodes: Iterable[ast.AST], names: frozenset[str]) -> set[int]:
     local_nodes: set[int] = set()
-    for node in walk_ast(owner):
+    for node in nodes:
         if not isinstance(node, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
             continue
-        # Multiple generators can read an outer binding before a later generator shadows it.
-        if len(node.generators) != 1:
-            continue
+        # Only first-generator bindings are local before every later generator expression.
         bound = _bound_names(node.generators[0].target) & names
         if not bound:
             continue
         # The first iterable runs in the surrounding scope; targets and remaining expressions are local.
-        scoped: list[ast.AST] = [node.generators[0].target, *node.generators[0].ifs]
+        scoped: list[ast.AST] = [node.generators[0].target, *node.generators[0].ifs, *node.generators[1:]]
         scoped.extend((node.key, node.value) if isinstance(node, ast.DictComp) else (node.elt,))
         local_nodes.update(
             id(child)
@@ -642,12 +752,6 @@ def _comprehension_local_nodes(owner: _Callable, names: frozenset[str]) -> set[i
     return local_nodes
 
 
-def _declares_external(owner: _Callable, names: frozenset[str]) -> bool:
-    return any(
-        isinstance(node, (ast.Global, ast.Nonlocal)) and not names.isdisjoint(node.names) for node in walk_ast(owner)
-    )
-
-
 def _set_is_shadowed(tree: ast.Module, *, node_index: NodeIndex | None = None) -> bool:
     for node in walk_ast(tree, index=node_index):
         match node:
@@ -673,6 +777,7 @@ def _set_is_shadowed(tree: ast.Module, *, node_index: NodeIndex | None = None) -
 
 
 def _replacement_fits(init: _Init, name: str, expression: str, *, allow_multiline: bool = False) -> bool:
+    comprehension = ast.parse(expression, mode="eval").body
     prefix = f"{name} = "
     if isinstance(init, ast.AnnAssign):
         prefix = f"{name}: {ast.unparse(init.annotation)} = "
@@ -681,7 +786,6 @@ def _replacement_fits(init: _Init, name: str, expression: str, *, allow_multilin
     if not allow_multiline:
         return False
     if expression.startswith("{"):
-        comprehension = ast.parse(expression, mode="eval").body
         if not isinstance(comprehension, ast.DictComp) or not isinstance(comprehension.value, ast.Call):
             return False
         call = comprehension.value
@@ -690,7 +794,8 @@ def _replacement_fits(init: _Init, name: str, expression: str, *, allow_multilin
             f"{ast.unparse(comprehension.key)}: {ast.unparse(call.func)}(",
             *(f"    {ast.unparse(argument)}," for argument in call.args),
             *(f"    {keyword.arg}={ast.unparse(keyword.value)}," for keyword in call.keywords),
-            f"for {ast.unparse(generator.target)} in {ast.unparse(generator.iter)}",
+            f"for {ast.unparse(generator.target)} in {_comprehension_expression_source(generator.iter)}",
+            *(f"if {_comprehension_expression_source(test)}" for test in generator.ifs),
         )
         return init.col_offset + len(prefix) + 1 <= _MAX_REPLACEMENT_WIDTH and all(
             init.col_offset + 4 + len(line) <= _MAX_REPLACEMENT_WIDTH for line in lines
@@ -718,24 +823,24 @@ def _has_comment(init: _Init, loop: ast.For, comments: frozenset[int]) -> bool:
 
 
 def _set_replacement(loop: ast.For, name: str, bound_names: frozenset[str]) -> _LoopReplacement | None:
-    match loop.body[0]:
-        case ast.If(test=test, body=[body], orelse=[]):
-            expression = _single_method_argument(body, name, "add")
-            if (
-                expression is not None
-                and not _loads_name(test, name)
-                and not _loads_name(expression, name)
-                and _simple_projection(expression, bound_names)
-                and not _contains_prohibited_expression(test)
-            ):
-                return _LoopReplacement(
-                    _CollectionKind.SET,
-                    f"{{{ast.unparse(expression)} for {ast.unparse(loop.target)} in {ast.unparse(loop.iter)} "
-                    f"if {ast.unparse(test)}}}",
-                )
-        case _:
-            pass
-    return None
+    parts = _filtered_statement_parts(loop.body)
+    if parts is None:
+        return None
+    statement, test, inverted = parts
+    expression = _single_method_argument(statement, name, "add")
+    if (
+        expression is None
+        or _loads_name(test, name)
+        or _loads_name(expression, name)
+        or not _simple_projection(expression, bound_names)
+        or _contains_prohibited_expression(test)
+    ):
+        return None
+    return _LoopReplacement(
+        _CollectionKind.SET,
+        f"{{{ast.unparse(expression)} for {ast.unparse(loop.target)} "
+        f"in {_comprehension_expression_source(loop.iter)} if {_condition_source(test, inverted=inverted)}}}",
+    )
 
 
 def _message(finding: _Candidate) -> str: