sarj-python-lint 1.81.0__tar.gz → 1.82.0__tar.gz

{sarj_python_lint-1.81.0 → sarj_python_lint-1.82.0}/PKG-INFO

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

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

sarj_python_lint-1.82.0/src/sarj_python_lint/rules/_async_lifecycle.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, final
+
+from sarj_python_lint.rules._resource_provenance import import_name_for_binding
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_INTROSPECTION = frozenset({"__dict__", "__setattr__", "__delattr__", "__getattribute__"})
+
+
+@dataclass(frozen=True, slots=True)
+class _LocalAssignment:
+    binding: ast.Name
+    value: ast.expr
+
+
+@final
+class AsyncApiProof:
+    def __init__(self, context: PythonFileContext) -> None:
+        self.context = context
+        self.provenance = context.static_resource_provenance
+        self._namespace_safety: dict[str, bool] = {}
+        self._origins: dict[str, set[str]] = {}
+        for node in context.nodes(ast.Import, ast.ImportFrom):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    name = alias.asname or alias.name.partition(".")[0]
+                    target = alias.name if alias.asname else alias.name.partition(".")[0]
+                    self._origins.setdefault(name, set()).add(target)
+            elif node.level == 0 and node.module is not None:
+                for alias in node.names:
+                    self._origins.setdefault(alias.asname or alias.name, set()).add(f"{node.module}.{alias.name}")
+
+    def imported(self, expression: ast.expr, qualified: str) -> bool:
+        root = expression
+        while isinstance(root, ast.Attribute):
+            root = root.value
+        if not isinstance(root, ast.Name):
+            return False
+        if (
+            self.context.dynamic_namespace
+            or self.provenance.wildcard
+            or root.id in self.provenance.mutated
+            or root.id in self.provenance.external_bindings
+        ):
+            return False
+        binding = self.provenance.binding(root.id, expression)
+        if (
+            not isinstance(binding, ast.alias)
+            or not isinstance(self.provenance.scope(binding), ast.Module)
+            or import_name_for_binding(expression, binding, self.context.parents.get(binding)) != qualified
+        ):
+            return False
+        declaration = self.context.parents.get(binding)
+        if not isinstance(declaration, ast.Import | ast.ImportFrom) or not isinstance(
+            self.context.parents.get(declaration), ast.Module
+        ):
+            return False
+        if qualified not in self._namespace_safety:
+            self._namespace_safety[qualified] = self._namespace_untouched(qualified)
+        return self._namespace_safety[qualified]
+
+    def _namespace_untouched(self, qualified: str) -> bool:
+        for node in self.context.nodes(ast.Name, ast.Attribute):
+            targets = self._targets(node)
+            if not any(
+                target == qualified or target.startswith(qualified + ".") or qualified.startswith(target + ".")
+                for target in targets
+            ):
+                continue
+            if not isinstance(node.ctx, ast.Load) or not self._safe_api_read(node, qualified):
+                return False
+        return True
+
+    def _targets(self, expression: ast.Name | ast.Attribute) -> tuple[str, ...]:
+        parts: list[str] = []
+        root: ast.expr = expression
+        while isinstance(root, ast.Attribute):
+            parts.append(root.attr)
+            root = root.value
+        if not isinstance(root, ast.Name):
+            return ()
+        suffix = ".".join(reversed(parts))
+        return tuple(f"{origin}.{suffix}" if suffix else origin for origin in self._origins.get(root.id, ()))
+
+    def _safe_api_read(self, node: ast.Name | ast.Attribute, qualified: str) -> bool:
+        parent = self.context.parents.get(node)
+        if isinstance(parent, ast.Attribute) and parent.value is node:
+            return parent.attr not in _INTROSPECTION
+        if isinstance(parent, ast.Call) and parent.func is node:
+            return True
+        if isinstance(parent, ast.Subscript) and parent.value is node:
+            return True
+        if isinstance(parent, ast.arg | ast.AnnAssign) and parent.annotation is node:
+            return True
+        if isinstance(parent, ast.FunctionDef | ast.AsyncFunctionDef):
+            return parent.returns is node or (
+                qualified == "contextlib.asynccontextmanager" and node in parent.decorator_list
+            )
+        return isinstance(parent, ast.ExceptHandler) and parent.type is node
+
+    def assignment(self, name: ast.Name, at: ast.AST) -> _LocalAssignment | None:
+        binding = self.provenance.binding(name.id, at)
+        if (
+            not isinstance(binding, ast.Name)
+            or name.id in self.provenance.mutated
+            or name.id in self.provenance.external_bindings
+        ):
+            return None
+        value = self.provenance.assignment_value(binding, at)
+        return _LocalAssignment(binding=binding, value=value) if value is not None else None
+
+
+def method_receiver(call: ast.Call, methods: frozenset[str]) -> ast.Name | None:
+    callee = call.func
+    if isinstance(callee, ast.Attribute) and callee.attr in methods and isinstance(callee.value, ast.Name):
+        return callee.value
+    return None

sarj_python_lint-1.82.0/src/sarj_python_lint/rules/_numeric_proof.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sarj_python_lint.rules._resource_provenance import builtin_namespace_untouched
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_MAX_ALIAS_DEPTH = 8
+
+
+@dataclass(frozen=True, slots=True)
+class LocalAssignment:
+    target: ast.Name
+    value: ast.expr
+
+
+def native_builtin(context: PythonFileContext, node: ast.expr, name: str) -> bool:
+    return (
+        isinstance(node, ast.Name)
+        and node.id == name
+        and context.imports.builtin_is_unshadowed(name)
+        and builtin_namespace_untouched(context)
+    )
+
+
+def imported_api(context: PythonFileContext, node: ast.expr, qualified: str) -> bool:
+    if context.imports.resolved_qualified_name(node) != qualified:
+        return False
+    provenance = context.static_resource_provenance
+    root = node
+    while isinstance(root, ast.Attribute):
+        root = root.value
+    if not isinstance(root, ast.Name):
+        return False
+    binding = provenance.binding(root.id, node)
+    if not isinstance(binding, ast.alias) or provenance.scope(binding) is not context.tree:
+        return False
+    if root.id in provenance.mutated:
+        return False
+    module = qualified.partition(".")[0]
+    if not _module_namespace_intact(context, module):
+        return False
+    for read in provenance.binding_reads(root.id, binding):
+        parent = context.parents.get(read)
+        if not (isinstance(parent, ast.Attribute) or (isinstance(parent, ast.Call) and parent.func is read)):
+            return False
+    for reference in context.nodes(ast.Name, ast.Attribute):
+        if context.imports.resolved_qualified_name(reference) != qualified:
+            continue
+        parent = context.parents.get(reference)
+        if not isinstance(parent, ast.Call) or parent.func is not reference:
+            return False
+    return True
+
+
+def _module_namespace_intact(context: PythonFileContext, module: str) -> bool:
+    for member in context.nodes(ast.Attribute):
+        target = context.imports.resolved_qualified_name(member)
+        if isinstance(member.ctx, ast.Store | ast.Del) and target is not None and target.startswith(module + "."):
+            return False
+    for statement in context.nodes(ast.Import):
+        for alias in statement.names:
+            if alias.name != module:
+                continue
+            if not _namespace_reads_are_members(context, alias):
+                return False
+    return True
+
+
+def _namespace_reads_are_members(context: PythonFileContext, alias: ast.alias) -> bool:
+    local = alias.asname or alias.name
+    for read in context.static_resource_provenance.binding_reads(local, alias):
+        parent = context.parents.get(read)
+        if not isinstance(parent, ast.Attribute) or parent.value is not read:
+            return False
+    return True
+
+
+def local_value(context: PythonFileContext, node: ast.Name) -> ast.expr | None:
+    provenance = context.static_resource_provenance
+    binding = provenance.binding(node.id, node)
+    if not isinstance(binding, ast.Name):
+        return None
+    return provenance.assignment_value(binding, node)
+
+
+def value_origin(context: PythonFileContext, expression: ast.expr, *, depth: int = 0) -> str:
+    if isinstance(expression, ast.Name):
+        value = local_value(context, expression)
+        if isinstance(value, ast.Name) and depth < _MAX_ALIAS_DEPTH:
+            return value_origin(context, value, depth=depth + 1)
+        binding = context.static_resource_provenance.binding(expression.id, expression)
+        if isinstance(binding, ast.Name | ast.arg):
+            return f"binding:{binding.lineno}:{binding.col_offset}"
+    return ast.dump(expression)
+
+
+def overridden_exit(context: PythonFileContext, node: ast.AST) -> bool:
+    parent = context.parents.get(node)
+    while parent is not None and not isinstance(parent, ast.FunctionDef | ast.AsyncFunctionDef):
+        if isinstance(parent, ast.Try | ast.TryStar) and any(
+            isinstance(nested, ast.Return | ast.Raise | ast.Break | ast.Continue)
+            for statement in parent.finalbody
+            for nested in ast.walk(statement)
+        ):
+            return True
+        parent = context.parents.get(parent)
+    return False
+
+
+def local_function(context: PythonFileContext, node: ast.expr) -> ast.FunctionDef | None:
+    if not isinstance(node, ast.Name):
+        return None
+    provenance = context.static_resource_provenance
+    binding = provenance.binding(node.id, node)
+    if not isinstance(binding, ast.FunctionDef) or binding.decorator_list:
+        return None
+    if provenance.scope(binding) is not context.tree or node.id in provenance.mutated:
+        return None
+    for read in provenance.binding_reads(node.id, binding):
+        parent = context.parents.get(read)
+        if not isinstance(parent, ast.Call) or parent.func is not read:
+            return None
+    return binding
+
+
+def function_body(function: ast.FunctionDef) -> list[ast.stmt]:
+    body = function.body
+    if (
+        body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+    ):
+        return body[1:]
+    return body
+
+
+def assignment(statement: ast.stmt) -> LocalAssignment | None:
+    match statement:
+        case ast.Assign(targets=[ast.Name() as target], value=value):
+            return LocalAssignment(target=target, value=value)
+        case ast.AnnAssign(target=ast.Name() as target, value=ast.expr() as value):
+            return LocalAssignment(target=target, value=value)
+        case _:
+            return None
+
+
+def null_test(expression: ast.expr, name: str) -> bool:
+    return (
+        isinstance(expression, ast.Compare)
+        and isinstance(expression.left, ast.Name)
+        and expression.left.id == name
+        and len(expression.ops) == 1
+        and isinstance(expression.ops[0], ast.Is)
+        and len(expression.comparators) == 1
+        and isinstance(expression.comparators[0], ast.Constant)
+        and expression.comparators[0].value is None
+    )
+
+
+def returns_none(statement: ast.stmt) -> bool:
+    return isinstance(statement, ast.Return) and (
+        statement.value is None or (isinstance(statement.value, ast.Constant) and statement.value.value is None)
+    )

{sarj_python_lint-1.81.0 → sarj_python_lint-1.82.0}/src/sarj_python_lint/rules/_registry.py

@@ -216,10 +216,15 @@ if TYPE_CHECKING:
     from collections.abc import Mapping
 
     from sarj_python_lint.rule_base import Rule
+from sarj_python_lint.rules.async_executor_shutdown import AsyncExecutorShutdown
+from sarj_python_lint.rules.async_subprocess_cancellation_cleanup import AsyncSubprocessCancellationCleanup
+from sarj_python_lint.rules.cancel_owned_task_without_join import CancelOwnedTaskWithoutJoin
 from sarj_python_lint.rules.delete_route_returns_no_content import DeleteRouteReturnsNoContent
 from sarj_python_lint.rules.duplicate_adjacent_exception_handler import DuplicateAdjacentExceptionHandler
 from sarj_python_lint.rules.duplicate_closed_pure_helper import DuplicateClosedPureHelper
 from sarj_python_lint.rules.duplicate_pytest_fixture_params import DuplicatePytestFixtureParams
+from sarj_python_lint.rules.failed_probe_zero_threshold import FailedProbeZeroThreshold
+from sarj_python_lint.rules.nan_hidden_by_builtin_min import NanHiddenByBuiltinMin
 from sarj_python_lint.rules.no_conflicting_pydantic_alias_validation import NoConflictingPydanticAliasValidation
 from sarj_python_lint.rules.no_contradictory_type_guard import NoContradictoryTypeGuard
 from sarj_python_lint.rules.no_create_verb_in_post_path import NoCreateVerbInPostPath
@@ -256,6 +261,11 @@ from sarj_python_lint.rules.test_without_explicit_oracle import NoExplicitTestOr
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        AsyncSubprocessCancellationCleanup.id: AsyncSubprocessCancellationCleanup,
+        CancelOwnedTaskWithoutJoin.id: CancelOwnedTaskWithoutJoin,
+        AsyncExecutorShutdown.id: AsyncExecutorShutdown,
+        NanHiddenByBuiltinMin.id: NanHiddenByBuiltinMin,
+        FailedProbeZeroThreshold.id: FailedProbeZeroThreshold,
         PreferGroupedSettings.id: PreferGroupedSettings,
         NoRedundantLocalAlias.id: NoRedundantLocalAlias,
         PytestFixtureReturnsClosedResource.id: PytestFixtureReturnsClosedResource,

sarj_python_lint-1.82.0/src/sarj_python_lint/rules/async_executor_shutdown.py

@@ -0,0 +1,135 @@
+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,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._async_lifecycle import AsyncApiProof, method_receiver
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_EXECUTORS = ("concurrent.futures.ThreadPoolExecutor", "concurrent.futures.ProcessPoolExecutor")
+_BAD = "from concurrent.futures import ThreadPoolExecutor\n\nasync def close():\n    executor = ThreadPoolExecutor()\n    executor.shutdown(wait=True)\n"
+_GOOD = "import asyncio\nfrom concurrent.futures import ThreadPoolExecutor\n\nasync def close():\n    executor = ThreadPoolExecutor()\n    await asyncio.to_thread(executor.shutdown, wait=True)\n"
+
+
+@final
+class AsyncExecutorShutdown(Rule):
+    id = "async-executor-shutdown"
+    code = "SARJ540"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Run waiting executor shutdown outside the async event-loop thread.",
+        rationale="Executor.shutdown waits for workers by default; invoking it directly in an async function can block the event loop and delay unrelated service work or cancellation.",
+        remediation="Await asyncio.to_thread(executor.shutdown, wait=True), or use the application's explicit nonblocking shutdown policy after arranging worker ownership and completion.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Requires a stable direct assignment from an import-proven concurrent.futures ThreadPoolExecutor or ProcessPoolExecutor constructor and a direct shutdown call in an executing async function body.",
+            "Only omitted wait or literal wait=True is reported. Literal wait=False, dynamic arguments, nested synchronous callbacks, custom factories, borrowed receivers, context-managed bindings and explicit receiver/API mutation are excluded.",
+            "Stable enclosing-function and module bindings are recognized. Ordinary argument passing does not erase the constructor identity; external monkey-patching inside opaque consumers and runtime replacement of stdlib modules are not inferred.",
+            "Unknown bound-method consumers, receiver aliases/storage, conditional imports, namespace escapes, reflection, wildcard imports and generated files conservatively abstain. No automatic shutdown-policy change is offered.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="waiting-shutdown-in-async",
+                title="Waiting shutdown runs on the event-loop thread",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/lifecycle.py", _BAD),),
+                focus_path=PurePosixPath("app/lifecycle.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="shutdown-in-worker-thread",
+                title="Await waiting shutdown outside the event-loop thread",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/lifecycle.py", _GOOD),),
+                focus_path=PurePosixPath("app/lifecycle.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if "shutdown" not in context.symbol_source or context.generated or context.tree is None:
+            return []
+        proof = AsyncApiProof(context)
+        diagnostics: list[Diagnostic] = []
+        for call in context.nodes(ast.Call):
+            receiver = method_receiver(call, frozenset({"shutdown"}))
+            if receiver is None or not isinstance(proof.provenance.scope(call), ast.AsyncFunctionDef):
+                continue
+            if not _waiting_shutdown(call):
+                continue
+            assigned = proof.assignment(receiver, call)
+            if assigned is None:
+                continue
+            binding = assigned.binding
+            value = assigned.value
+            if not isinstance(value, ast.Call) or not any(proof.imported(value.func, name) for name in _EXECUTORS):
+                continue
+            if not _unchanged_receiver(proof, binding) or is_suppressed(context.source_lines, call.lineno, self.code):
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    path=context.path,
+                    line=call.lineno,
+                    col=call.col_offset + 1,
+                    code=self.code,
+                    severity=Severity.WARNING,
+                    message="waiting Executor.shutdown runs on the event-loop thread; await an offloaded shutdown after arranging worker ownership",
+                )
+            )
+        return diagnostics
+
+
+def _waiting_shutdown(call: ast.Call) -> bool:
+    if len(call.args) > 1 or any(keyword.arg not in {"wait", "cancel_futures"} for keyword in call.keywords):
+        return False
+    values = [*call.args, *(keyword.value for keyword in call.keywords if keyword.arg == "wait")]
+    return not values or (len(values) == 1 and isinstance(values[0], ast.Constant) and values[0].value is True)
+
+
+def _unchanged_receiver(proof: AsyncApiProof, binding: ast.Name) -> bool:
+    for read in proof.provenance.binding_reads(binding.id, binding):
+        parent = proof.context.parents.get(read)
+        if isinstance(parent, ast.Call) and read in parent.args:
+            continue
+        if isinstance(parent, ast.keyword) and isinstance(proof.context.parents.get(parent), ast.Call):
+            continue
+        if (
+            not isinstance(parent, ast.Attribute)
+            or parent.value is not read
+            or parent.attr in {"__dict__", "__setattr__", "__delattr__", "__getattribute__"}
+        ):
+            return False
+        consumer = proof.context.parents.get(parent)
+        if isinstance(consumer, ast.Call) and consumer.func is parent:
+            continue
+        if (
+            isinstance(consumer, ast.Call)
+            and parent in consumer.args
+            and proof.imported(consumer.func, "asyncio.to_thread")
+        ):
+            continue
+        return False
+    return True