sarj-python-lint 1.43.0__tar.gz → 1.44.0__tar.gz

{sarj_python_lint-1.43.0 → sarj_python_lint-1.44.0}/PKG-INFO

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

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

{sarj_python_lint-1.43.0 → sarj_python_lint-1.44.0}/src/sarj_python_lint/rules/_resource_provenance.py

@@ -56,6 +56,15 @@ _RESOURCE_OWNERS = MappingProxyType(
 )
 
 
+def builtin_namespace_untouched(context: PythonFileContext) -> 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 context.nodes(ast.Import, ast.ImportFrom, ast.Name)
+    )
+
+
 @final
 class ResourceProvenance:
     def __init__(self, context: PythonFileContext, *, require_static_namespace: bool = False) -> None:
@@ -86,12 +95,7 @@ class ResourceProvenance:
 
     @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)
-        )
+        return builtin_namespace_untouched(self.context)
 
     def scope(self, node: ast.AST) -> ast.AST | None:
         parent = self.context.parents.get(node)

sarj_python_lint-1.44.0/src/sarj_python_lint/rules/_type_guard_symbols.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import ast
+from collections import Counter
+from typing import TYPE_CHECKING
+
+from sarj_python_lint.rules._imports import TYPING_SOURCES
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_NAMESPACE_IMPORT_CAPABILITIES = frozenset(
+    {"__dict__", "__builtins__", "__getattribute__", "__setattr__", "__delattr__"}
+)
+_NAMESPACE_RETURNING_FUNCTIONS = frozenset({"__lazy_import__"})
+_BUILTIN_NAMESPACE_FUNCTIONS = frozenset(
+    {
+        "__build_class__",
+        "__import__",
+        "__lazy_import__",
+        "abs",
+        "aiter",
+        "all",
+        "anext",
+        "any",
+        "ascii",
+        "bin",
+        "breakpoint",
+        "callable",
+        "chr",
+        "compile",
+        "delattr",
+        "dir",
+        "divmod",
+        "eval",
+        "exec",
+        "format",
+        "getattr",
+        "globals",
+        "hasattr",
+        "hash",
+        "hex",
+        "id",
+        "input",
+        "isinstance",
+        "issubclass",
+        "iter",
+        "len",
+        "locals",
+        "max",
+        "min",
+        "next",
+        "oct",
+        "ord",
+        "pow",
+        "print",
+        "repr",
+        "round",
+        "setattr",
+        "sorted",
+        "sum",
+        "vars",
+    }
+)
+
+
+def builtin_guard_symbol(node: ast.expr | None, imports: ImportIndex, builtin_symbols: frozenset[str]) -> str | None:
+    if node is None:
+        return None
+    symbol = imports.resolved_symbol(node, sources=frozenset({"builtins"}))
+    if symbol in builtin_symbols:
+        return symbol
+    if isinstance(node, ast.Name) and node.id in builtin_symbols and imports.builtin_is_unshadowed(node.id):
+        return node.id
+    return None
+
+
+def unique_guard_function_names(context: PythonFileContext) -> frozenset[str]:
+    if context.tree is None:
+        return frozenset()
+    counts: Counter[str] = Counter()
+    pending: list[ast.AST] = list(context.tree.body)
+    while pending:
+        node = pending.pop()
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            counts[node.name] += 1
+        elif not isinstance(node, (ast.ClassDef, ast.Lambda)):
+            pending.extend(ast.iter_child_nodes(node))
+    return frozenset(name for name, count in counts.items() if count == 1)
+
+
+def guard_symbols_ambiguous(
+    context: PythonFileContext,
+    builtin_symbols: frozenset[str],
+    *,
+    typing_symbols: frozenset[str] = frozenset({"TypeGuard", "TypeIs"}),
+) -> bool:
+    namespace_names = _namespace_import_names(context)
+    if _namespace_escapes(context, namespace_names):
+        return True
+    mutation_targets = (
+        {f"builtins.{symbol}" for symbol in builtin_symbols}
+        | {f"{module}.{symbol}" for module in TYPING_SOURCES for symbol in typing_symbols}
+        | {f"{module}.__class__" for module in TYPING_SOURCES | {"builtins"}}
+    )
+    sensitive_names = (
+        builtin_symbols
+        | namespace_names
+        | {
+            name
+            for name, target in context.module_imports.bindings.items()
+            if target.module in TYPING_SOURCES | {"builtins"}
+            and (target.symbol is None or target.symbol in builtin_symbols | typing_symbols)
+        }
+    )
+    return any(
+        _ambiguous_node(node, context, mutation_targets, sensitive_names)
+        for node in context.nodes(
+            ast.Import,
+            ast.ImportFrom,
+            ast.Attribute,
+            ast.ExceptHandler,
+            ast.MatchAs,
+            ast.MatchStar,
+            ast.MatchMapping,
+            ast.NamedExpr,
+        )
+    )
+
+
+def _namespace_import_names(context: PythonFileContext) -> frozenset[str]:
+    return frozenset(
+        alias.asname or alias.name
+        for node in context.nodes(ast.Import)
+        for alias in node.names
+        if alias.name in TYPING_SOURCES | {"builtins"}
+    )
+
+
+def _namespace_escapes(context: PythonFileContext, namespace_names: frozenset[str]) -> bool:
+    if context.dynamic_namespace or any(node.id == "__builtins__" for node in context.nodes(ast.Name)):
+        return True
+    if any(
+        node.level == 0
+        and node.module in TYPING_SOURCES | {"builtins"}
+        and any(alias.name in _NAMESPACE_IMPORT_CAPABILITIES for alias in node.names)
+        for node in context.nodes(ast.ImportFrom)
+    ):
+        return True
+    if _native_function_escapes(context):
+        return True
+    for name in context.nodes(ast.Name):
+        if name.id not in namespace_names:
+            continue
+        parent = context.parents.get(name)
+        if not isinstance(parent, ast.Attribute) or parent.value is not name or parent.attr == "__dict__":
+            return True
+    return False
+
+
+def _native_function_escapes(context: PythonFileContext) -> bool:
+    function_names = _possible_native_function_names(context)
+    namespace_function_names = _possible_native_function_names(context, symbols=_NAMESPACE_RETURNING_FUNCTIONS)
+    module_names = frozenset(
+        alias.asname or alias.name
+        for node in context.nodes(ast.Import)
+        for alias in node.names
+        if alias.name == "builtins"
+    )
+    for node in context.nodes(ast.Name, ast.Attribute):
+        if isinstance(node, ast.Attribute) and (
+            not isinstance(node.value, ast.Name) or node.attr not in _BUILTIN_NAMESPACE_FUNCTIONS
+        ):
+            continue
+        if not isinstance(node.ctx, ast.Load) or not _possible_native_function(node, function_names, module_names):
+            continue
+        parent = context.parents.get(node)
+        if (
+            not isinstance(parent, ast.Call)
+            or parent.func is not node
+            or _namespace_returning_function(node, namespace_function_names)
+        ):
+            return True
+    return False
+
+
+def _possible_native_function_names(
+    context: PythonFileContext, *, symbols: frozenset[str] = _BUILTIN_NAMESPACE_FUNCTIONS
+) -> frozenset[str]:
+    return symbols | frozenset(
+        alias.asname or alias.name
+        for node in context.nodes(ast.ImportFrom)
+        if node.level == 0 and node.module == "builtins"
+        for alias in node.names
+        if alias.name in symbols
+    )
+
+
+def _namespace_returning_function(node: ast.Name | ast.Attribute, function_names: frozenset[str]) -> bool:
+    if isinstance(node, ast.Name):
+        return node.id in function_names
+    return node.attr in _NAMESPACE_RETURNING_FUNCTIONS
+
+
+def _possible_native_function(
+    node: ast.Name | ast.Attribute,
+    function_names: frozenset[str],
+    module_names: frozenset[str],
+) -> bool:
+    if isinstance(node, ast.Name):
+        return node.id in function_names
+    return (
+        isinstance(node.value, ast.Name) and node.value.id in module_names and node.attr in _BUILTIN_NAMESPACE_FUNCTIONS
+    )
+
+
+def _ambiguous_node(
+    node: ast.AST, context: PythonFileContext, mutation_targets: set[str], sensitive_names: frozenset[str]
+) -> bool:
+    match node:
+        case ast.Import() | ast.ImportFrom():
+            return _ambiguous_import(node, context.module_imports, sensitive_names)
+        case ast.Attribute(ctx=(ast.Store() | ast.Del())):
+            return context.module_imports.resolved_qualified_name(node) in mutation_targets
+        case (
+            ast.ExceptHandler(name=name)
+            | ast.MatchAs(name=name)
+            | ast.MatchStar(name=name)
+            | ast.MatchMapping(rest=name)
+            | ast.NamedExpr(target=ast.Name(id=name))
+        ):
+            return name in sensitive_names
+        case _:
+            return False
+
+
+def _ambiguous_import(node: ast.Import | ast.ImportFrom, imports: ImportIndex, sensitive_names: frozenset[str]) -> bool:
+    if isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names):
+        return True
+    for alias in node.names:
+        name = alias.asname or alias.name.partition(".")[0]
+        if name not in sensitive_names:
+            continue
+        if not _preserves_canonical_import(node, alias, imports):
+            return True
+    return False
+
+
+def _preserves_canonical_import(node: ast.Import | ast.ImportFrom, alias: ast.alias, imports: ImportIndex) -> bool:
+    if isinstance(node, ast.ImportFrom):
+        if node.level:
+            return False
+        module, symbol = node.module, alias.name
+    else:
+        module, symbol = alias.name, None
+    name = alias.asname or alias.name.partition(".")[0]
+    target = imports.bindings.get(name)
+    if target is None:
+        return module == "builtins" and symbol == name
+    return target.module == module and target.symbol == symbol

{sarj_python_lint-1.43.0 → sarj_python_lint-1.44.0}/src/sarj_python_lint/rules/async_mock_call_without_await_assertion.py

@@ -21,7 +21,7 @@ from sarj_python_lint.rule_base import (
 from sarj_python_lint.rules._ast_index import walk as walk_ast
 from sarj_python_lint.rules._imports import ImportIndex
 from sarj_python_lint.rules._pytest import collected_tests
-from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance, builtin_namespace_untouched
 
 
 if TYPE_CHECKING:
@@ -97,13 +97,44 @@ class AsyncMockCallWithoutAwaitAssertion(Rule):
             "Requires a fresh local unittest.mock.AsyncMock constructor with unshadowed imports; aliases, reassignment, reset, and ambiguous configuration are excluded.",
             "Visible provider replacement, escape or unresolved lexical ownership retains WARNING; only the closed canonical AsyncMock provider proof blocks.",
             "Only the mock itself and unchanged immediate children of unspecced, unwrapped mocks are inferred; spec children, return values, and deeper chains are excluded.",
-            "Positive call evidence includes direct assertion methods and literal integer or boolean call-state checks; unresolved call expectations are excluded.",
-            "Await evidence excludes provably vacuous checks, including zero or nonnegative counts and empty expected await sequences; unresolved expectations are accepted without inferring their values.",
+            "Positive call evidence includes direct assertion methods and literal numeric or boolean call-state checks; unresolved call expectations are excluded.",
+            "Await evidence excludes provably vacuous checks, including non-None count/list state, zero or nonnegative numeric bounds, and empty expected await sequences; unresolved expectations are accepted without inferring their values.",
+            "Length comparisons over await_args_list use count semantics only for an unshadowed builtin len without visible builtin namespace access; custom length functions remain unresolved.",
             "Conjunctions need one accepted await branch; disjunctions need accepted evidence for the same mock in every branch. Argument equality and assertion strength are not compared.",
             "Compound negation and custom expression semantics remain unresolved; no variable values or fixture graphs are inferred.",
             "Custom assertion helpers and intentional scheduling contracts may require a reasoned local suppression.",
         ),
         examples=(
+            RuleExample(
+                example_id="vacuous-await-length",
+                scenario="await-length-evidence",
+                title="An empty await history still has nonnegative length",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_delivery.py",
+                        "from unittest.mock import AsyncMock\nasync def test_delivery():\n    send = AsyncMock()\n    await deliver(send)\n    send.assert_called_once()\n    assert len(send.await_args_list) >= 0\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_delivery.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="positive-await-length",
+                scenario="await-length-evidence",
+                title="A positive await-history length distinguishes a dropped coroutine",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_delivery.py",
+                        "from unittest.mock import AsyncMock\nasync def test_delivery():\n    send = AsyncMock()\n    await deliver(send)\n    send.assert_called_once()\n    assert len(send.await_args_list) == 1\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_delivery.py"),
+                expected_count=0,
+                public=True,
+            ),
             RuleExample(
                 example_id="spaced-positive-called-state",
                 scenario="called-attribute-spacing",
@@ -212,6 +243,7 @@ class AsyncMockCallWithoutAwaitAssertion(Rule):
         if tree is None:
             return []
         imports = context.module_imports
+        builtin_len = builtin_namespace_untouched(context)
         writes = {
             _reference(node)
             for node in context.nodes(ast.AST)
@@ -221,14 +253,20 @@ class AsyncMockCallWithoutAwaitAssertion(Rule):
             finding
             for test in collected_tests(tree.body)
             if not _is_pytest_fixture(test, imports)
-            for finding in _test_diagnostics(test, context, imports, writes, self.code)
+            for finding in _test_diagnostics(test, context, imports, writes, self.code, builtin_len=builtin_len)
         ]
 
 
 def _test_diagnostics(
-    test: _TestFunction, context: PythonFileContext, imports: ImportIndex, writes: set[_Reference], code: str
+    test: _TestFunction,
+    context: PythonFileContext,
+    imports: ImportIndex,
+    writes: set[_Reference],
+    code: str,
+    *,
+    builtin_len: bool,
 ) -> list[Diagnostic]:
-    calls = tuple(_uncovered_calls(_test_imports(imports, test), test, writes))
+    calls = tuple(_uncovered_calls(_test_imports(imports, test), test, writes, builtin_len=builtin_len))
     if not calls:
         return []
     severity = Severity.ERROR if _mock_provider_proven(test, context) else Severity.WARNING
@@ -281,11 +319,11 @@ def _test_imports(module: ImportIndex, test: _TestFunction) -> ImportIndex:
 
 
 def _uncovered_calls(
-    imports: ImportIndex, test: _TestFunction, writes: set[_Reference]
+    imports: ImportIndex, test: _TestFunction, writes: set[_Reference], *, builtin_len: bool
 ) -> Iterator[ast.Call | ast.Attribute]:
     nodes = tuple(walk_ast(test))
     bindings = _mock_bindings(imports, test.body, writes)
-    covered = _await_oracles(test.body)
+    covered = _await_oracles(test.body, builtin_len=builtin_len and imports.builtin_is_unshadowed("len"))
     reported: set[_Reference] = set()
     for statement in test.body:
         for reference, oracle in _call_oracles(statement):
@@ -375,7 +413,7 @@ def _is_async_reference(reference: _Reference, constructor: ast.Call) -> bool:
     )
 
 
-def _await_oracles(statements: list[ast.stmt]) -> set[_Reference]:
+def _await_oracles(statements: list[ast.stmt], *, builtin_len: bool) -> set[_Reference]:
     covered: set[_Reference] = set()
     for statement in statements:
         match statement:
@@ -385,7 +423,7 @@ def _await_oracles(statements: list[ast.stmt]) -> set[_Reference]:
                 if method != "assert_has_awaits" or _calls_evidence(call) is not _Evidence.INSUFFICIENT:
                     covered.add(_reference(receiver))
             case ast.Assert(test=condition):
-                covered.update(_asserted_states(condition, _AWAIT_STATE))
+                covered.update(_asserted_states(condition, _AWAIT_STATE, builtin_len=builtin_len))
             case _:
                 pass
     return covered
@@ -409,17 +447,21 @@ def _sequence_evidence(node: ast.expr) -> _Evidence:
     return _Evidence.UNRESOLVED
 
 
-def _asserted_states(condition: ast.expr, states: frozenset[str]) -> set[_Reference]:
+def _asserted_states(condition: ast.expr, states: frozenset[str], *, builtin_len: bool = False) -> set[_Reference]:
     match condition:
         case ast.UnaryOp(op=ast.Not(), operand=ast.UnaryOp(op=ast.Not(), operand=operand)):
-            return _asserted_states(operand, states)
+            return _asserted_states(operand, states, builtin_len=builtin_len)
         case ast.UnaryOp(op=ast.Not(), operand=ast.Compare(left=left, ops=[operator], comparators=[right])):
             inverse = _negated_operator(operator)
-            return _comparison_states(left, inverse, right, states) if inverse is not None else set()
+            return (
+                _comparison_states(left, inverse, right, states, builtin_len=builtin_len)
+                if inverse is not None
+                else set()
+            )
         case ast.UnaryOp(op=ast.Not(), operand=ast.Attribute(attr=attribute)) if attribute in states:
             return set()
         case ast.BoolOp(op=operator, values=values):
-            branches = [_asserted_states(value, states) for value in values]
+            branches = [_asserted_states(value, states, builtin_len=builtin_len) for value in values]
             return (
                 branches[0].union(*branches[1:])
                 if isinstance(operator, ast.And)
@@ -430,7 +472,7 @@ def _asserted_states(condition: ast.expr, states: frozenset[str]) -> set[_Refere
         case ast.Compare(left=left, ops=operators, comparators=rights):
             result: set[_Reference] = set()
             for first, operator, second in zip((left, *rights[:-1]), operators, rights, strict=True):
-                result.update(_comparison_states(first, operator, second, states))
+                result.update(_comparison_states(first, operator, second, states, builtin_len=builtin_len))
             return result
         case _:
             # Preserve acceptance of unresolved await-state assertions, such as
@@ -453,18 +495,37 @@ def _negated_operator(operator: ast.cmpop) -> ast.cmpop | None:
     return factory() if factory is not None else None
 
 
-def _comparison_states(left: ast.expr, operator: ast.cmpop, right: ast.expr, states: frozenset[str]) -> set[_Reference]:
+def _comparison_states(
+    left: ast.expr, operator: ast.cmpop, right: ast.expr, states: frozenset[str], *, builtin_len: bool = False
+) -> set[_Reference]:
     result: set[_Reference] = set()
     for node, comparison, expected in ((left, operator, right), (right, _reversed_operator(operator), left)):
-        if isinstance(node, ast.Attribute) and node.attr in states:
-            evidence = _state_evidence(node.attr, comparison, expected)
+        state = _state_operand(node, states, builtin_len=builtin_len)
+        if state is not None:
+            evidence = _state_evidence(
+                "await_count" if isinstance(node, ast.Call) else state.attr, comparison, expected
+            )
             if evidence is _Evidence.POSITIVE or (states == _AWAIT_STATE and evidence is _Evidence.UNRESOLVED):
-                result.add(_reference(node.value))
+                result.add(_reference(state.value))
         else:
             result.update(_unresolved_await_states(node, states))
     return result
 
 
+def _state_operand(node: ast.expr, states: frozenset[str], *, builtin_len: bool) -> ast.Attribute | None:
+    if isinstance(node, ast.Attribute) and node.attr in states:
+        return node
+    if builtin_len and states == _AWAIT_STATE:
+        match node:
+            case ast.Call(
+                func=ast.Name(id="len"), args=[ast.Attribute(attr="await_args_list") as argument], keywords=[]
+            ):
+                return argument
+            case _:
+                pass
+    return None
+
+
 def _reversed_operator(operator: ast.cmpop) -> ast.cmpop:
     match operator:
         case ast.Lt():
@@ -489,12 +550,14 @@ def _unresolved_await_states(node: ast.expr, states: frozenset[str]) -> set[_Ref
 
 def _state_evidence(attribute: str, operator: ast.cmpop, expected: ast.expr) -> _Evidence:
     positive: bool
-    if (
-        attribute in {"call_count", "await_count"}
+    if attribute in {"call_count", "await_count"} and (value := _literal_number(expected)) is not None:
+        positive = _proves_positive_count(operator, value)
+    elif (
+        attribute in {"call_count", "await_count", "await_args_list"}
         and isinstance(expected, ast.Constant)
-        and isinstance(expected.value, int)
+        and expected.value is None
     ):
-        positive = _proves_positive_count(operator, expected.value)
+        return _Evidence.INSUFFICIENT
     elif attribute == "called" and isinstance(expected, ast.Constant) and isinstance(expected.value, bool):
         positive = (isinstance(operator, (ast.Eq, ast.Is)) and expected.value) or (
             isinstance(operator, (ast.NotEq, ast.IsNot)) and not expected.value
@@ -513,7 +576,20 @@ def _state_evidence(attribute: str, operator: ast.cmpop, expected: ast.expr) ->
     return _Evidence.POSITIVE if positive else _Evidence.INSUFFICIENT
 
 
-def _proves_positive_count(operator: ast.cmpop, value: int) -> bool:
+def _literal_number(node: ast.expr) -> int | float | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+        return node.value
+    if isinstance(node, ast.UnaryOp) and isinstance(node.operand, ast.Constant):
+        value = node.operand.value
+        if isinstance(value, (int, float)):
+            if isinstance(node.op, ast.USub):
+                return -value
+            if isinstance(node.op, ast.UAdd):
+                return +value
+    return None
+
+
+def _proves_positive_count(operator: ast.cmpop, value: float) -> bool:
     match operator:
         case ast.Eq() | ast.GtE():
             return value > 0