sarj-python-lint 1.26.2__tar.gz → 1.27.0__tar.gz

{sarj_python_lint-1.26.2 → sarj_python_lint-1.27.0}/PKG-INFO

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

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

{sarj_python_lint-1.26.2 → sarj_python_lint-1.27.0}/src/sarj_python_lint/rule_base.py

@@ -37,7 +37,7 @@ TESTS_DIR: Final = "packages/python/tests/rules"
 
 # Keep SARJ suppressions separate because Ruff removes unknown `noqa` codes.
 _SARJ_NOQA_RE = re.compile(
-    r"#\s*sarj-noqa(?::\s*([A-Za-z0-9_, ]+))?",
+    r"#\s*sarj-noqa\b(?::\s*([A-Za-z0-9_, ]+))?",
     re.IGNORECASE,
 )
 
@@ -49,12 +49,25 @@ def is_suppressed(source_lines: Sequence[str], line: int, code: str) -> bool:
     m = _SARJ_NOQA_RE.search(text)
     if not m:
         return False
+    from sarj_python_lint.rules._suppression_comments import comment_lines  # ruff: ignore[import-outside-top-level] -- comment scanner depends on rule_base.
+
+    comment = comment_lines(tuple(source_lines)).get(line, "")
+    m = _SARJ_NOQA_RE.search(comment)
+    if m is None:
+        return False
     codes_str = m.group(1)
-    if not codes_str:
-        # A bare sarj-noqa intentionally suppresses every SARJ code on its line.
-        return True
-    codes = {val.upper() for c in codes_str.split(",") if (val := c.strip())}
-    return code.upper() in codes
+    trailing = comment[m.end() :]
+    if codes_str is None:
+        # A complete bare marker preserves the existing all-codes waiver contract.
+        return not (trailing and (not trailing[0].isspace() or trailing.lstrip().startswith(":")))
+    reason = trailing.lstrip()
+    single_dash_reason = reason.startswith("-") and (codes_str[-1:].isspace() or trailing[:1].isspace())
+    if reason and not reason.startswith(("--", "—", "–")) and not single_dash_reason:
+        return False
+    parts = tuple(part.strip() for part in codes_str.split(","))
+    if any(not part for part in parts):
+        return False
+    return code.upper() in {part.upper() for part in parts}
 
 
 class ColumnEncoding(StrEnum):

{sarj_python_lint-1.26.2 → sarj_python_lint-1.27.0}/src/sarj_python_lint/rules/_registry.py

@@ -53,6 +53,7 @@ from sarj_python_lint.rules.no_first_party_private_import import (
     NoFirstPartyPrivateImport,
 )
 from sarj_python_lint.rules.no_fixed_sleep_before_assert import NoFixedSleepBeforeAssert
+from sarj_python_lint.rules.no_fixed_sleep_in_loop import NoFixedSleepInLoop
 from sarj_python_lint.rules.no_frozen_after_validator_field_write import (
     NoFrozenAfterValidatorFieldWrite,
 )
@@ -169,6 +170,7 @@ from sarj_python_lint.rules.repeated_test_composition import RepeatedTestComposi
 from sarj_python_lint.rules.require_explicit_contract_implementation import RequireExplicitContractImplementation
 from sarj_python_lint.rules.require_explicit_psycopg_transaction import RequireExplicitPsycopgTransaction
 from sarj_python_lint.rules.require_explicit_service_contract import RequireExplicitServiceContract
+from sarj_python_lint.rules.require_injectable_retry_sleep import RequireInjectableRetrySleep
 from sarj_python_lint.rules.require_keyword_only_swap_prone_params import (
     RequireKeywordOnlySwapProneParams,
 )
@@ -208,6 +210,8 @@ if TYPE_CHECKING:
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        RequireInjectableRetrySleep.id: RequireInjectableRetrySleep,
+        NoFixedSleepInLoop.id: NoFixedSleepInLoop,
         NoInterpreterSourceArguments.id: NoInterpreterSourceArguments,
         NoUnusedCopyResult.id: NoUnusedCopyResult,
         NoBeforeValidatorInputMutation.id: NoBeforeValidatorInputMutation,

{sarj_python_lint-1.26.2 → sarj_python_lint-1.27.0}/src/sarj_python_lint/rules/_suppression_comments.py

@@ -1,11 +1,18 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from functools import lru_cache
 import tokenize
+from types import MappingProxyType
+from typing import TYPE_CHECKING
 
 from sarj_python_lint.rules._comments import all_comments
 
 
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
 @dataclass(frozen=True, slots=True)
 class Comment:
     line: int
@@ -34,3 +41,10 @@ def scan_comments_or_none(source: str) -> list[Comment] | None:
         return scan_comments(source)
     except tokenize.TokenError, SyntaxError:
         return None
+
+
+@lru_cache(maxsize=1)
+def comment_lines(source_lines: tuple[str, ...]) -> Mapping[int, str]:
+    return MappingProxyType(
+        {comment.line: "# " + comment.body for comment in scan_comments_or_none("\n".join(source_lines)) or ()}
+    )

sarj_python_lint-1.27.0/src/sarj_python_lint/rules/no_fixed_sleep_in_loop.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import ast
+from collections import Counter
+from pathlib import PurePosixPath
+import re
+from typing import TYPE_CHECKING, ClassVar, Final, NamedTuple, 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._paths import is_test_path, is_test_support_path
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_ASYNC_SLEEPS: Final = frozenset({"asyncio.sleep", "anyio.sleep", "trio.sleep"})
+_BLOCKING_SLEEP: Final = "time.sleep"
+_DURATION_KEYWORDS: Final = frozenset({"delay", "seconds"})
+_CONSTANT_NAME: Final = re.compile(r"_*[A-Z][A-Z0-9_]*")
+_LOOPS: Final = (ast.For, ast.AsyncFor, ast.While)
+_FUNCTIONS: Final = (ast.FunctionDef, ast.AsyncFunctionDef)
+_SCOPES: Final = (*_FUNCTIONS, ast.Lambda, ast.ClassDef)
+_MESSAGE: Final = (
+    "fixed sleep inside a loop makes every iteration wait on the wall clock, including under test; take the "
+    "interval or the sleeper from an injected dependency"
+)
+
+
+@final
+class NoFixedSleepInLoop(Rule):
+    id = "no-fixed-sleep-in-loop"
+    code = "SARJ485"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Do not sleep for a fixed literal interval inside a production loop.",
+        rationale=(
+            "A polling or cleanup loop that sleeps for a literal interval gives tests no seam: every test that "
+            "drives the loop pays the whole interval in real time, and replacing the module's sleep is a "
+            "monkeypatch that SARJ445 forbids. Suites slow down one hardcoded interval at a time."
+        ),
+        remediation=(
+            "Route the interval through a constructor or configuration parameter, or call an injected sleeper or "
+            "clock, so tests can pass a zero interval or a recording fake. Keep a literal only behind an exact "
+            "SARJ485 suppression that names why the interval must never change under test."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only awaited asyncio.sleep, anyio.sleep, and trio.sleep, and time.sleep in synchronous functions, are inspected; import aliases are followed and shadowed names abstain. time.sleep in an async function is left to Ruff ASYNC251.",
+            "A duration is fixed when it folds with +, -, *, /, and // from numeric literals and UPPER_CASE constants bound once at module scope in the same file to such a literal; zero and negative results are yields, not waits.",
+            "Imported, reassigned, or shadowed constants, lowercase names, attributes including class constants, subscripts, and calls are treated as configurable and are not reported.",
+            "The sleep must sit in the body of a for, async for, or while loop inside the same function; loop else clauses, module-level and class-level loops, and loops in an enclosing function across a nested def, lambda, or class are not reported.",
+            "Test modules, test directories, conftest.py, test-support paths, and generated files are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="polling-loop-sleeps-literal",
+                title="A polling loop sleeps for a hardcoded interval",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/jobs.py",
+                        "import asyncio\n\n\nasync def wait_until_done(job):\n    while not await job.done():\n"
+                        "        await asyncio.sleep(2)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/jobs.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="polling-loop-sleeps-injected-interval",
+                title="A polling loop sleeps for an injected interval",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/jobs.py",
+                        "import asyncio\n\n\nclass JobWaiter:\n    def __init__(self, poll_seconds: float) -> None:\n"
+                        "        self._poll_seconds = poll_seconds\n\n    async def wait_until_done(self, job):\n"
+                        "        while not await job.done():\n            await asyncio.sleep(self._poll_seconds)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/jobs.py"),
+                expected_count=0,
+                public=True,
+            ),
+            RuleExample(
+                example_id="blocking-loop-sleeps-literal",
+                title="A synchronous retry loop blocks for a hardcoded interval",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/health.py",
+                        "import time\n\n\ndef wait_for_health(probe):\n    for _ in range(30):\n"
+                        "        if probe():\n            return\n        time.sleep(0.5)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/health.py"),
+                expected_count=1,
+                scenario="blocking-sleep",
+                public=True,
+            ),
+            RuleExample(
+                example_id="blocking-loop-calls-injected-sleeper",
+                title="A synchronous retry loop calls an injected sleeper",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/health.py",
+                        "from collections.abc import Callable\n\n\n"
+                        "def wait_for_health(probe, sleep: Callable[[float], None]):\n    for _ in range(30):\n"
+                        "        if probe():\n            return\n        sleep(0.5)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/health.py"),
+                expected_count=0,
+                scenario="blocking-sleep",
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        path = context.path
+        if (
+            "sleep" not in context.source
+            or is_test_path(path)
+            or is_test_support_path(path)
+            or context.generated
+            or context.tree is None
+        ):
+            return []
+        sleeps = [
+            sleep
+            for call in context.nodes(ast.Call)
+            if (sleep := _sleep(context, call)) is not None and _in_function_loop_body(context, sleep.reported)
+        ]
+        if not sleeps:
+            return []
+        constants = _module_constants(context)
+        findings = [
+            Diagnostic(
+                path=path,
+                line=reported.lineno,
+                col=reported.col_offset + 1,
+                code=self.code,
+                message=_MESSAGE,
+                severity=Severity.WARNING,
+            )
+            for reported, duration in sleeps
+            if (seconds := _folded_seconds(duration, constants)) is not None
+            and seconds > 0
+            and not is_suppressed(context.source_lines, reported.lineno, self.code)
+        ]
+        return sorted(findings, key=lambda finding: (finding.line, finding.col))
+
+
+class _Sleep(NamedTuple):
+    reported: ast.expr
+    duration: ast.expr | None
+
+
+def _sleep(context: PythonFileContext, call: ast.Call) -> _Sleep | None:
+    name = context.imports.resolved_qualified_name(call.func)
+    parent = context.parents.get(call)
+    if name in _ASYNC_SLEEPS and isinstance(parent, ast.Await):
+        return _Sleep(parent, _duration(call))
+    if name == _BLOCKING_SLEEP and isinstance(_owner(context, call), ast.FunctionDef):
+        return _Sleep(call, _duration(call))
+    return None
+
+
+def _duration(call: ast.Call) -> ast.expr | None:
+    if call.args:
+        return call.args[0]
+    return next((keyword.value for keyword in call.keywords if keyword.arg in _DURATION_KEYWORDS), None)
+
+
+def _module_constants(context: PythonFileContext) -> dict[str, float]:
+    tree = context.tree
+    if tree is None:
+        return {}
+    assignments: dict[str, ast.expr] = {}
+    for statement in tree.body:
+        match statement:
+            case (
+                ast.Assign(targets=[ast.Name(id=name)], value=value)
+                | ast.AnnAssign(target=ast.Name(id=name), value=ast.expr() as value)
+            ) if _CONSTANT_NAME.fullmatch(name):
+                assignments[name] = value
+            case _:
+                pass
+    stores = Counter(node.id for node in context.nodes(ast.Name) if not isinstance(node.ctx, ast.Load))
+    rebound = {
+        *(node.arg for node in context.nodes(ast.arg)),
+        *(name for node in context.nodes(ast.Global, ast.Nonlocal) for name in node.names),
+        *(node.name for node in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)),
+        *context.imports.bindings,
+    }
+    return {
+        name: seconds
+        for name, value in assignments.items()
+        if stores[name] == 1 and name not in rebound and (seconds := _folded_seconds(value, {})) is not None
+    }
+
+
+def _folded_seconds(node: ast.expr | None, constants: Mapping[str, float]) -> float | None:
+    match node:
+        case ast.Constant(value=bool()):
+            return None
+        case ast.Constant(value=int() | float() as value):
+            return value
+        case ast.Name(id=name):
+            return constants.get(name)
+        case ast.UnaryOp(op=ast.UAdd(), operand=operand):
+            return _folded_seconds(operand, constants)
+        case ast.UnaryOp(op=ast.USub(), operand=operand):
+            value = _folded_seconds(operand, constants)
+            return None if value is None else -value
+        case ast.BinOp(left=left, op=op, right=right):
+            lhs, rhs = _folded_seconds(left, constants), _folded_seconds(right, constants)
+            return None if lhs is None or rhs is None else _arithmetic(op, lhs, rhs)
+        case _:
+            return None
+
+
+def _arithmetic(op: ast.operator, lhs: float, rhs: float) -> float | None:
+    match op:
+        case ast.Add():
+            return lhs + rhs
+        case ast.Sub():
+            return lhs - rhs
+        case ast.Mult():
+            return lhs * rhs
+        case ast.Div() if rhs:
+            return lhs / rhs
+        case ast.FloorDiv() if rhs:
+            return lhs // rhs
+        case _:
+            return None
+
+
+def _owner(context: PythonFileContext, node: ast.AST) -> ast.AST | None:
+    current = context.parents.get(node)
+    while current is not None and not isinstance(current, _SCOPES):
+        current = context.parents.get(current)
+    return current
+
+
+def _in_function_loop_body(context: PythonFileContext, node: ast.AST) -> bool:
+    in_loop = False
+    child, parent = node, context.parents.get(node)
+    while parent is not None and not isinstance(parent, _SCOPES):
+        if isinstance(parent, _LOOPS) and any(statement is child for statement in parent.body):
+            in_loop = True
+        child, parent = parent, context.parents.get(parent)
+    return in_loop and isinstance(parent, _FUNCTIONS)

sarj_python_lint-1.27.0/src/sarj_python_lint/rules/require_injectable_retry_sleep.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, Final, 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._paths import is_test_path, is_test_support_path
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_POLICIES: Final = frozenset(
+    {"tenacity.retry", "tenacity.Retrying", "tenacity.AsyncRetrying", "tenacity.asyncio.AsyncRetrying"}
+)
+_WAIT_MODULES: Final = frozenset({"tenacity", "tenacity.wait"})
+_WALL_CLOCK_SLEEPS: Final = frozenset(
+    {"asyncio.sleep", "anyio.sleep", "trio.sleep", "time.sleep", "tenacity.nap.sleep"}
+)
+_MESSAGE: Final = (
+    "this tenacity policy waits between attempts on the wall clock without a sleep= seam; pass an injected sleep "
+    "so tests exercise retries without real delays"
+)
+
+
+@final
+class RequireInjectableRetrySleep(Rule):
+    id = "require-injectable-retry-sleep"
+    code = "SARJ486"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Pass an injectable sleep to a tenacity retry policy that waits between attempts.",
+        rationale=(
+            "A tenacity policy built with a backoff wait and no sleep argument sleeps on the wall clock. Every test "
+            "that exercises a transient failure pays the backoff, and exhausting an exponential policy costs the "
+            "sum of every interval. Replacing tenacity's sleep from a test is a monkeypatch that SARJ445 forbids."
+        ),
+        remediation=(
+            "Build the policy in a factory or constructor that accepts a sleep callable and pass it as sleep=, or "
+            "accept the wait strategy itself as a dependency. Tests then inject a no-op or recording sleeper, or "
+            "wait_none()."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only calls to tenacity.retry, tenacity.Retrying, and tenacity.AsyncRetrying resolved through imports are inspected; bare @retry, positional arguments, and **kwargs expansion abstain.",
+            "A wait is reported only when it is built inline from tenacity wait_* calls, optionally combined with +; wait_none() and wait_fixed(0) do not wait. A wait read from a name, attribute, or other call is treated as injected.",
+            "Any sleep= argument other than a wall-clock sleep imported from asyncio, anyio, trio, time, or tenacity.nap counts as a seam; the rule does not prove that tests replace it.",
+            "The backoff library has no sleep parameter, so its decorators are not inspected. Test modules, test directories, conftest.py, test-support paths, and generated files are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="retry-backoff-without-sleep",
+                title="A module-level retry decorator backs off on the wall clock",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/retry.py",
+                        "from tenacity import retry, stop_after_attempt, wait_exponential\n\n"
+                        "client_retry = retry(stop=stop_after_attempt(4), wait=wait_exponential(multiplier=2))\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/retry.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="retry-backoff-with-injected-sleep",
+                title="A retry factory passes an injected sleep",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/retry.py",
+                        "from collections.abc import Awaitable, Callable\n\n"
+                        "from tenacity import AsyncRetrying, stop_after_attempt, wait_exponential\n\n\n"
+                        "def client_retrying(sleep: Callable[[float], Awaitable[None]]) -> AsyncRetrying:\n"
+                        "    return AsyncRetrying(sleep=sleep, stop=stop_after_attempt(4), "
+                        "wait=wait_exponential(multiplier=2))\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/retry.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        path = context.path
+        if (
+            "tenacity" not in context.source
+            or is_test_path(path)
+            or is_test_support_path(path)
+            or context.generated
+            or context.tree is None
+        ):
+            return []
+        imports = context.imports
+        findings = [
+            Diagnostic(
+                path=path,
+                line=call.lineno,
+                col=call.col_offset + 1,
+                code=self.code,
+                message=_MESSAGE,
+                severity=Severity.WARNING,
+            )
+            for call in context.nodes(ast.Call)
+            if imports.resolved_qualified_name(call.func) in _POLICIES
+            and _waits_without_seam(call, imports)
+            and not is_suppressed(context.source_lines, call.lineno, self.code)
+        ]
+        return sorted(findings, key=lambda finding: (finding.line, finding.col))
+
+
+def _waits_without_seam(call: ast.Call, imports: ImportIndex) -> bool:
+    if call.args or any(keyword.arg is None for keyword in call.keywords):
+        return False
+    arguments = {keyword.arg: keyword.value for keyword in call.keywords}
+    wait = arguments.get("wait")
+    if wait is None or _wait_strategy(wait, imports) is not True:
+        return False
+    sleep = arguments.get("sleep")
+    return sleep is None or imports.resolved_qualified_name(sleep) in _WALL_CLOCK_SLEEPS
+
+
+def _wait_strategy(node: ast.expr, imports: ImportIndex) -> bool | None:
+    match node:
+        case ast.BinOp(left=left, op=ast.Add(), right=right):
+            parts = (_wait_strategy(left, imports), _wait_strategy(right, imports))
+            return None if None in parts else any(parts)
+        case ast.Call(func=func, args=args, keywords=keywords):
+            module, _, strategy = (imports.resolved_qualified_name(func) or "").rpartition(".")
+            if module not in _WAIT_MODULES or not strategy.startswith("wait_"):
+                return None
+            match strategy, args, keywords:
+                case "wait_none", [], []:
+                    return False
+                case "wait_fixed", [ast.Constant(value=0)], []:
+                    return False
+                case "wait_fixed", [], [ast.keyword(arg="wait", value=ast.Constant(value=0))]:
+                    return False
+                case _:
+                    return True
+        case _:
+            return None