sarj-python-lint 0.6.0__tar.gz → 0.7.0__tar.gz

{sarj_python_lint-0.6.0 → sarj_python_lint-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.6.0
+Version: 0.7.0
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://github.com/sarj-ai/standards/tree/main/packages/python
 Project-URL: Repository, https://github.com/sarj-ai/standards

{sarj_python_lint-0.6.0 → sarj_python_lint-0.7.0}/pyproject.toml

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

{sarj_python_lint-0.6.0 → sarj_python_lint-0.7.0}/src/sarj_python_lint/__main__.py

@@ -66,6 +66,18 @@ def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
     return diags
 
 
+class _Args(argparse.Namespace):
+    cmd: str | None
+    rule: list[str]
+    files: list[Path]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.cmd = None
+        self.rule = []
+        self.files = []
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="sarj-python-lint",
@@ -85,18 +97,15 @@ def main(argv: list[str] | None = None) -> int:
 
     sub.add_parser("list-rules", help="List available rule IDs.")
 
-    args = parser.parse_args(argv)
-    cmd: str | None = args.cmd
+    args = parser.parse_args(argv, namespace=_Args())
 
-    if cmd == "list-rules":
+    if args.cmd == "list-rules":
         for rid, cls in sorted(REGISTRY.items()):
             inst = cls()
             sys.stdout.write(f"{inst.code:8}  {rid:40}  {inst.description}\n")
         return 0
 
-    rule_ids: list[str] = args.rule
-    files: list[Path] = args.files
-    diags = _check(rule_ids, files)
+    diags = _check(args.rule, args.files)
     for d in diags:
         sys.stdout.write(d.format() + "\n")
     return 1 if diags else 0

{sarj_python_lint-0.6.0 → sarj_python_lint-0.7.0}/src/sarj_python_lint/rules/no_aggregation_in_store_query.py

@@ -82,9 +82,9 @@ def _strip_sql_comments(text: str) -> str:
 class NoAggregationInStoreQuery(Rule):
     """DISTINCT / GROUP BY / COUNT in a store query — aggregate in ClickHouse."""
 
-    id = "no-aggregation-in-store-query"
-    code = "SARJ020"
-    description = (
+    id: str = "no-aggregation-in-store-query"
+    code: str = "SARJ020"
+    description: str = (
         "DISTINCT / GROUP BY / COUNT in a Postgres store query — push heavy "
         "aggregation to the columnar mirror (ClickHouse / BigQuery)."
     )

{sarj_python_lint-0.6.0 → sarj_python_lint-0.7.0}/src/sarj_python_lint/rules/no_fat_try_blocks.py

@@ -1,4 +1,4 @@
-"""SARJ007: `try` block whose body has more than 3 top-level statements.
+"""SARJ007: `try` block with more than 3 top-level statements that can raise.
 
 A fat `try` body obscures which statement is actually expected to raise and
 widens the blast radius of the `except` handlers: unrelated failures get
@@ -6,13 +6,20 @@ caught (and often swallowed or mis-reported) by handlers written for a
 different operation. Keep the `try` skinny — isolate the throwing
 statement(s) and move the non-throwing setup and follow-up work outside.
 
-Only the top-level statements of the `try` body are counted; statements
-nested inside an `if` / `with` / loop within the body count as the single
-compound statement that contains them. Nested `try` blocks are checked
-independently. `try*` (PEP 654 except-groups) is held to the same limit.
-
-This is a direct Python port of the org's ESLint restriction
-`TryStatement > BlockStatement[body.length > 3]` in eslint.strict.mjs.
+Two refinements keep the count aligned with that intent and avoid the
+false-positive patterns that dominated real-world suppressions:
+
+* Only top-level statements that *can raise* are counted — a statement counts
+  toward the limit only if its subtree contains a call or `await`. Pure
+  assignments / name-rebinds (`self.x = y`, `a = b.c`) don't obscure a throwing
+  statement and are free. Statements nested inside an `if` / `with` / loop
+  count as the single compound statement that contains them. Nested `try`
+  blocks are checked independently. `try*` (PEP 654) is held to the same limit.
+* `try` blocks that carry an `else` or `finally` clause are exempt. Those
+  clauses are a deliberate success/cleanup contract that couples the body to
+  the handler (a `finally` that tears down a resource, an `else`/`finally` that
+  reads a status the body set) — statements can't be freely hoisted out without
+  changing semantics, so the length check is counterproductive there.
 
 Instead of:
     try:
@@ -52,12 +59,18 @@ if TYPE_CHECKING:
 _MAX_TRY_BODY_STATEMENTS = 3
 
 
+def _can_raise(stmt: ast.stmt) -> bool:
+    """True if the statement's subtree contains a call or `await` — i.e. it can
+    plausibly raise. Pure assignments / rebinds with no call do not count."""
+    return any(isinstance(n, (ast.Call, ast.Await)) for n in ast.walk(stmt))
+
+
 class NoFatTryBlocks(Rule):
-    """Try body longer than 3 statements — isolate the throwing statement(s)."""
+    """Try body with too many throwing statements — isolate the one that raises."""
 
     id: str = "no-fat-try-blocks"
     code: str = "SARJ007"
-    description: str = "Try block body exceeds 3 statements — keep try blocks skinny."
+    description: str = "Try block has too many throwing statements — keep try blocks skinny."
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
@@ -69,7 +82,12 @@ class NoFatTryBlocks(Rule):
         for node in ast.walk(tree):
             if not isinstance(node, (ast.Try, ast.TryStar)):
                 continue
-            if len(node.body) <= _MAX_TRY_BODY_STATEMENTS:
+            # An `else`/`finally` clause is a deliberate success/cleanup contract
+            # that couples the body to the handler — don't fight it on length.
+            if node.orelse or node.finalbody:
+                continue
+            throwing = sum(_can_raise(stmt) for stmt in node.body)
+            if throwing <= _MAX_TRY_BODY_STATEMENTS:
                 continue
             diags.append(
                 Diagnostic(
@@ -78,7 +96,7 @@ class NoFatTryBlocks(Rule):
                     col=node.col_offset + 1,
                     code=self.code,
                     message=(
-                        f"try block has {len(node.body)} statements "
+                        f"try block has {throwing} statements that can raise "
                         f"(max {_MAX_TRY_BODY_STATEMENTS}) — try blocks should "
                         "isolate the throwing statement(s); move non-throwing "
                         "work outside the try."

{sarj_python_lint-0.6.0 → sarj_python_lint-0.7.0}/src/sarj_python_lint/rules/no_query_with_many_joins.py

@@ -61,9 +61,9 @@ def _strip_sql_comments(text: str) -> str:
 class NoQueryWithManyJoins(Rule):
     """A SQL query with 3+ JOINs is too entangled — split it or denormalize."""
 
-    id = "no-query-with-many-joins"
-    code = "SARJ019"
-    description = (
+    id: str = "no-query-with-many-joins"
+    code: str = "SARJ019"
+    description: str = (
         "SQL query with 3 or more JOINs — split the query or denormalize instead of fanning across many tables."
     )
 

{sarj_python_lint-0.6.0 → sarj_python_lint-0.7.0}/src/sarj_python_lint/rules/no_select_star.py

@@ -67,9 +67,9 @@ def _has_real_select_star(sql: str) -> bool:
 class NoSelectStar(Rule):
     """`SELECT *` in a store query — list the columns explicitly."""
 
-    id = "no-select-star"
-    code = "SARJ021"
-    description = (
+    id: str = "no-select-star"
+    code: str = "SARJ021"
+    description: str = (
         "SELECT * in a store query — name the columns; * over-fetches and breaks "
         "class_row mapping when the schema changes."
     )

sarj_python_lint-0.7.0/src/sarj_python_lint/rules/no_sequential_await.py

@@ -0,0 +1,196 @@
+"""SARJ001: detect the `for x in xs: await f(x)` gather antipattern.
+
+Sequential `await` in a for-loop serializes I/O that could be parallelized
+with `asyncio.gather([f(x) for x in xs])`. The performance gap is often 10-100x
+for network-bound work (HTTP, DB queries, LLM calls).
+
+Deliberately narrow, to flag the textbook antipattern and almost nothing else —
+an over-broad version drowned real signal under suppressions. The rule fires
+only for:
+
+* a `for` loop whose body is **straight-line** (no `if`/`try`/`with`/`return`/
+  `break`/`continue`/`raise`/nested loop — those signal conditional or ordered
+  logic, not a parallel map) and awaits a call that **uses the loop variable**
+  (so each iteration is a distinct, independent call); or
+* a comprehension / generator expression with an `await` in its element or a
+  per-element `if` (those have no ordered side effects).
+
+It does NOT fire for: `while` loops (pagination, polling, queue drains — length
+unknown, inherently sequential), a loop's once-evaluated iterable
+(`for x in await fetch()`), `async for`, test modules (intentional ordering),
+or a `for` body containing control flow. Those were the false-positive sources.
+
+References:
+- https://docs.python.org/3/library/asyncio-task.html#running-tasks-concurrently
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _is_test_path(path: Path) -> bool:
+    name = path.name
+    if name == "conftest.py" or name.startswith("test_") or name.endswith("_test.py"):
+        return True
+    return any(part in {"tests", "test"} for part in path.parts)
+
+
+class NoSequentialAwait(Rule):
+    """Sequential await calls in a loop that could be parallelized."""
+
+    id: str = "no-sequential-await"
+    code: str = "SARJ001"
+    description: str = "Sequential `await` in a for-loop — prefer asyncio.gather."
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if _is_test_path(path):
+            return []
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        visitor = _SequentialAwaitVisitor()
+        visitor.visit(tree)
+        diags = [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message=("Sequential `await` inside `for` — prefer `asyncio.gather([f(x) for x in xs])`."),
+            )
+            for node in visitor.hits
+        ]
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+# A loop's *iterable* is evaluated once in the enclosing scope, NOT per element:
+# `for x in await fetch()` / `{x for x in await fetch()}` await once. Iterables
+# are visited *before* the loop is pushed, so an await there attributes to an
+# enclosing loop (if any), not this one.
+_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
+
+# Top-level body statements that signal conditional or ordered logic rather than
+# a straight-line parallel map. A `for` whose body contains any of these is not
+# treated as the gather antipattern.
+_CONTROL_FLOW = (
+    ast.If,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.With,
+    ast.AsyncWith,
+    ast.Try,
+    ast.Match,
+    ast.Return,
+    ast.Break,
+    ast.Continue,
+    ast.Raise,
+)
+
+
+def _names(node: ast.AST) -> set[str]:
+    return {n.id for n in ast.walk(node) if isinstance(n, ast.Name)}
+
+
+def _is_gather_antipattern(node: ast.For) -> bool:
+    """True for `for x in xs: <straight-line body awaiting a call that uses x>`."""
+    if any(isinstance(stmt, _CONTROL_FLOW) for stmt in node.body):
+        return False
+    targets = _names(node.target)
+    for stmt in node.body:
+        for inner in ast.walk(stmt):
+            if isinstance(inner, ast.Await) and _names(inner) & targets:
+                return True
+    return False
+
+
+class _SequentialAwaitVisitor(ast.NodeVisitor):
+    """Single O(n) pass: flag the first per-iteration `await` of each loop.
+
+    Maintains a stack of enclosing loops within the current function. The stack
+    resets at function boundaries so a loop in an outer function never claims an
+    `await` in a nested one. Each loop is flagged at most once. A loop's
+    once-evaluated iterable is excluded (see module comment).
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._loops: list[ast.AST] = []
+        self._flagged: set[int] = set()
+        self.hits: list[ast.Await] = []
+
+    def _flag_if_in_loop(self, node: ast.Await) -> None:
+        if self._loops:
+            loop = self._loops[-1]
+            if id(loop) not in self._flagged:
+                self._flagged.add(id(loop))
+                self.hits.append(node)
+
+    def visit_For(self, node: ast.For) -> None:
+        # `<iter>` runs once in the enclosing scope; visit it before entering.
+        self.visit(node.iter)
+        # Only a straight-line per-element-await body is the gather antipattern;
+        # control-flow bodies (conditional/ordered) are not pushed, so awaits in
+        # them are not flagged for this loop.
+        antipattern = _is_gather_antipattern(node)
+        if antipattern:
+            self._loops.append(node)
+        self.visit(node.target)
+        for stmt in (*node.body, *node.orelse):
+            self.visit(stmt)
+        if antipattern:
+            self._loops.pop()
+
+    def _visit_comprehension(self, node: ast.AST, elements: tuple[ast.expr, ...]) -> None:
+        gens: list[ast.comprehension] = node.generators  # pyright: ignore[reportAttributeAccessIssue]
+        # Outermost iterable is evaluated once in the enclosing scope.
+        self.visit(gens[0].iter)
+        self._loops.append(node)
+        for elt in elements:
+            self.visit(elt)
+        self.visit(gens[0].target)
+        for cond in gens[0].ifs:
+            self.visit(cond)
+        # Later generators iterate per element of the preceding one.
+        for gen in gens[1:]:
+            self.visit(gen.iter)
+            self.visit(gen.target)
+            for cond in gen.ifs:
+                self.visit(cond)
+        self._loops.pop()
+
+    def visit_ListComp(self, node: ast.ListComp) -> None:
+        self._visit_comprehension(node, (node.elt,))
+
+    def visit_SetComp(self, node: ast.SetComp) -> None:
+        self._visit_comprehension(node, (node.elt,))
+
+    def visit_GeneratorExp(self, node: ast.GeneratorExp) -> None:
+        self._visit_comprehension(node, (node.elt,))
+
+    def visit_DictComp(self, node: ast.DictComp) -> None:
+        self._visit_comprehension(node, (node.key, node.value))
+
+    @override
+    def generic_visit(self, node: ast.AST) -> None:
+        if isinstance(node, _SCOPES):
+            saved = self._loops
+            self._loops = []
+            super().generic_visit(node)
+            self._loops = saved
+        elif isinstance(node, ast.Await):
+            self._flag_if_in_loop(node)
+            super().generic_visit(node)
+        else:
+            super().generic_visit(node)

{sarj_python_lint-0.6.0 → sarj_python_lint-0.7.0}/src/sarj_python_lint/rules/store_insert_requires_on_conflict.py

@@ -61,9 +61,9 @@ def _strip_sql_comments(text: str) -> str:
 class StoreInsertRequiresOnConflict(Rule):
     """Embedded INSERT in store code without ON CONFLICT — store writes must be upserts."""
 
-    id = "store-insert-requires-on-conflict"
-    code = "SARJ018"
-    description = "Embedded SQL INSERT in store code without ON CONFLICT — store writes must be idempotent upserts."
+    id: str = "store-insert-requires-on-conflict"
+    code: str = "SARJ018"
+    description: str = "Embedded SQL INSERT in store code without ON CONFLICT — store writes must be idempotent upserts."
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:

sarj_python_lint-0.6.0/src/sarj_python_lint/rules/no_sequential_await.py

@@ -1,94 +0,0 @@
-"""SARJ001: detect `for x in xs: await f(x)` patterns.
-
-Sequential `await` in a for-loop serializes I/O that could be parallelized
-with `asyncio.gather([f(x) for x in xs])`. The performance gap is often 10-100x
-for network-bound work (HTTP, DB queries, LLM calls).
-
-References:
-- https://docs.python.org/3/library/asyncio-task.html#running-tasks-concurrently
-"""
-
-from __future__ import annotations
-
-import ast
-from typing import TYPE_CHECKING, override
-
-from sarj_python_lint.rule_base import Diagnostic, Rule
-
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-class NoSequentialAwait(Rule):
-    """Sequential await calls in a loop that could be parallelized."""
-
-    id: str = "no-sequential-await"
-    code: str = "SARJ001"
-    description: str = "Sequential `await` in a for-loop — prefer asyncio.gather."
-
-    @override
-    def check(self, path: Path, source: str) -> list[Diagnostic]:
-        try:
-            tree = ast.parse(source, filename=str(path))
-        except SyntaxError:
-            return []
-        visitor = _SequentialAwaitVisitor()
-        visitor.visit(tree)
-        diags = [
-            Diagnostic(
-                path=path,
-                line=node.lineno,
-                col=node.col_offset + 1,
-                code=self.code,
-                message=(
-                    "Sequential `await` inside `for` — prefer "
-                    "`asyncio.gather([f(x) for x in xs])`."
-                ),
-            )
-            for node in visitor.hits
-        ]
-        diags.sort(key=lambda d: (d.line, d.col))
-        return diags
-
-
-# Loop-like constructs whose body runs once per element: `await` inside one of
-# them serializes the iterations. `async for` is deliberately absent — it is the
-# parallel-iteration construct, not the antipattern.
-_LOOPS = (ast.For, ast.While, ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)
-_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
-
-
-class _SequentialAwaitVisitor(ast.NodeVisitor):
-    """Single O(n) pass: flag the first `await` of each enclosing loop.
-
-    Maintains a stack of enclosing loops within the current function. The stack
-    resets at function boundaries so a loop in an outer function never claims an
-    `await` in a nested one. Each loop is flagged at most once.
-    """
-
-    def __init__(self) -> None:
-        self._loops: list[ast.AST] = []
-        self._flagged: set[int] = set()
-        self.hits: list[ast.Await] = []
-
-    @override
-    def generic_visit(self, node: ast.AST) -> None:
-        if isinstance(node, _SCOPES):
-            saved = self._loops
-            self._loops = []
-            super().generic_visit(node)
-            self._loops = saved
-        elif isinstance(node, _LOOPS):
-            self._loops.append(node)
-            super().generic_visit(node)
-            self._loops.pop()
-        elif isinstance(node, ast.Await):
-            if self._loops:
-                loop = self._loops[-1]
-                if id(loop) not in self._flagged:
-                    self._flagged.add(id(loop))
-                    self.hits.append(node)
-            super().generic_visit(node)
-        else:
-            super().generic_visit(node)