sarj-python-lint 0.12.0__tar.gz → 0.12.1__tar.gz

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.12.0
+Version: 0.12.1
 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.12.0 → sarj_python_lint-0.12.1}/pyproject.toml

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

sarj_python_lint-0.12.1/src/sarj_python_lint/__init__.py

@@ -0,0 +1,6 @@
+"""sarj-python-lint — custom Python + SQL lint rules."""
+
+from sarj_python_lint._version import __version__
+
+
+__all__ = ["__version__"]

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.1}/src/sarj_python_lint/__main__.py

@@ -1,4 +1,4 @@
-"""CLI: sarj-python-lint check --rule <id> [--rule <id2>] [--baseline <json>] <files>"""
+"""CLI: sarj-python-lint check --rule <id> [--rule <id2>] [--baseline <json>] <files>."""
 
 from __future__ import annotations
 
@@ -106,7 +106,12 @@ def _baseline_counts(diags: list[Diagnostic]) -> dict[str, dict[str, int]]:
 
 
 def _apply_baseline(diags: list[Diagnostic], baseline: dict[str, dict[str, int]]) -> list[Diagnostic]:
-    """Suppress up to the baselined count per (path, code); excess diags survive."""
+    """Suppress up to the baselined count per (path, code); excess diags survive.
+
+    Returns:
+        The diagnostics that exceed the baselined count for their (path, code).
+
+    """
     seen: Counter[tuple[str, str]] = Counter()
     out: list[Diagnostic] = []
     for d in diags:

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.1}/src/sarj_python_lint/_secret_names.py

@@ -95,12 +95,16 @@ _CAMEL_RE = re.compile(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|\d+")
 _SEGMENT_RE = re.compile(r"[^A-Za-z0-9]+")
 
 
-def _tokens(identifier: str) -> list[str]:
-    """Ordered lowercase tokens from snake_case + camelCase decomposition.
+def identifier_tokens(identifier: str) -> list[str]:
+    """Return ordered lowercase tokens from snake_case + camelCase decomposition.
 
     Also yields each whole snake/kebab segment lowercased, so a pathological
     mixed-case single word like `ToKeN` (which camel-splitting shreds into
     `to`/`ke`/`n`) still surfaces its intended `token` form.
+
+    Returns:
+        The ordered lowercase tokens decomposed from `identifier`.
+
     """
     tokens: list[str] = []
     for segment in _SEGMENT_RE.split(identifier):
@@ -112,8 +116,13 @@ def _tokens(identifier: str) -> list[str]:
 
 
 def is_secret_name(identifier: str) -> bool:
-    """True if `identifier` names raw secret material (a credential, not metadata)."""
-    tokens = _tokens(identifier)
+    """Report whether `identifier` names raw secret material (a credential, not metadata).
+
+    Returns:
+        True when `identifier` denotes a credential rather than metadata.
+
+    """
+    tokens = identifier_tokens(identifier)
     if tokens and tokens[-1] in _INNOCUOUS_WORDS:
         return False
     if any(tok in _SECRET_WORDS for tok in tokens):
@@ -122,5 +131,10 @@ def is_secret_name(identifier: str) -> bool:
 
 
 def _has_api_key(tokens: list[str]) -> bool:
-    """True if `api` is immediately followed by `key` (the split form of `api_key`)."""
+    """Report whether `api` is immediately followed by `key` (the split form of `api_key`).
+
+    Returns:
+        True when an `api` token is directly followed by a `key` token.
+
+    """
     return any(a == "api" and b == "key" for a, b in pairwise(tokens))

sarj_python_lint-0.12.1/src/sarj_python_lint/_version.py

@@ -0,0 +1,20 @@
+"""Resolve the installed package version, with a source-tree fallback."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def _resolve_version() -> str:
+    """Return the installed distribution version, or a dev sentinel from source.
+
+    Returns:
+        The distribution version string, or ``"0.0.0.dev0"`` when the package is
+        not installed (running straight from a source checkout).
+
+    """
+    try:
+        return version("sarj-python-lint")
+    except PackageNotFoundError:
+        return "0.0.0.dev0"
+
+
+__version__ = _resolve_version()

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rule_base.py

@@ -5,13 +5,13 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 import ast
 from dataclasses import dataclass
+from pathlib import Path
 import re
 from typing import TYPE_CHECKING
 
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
-    from pathlib import Path
 
 
 # Suppression syntax. Two forms supported:
@@ -28,9 +28,13 @@ _SARJ_NOQA_RE = re.compile(
 
 
 def is_suppressed(source_lines: Sequence[str], line: int, code: str) -> bool:
-    """Return True if the diagnostic's line carries a `# sarj-noqa[: CODE]` comment.
+    """Report whether the diagnostic's line carries a `# sarj-noqa[: CODE]` comment.
 
     `line` is 1-based to match Diagnostic.line.
+
+    Returns:
+        True when the line is suppressed for `code`.
+
     """
     if line < 1 or line > len(source_lines):
         return False
@@ -57,7 +61,12 @@ class Diagnostic:
     message: str
 
     def format(self) -> str:
-        """Ruff-compatible: `path:line:col: CODE message`."""
+        """Render the finding ruff-compatibly as `path:line:col: CODE message`.
+
+        Returns:
+            The formatted single-line diagnostic string.
+
+        """
         return f"{self.path}:{self.line}:{self.col}: {self.code} {self.message}"
 
 
@@ -82,7 +91,12 @@ _last_parse: tuple[tuple[str, int, int], ast.Module | None] | None = None
 
 
 def parse_or_none(path: Path, source: str) -> ast.Module | None:
-    """Parse `source`, memoizing the most recent file so N rules share one parse."""
+    """Parse `source`, memoizing the most recent file so N rules share one parse.
+
+    Returns:
+        The parsed module, or None when `source` has a syntax error.
+
+    """
     global _last_parse  # ruff:ignore[global-statement] — single-slot memo; the CLI runs rules per file sequentially
     key = (str(path), len(source), hash(source))
     if _last_parse is not None and _last_parse[0] == key:

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rules/_logging.py

@@ -16,11 +16,15 @@ _LOGGER_FACTORIES = frozenset({"getlogger", "get_logger"})
 
 
 def is_logger_expr(expr: ast.expr) -> bool:
-    """True if `expr` evaluates to a logger.
+    """Report whether `expr` evaluates to a logger.
 
     Resolves the whole receiver chain so adapter/builder/factory calls are
     caught: `logger.bind(...).info(...)`, `logger.opt(lazy=True).debug(...)`,
     `logging.getLogger(__name__).info(...)`, `self.logger.error(...)`.
+
+    Returns:
+        True when `expr` resolves to a logger receiver.
+
     """
     if isinstance(expr, ast.Name):
         return expr.id.lower() in _LOGGER_NAMES

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rules/_sql.py

@@ -19,19 +19,28 @@ if TYPE_CHECKING:
 
 
 def is_store_module(path: Path) -> bool:
-    """True for a store-layer module: basename ends `_store.py`, or the file lives under a `stores/` directory.
+    """Report whether `path` is a store-layer module: basename ends `_store.py`, or lives under a `stores/` directory.
 
     The SQL store-lint rules (SARJ018/020/021) encode store-write semantics —
     column-naming, ON-CONFLICT upserts, no Postgres-side aggregation — that only
     apply to the store layer. Non-store SQL (Flask view handlers, a Django ORM
     SQL generator) legitimately writes `SELECT *`, bare `INSERT`, and `COUNT()`,
     so those files are out of scope.
+
+    Returns:
+        True when `path` belongs to the store layer.
+
     """
     return path.name.endswith("_store.py") or "stores" in path.parts
 
 
 def sql_string_value(node: ast.expr) -> str | None:
-    """Reconstruct a (possibly `+`-concatenated) string literal, else None."""
+    """Reconstruct a (possibly `+`-concatenated) string literal, else None.
+
+    Returns:
+        The reconstructed string, or None when `node` is not a string literal.
+
+    """
     if isinstance(node, ast.Constant) and isinstance(node.value, str):
         return node.value
     if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
@@ -52,6 +61,10 @@ def strip_sql_noise(text: str) -> str:
     preserved so line offsets — and therefore diagnostic positions — do not
     shift. Doubled quotes (`''` / `""`) are SQL's in-string escape and keep the
     scanner inside the literal.
+
+    Returns:
+        `text` with string-literal contents and comment bodies blanked out.
+
     """
     out = list(text)
     n = len(text)

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -12,20 +12,29 @@ are either the prescribed remedy or a bounded per-iteration transform, not the
 O(n²) defect. Per-slot writes (`parts[i] = ...`) and idempotent rebinding
 (`x = f(x)`) are likewise excluded.
 
+A target that is freshly (re)bound earlier in the same loop body — `desc = ...`
+then `desc += suffix`, or a tuple unpack `obj, path = q.popleft()` then
+`path += ...` — is loop-local: it starts empty each iteration, so the growth is
+bounded, not cross-iteration accumulation. Only a target initialised BEFORE the
+loop is a true O(n²) accumulator, so a preceding non-accumulating rebind of the
+target inside the loop suppresses the diagnostic.
+
 References:
 - https://docs.python.org/3/library/stdtypes.html#str.join
 - https://wiki.python.org/moin/PythonSpeed/PerformanceTips
+
 """
 
 from __future__ import annotations
 
 import ast
-from typing import TYPE_CHECKING, override
+from typing import TYPE_CHECKING, TypeGuard, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
 
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
     from pathlib import Path
 
 
@@ -61,6 +70,7 @@ class _ConcatVisitor(ast.NodeVisitor):
     def __init__(self) -> None:
         self._loop_depth: int = 0
         self._string_vars: list[frozenset[str]] = [frozenset()]
+        self._loop_reassigns: list[dict[str, list[int]]] = []
         self.hits: list[ast.AugAssign | ast.Assign] = []
 
     @override
@@ -75,14 +85,38 @@ class _ConcatVisitor(ast.NodeVisitor):
             return
         if isinstance(node, (ast.For, ast.AsyncFor, ast.While)):
             self._loop_depth += 1
+            self._loop_reassigns.append(_loop_local_reassignments(node))
             super().generic_visit(node)
+            self._loop_reassigns.pop()
             self._loop_depth -= 1
             return
-        if self._loop_depth and self._is_in_loop_concat(node):
+        if self._loop_depth and self._is_in_loop_concat(node) and not self._is_loop_local_target(node):
             self.hits.append(node)
         super().generic_visit(node)
 
-    def _is_in_loop_concat(self, node: ast.AST) -> bool:
+    def _is_loop_local_target(self, node: ast.AugAssign | ast.Assign) -> bool:
+        """Report whether the concat target is freshly rebound earlier this iteration.
+
+        A target rebound (not self-accumulated) before the concat inside the same
+        innermost loop body starts empty each pass, so its growth is bounded.
+
+        Returns:
+            True when the target is loop-local rather than a cross-iteration accumulator.
+
+        """
+        target = self._accumulation_target(node)
+        rebinds = self._loop_reassigns[-1].get(ast.unparse(target), ())
+        return any(line < node.lineno for line in rebinds)
+
+    def _accumulation_target(self, node: ast.AugAssign | ast.Assign) -> ast.expr:
+        if isinstance(node, ast.AugAssign):
+            return node.target
+        for target in node.targets:
+            if self._is_self_add_growth(target, node.value):
+                return target
+        return node.targets[0]
+
+    def _is_in_loop_concat(self, node: ast.AST) -> TypeGuard[ast.AugAssign | ast.Assign]:
         if isinstance(node, ast.AugAssign):
             return isinstance(node.op, ast.Add) and self._is_string_growth(node.target, node.value)
         if isinstance(node, ast.Assign):
@@ -90,7 +124,12 @@ class _ConcatVisitor(ast.NodeVisitor):
         return False
 
     def _is_self_add_growth(self, target: ast.expr, value: ast.expr) -> bool:
-        """`s = s + <str>` — a BinOp(Add) rebinding the target to itself-plus-more."""
+        """Report whether `s = s + <str>` rebinds the target to itself-plus-more.
+
+        Returns:
+            True when the assignment is a BinOp(Add) accumulation onto the target.
+
+        """
         if not isinstance(value, ast.BinOp) or not isinstance(value.op, ast.Add):
             return False
         other = _other_add_operand(target, value)
@@ -99,7 +138,12 @@ class _ConcatVisitor(ast.NodeVisitor):
         return self._is_string_growth(target, other)
 
     def _is_string_growth(self, target: ast.expr, rhs: ast.expr) -> bool:
-        """True when appending `rhs` to `target` is single-string accumulation."""
+        """Report whether appending `rhs` to `target` is single-string accumulation.
+
+        Returns:
+            True when the append grows a string-typed target.
+
+        """
         if isinstance(target, ast.Subscript):
             return False
         if _looks_like_string(rhs):
@@ -109,8 +153,76 @@ class _ConcatVisitor(ast.NodeVisitor):
         return False
 
 
+def _loop_local_reassignments(loop: ast.For | ast.AsyncFor | ast.While) -> dict[str, list[int]]:
+    """Map each target rebound inside this loop's own body to the lines that rebind it.
+
+    Only rebinds that are NOT self-accumulation (`s = s + x`) count — those are the
+    defect itself, not a fresh reset. Nested loops / functions / classes are their
+    own scope and are excluded.
+
+    Returns:
+        Target source string → line numbers where it is freshly (re)bound.
+
+    """
+    reassigns: dict[str, list[int]] = {}
+    for stmt in loop.body:
+        _collect_reassignments(stmt, reassigns)
+    return reassigns
+
+
+def _collect_reassignments(node: ast.AST, reassigns: dict[str, list[int]]) -> None:
+    if isinstance(
+        node,
+        (ast.For, ast.AsyncFor, ast.While, ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef),
+    ):
+        return
+    if isinstance(node, ast.Assign):
+        for target in node.targets:
+            for bound in _iter_binding_targets(target):
+                if not _is_accumulation_assign(bound, node.value):
+                    reassigns.setdefault(ast.unparse(bound), []).append(bound.lineno)
+    elif (
+        isinstance(node, ast.AnnAssign)
+        and node.value is not None
+        and not _is_accumulation_assign(node.target, node.value)
+    ):
+        reassigns.setdefault(ast.unparse(node.target), []).append(node.target.lineno)
+    for child in ast.iter_child_nodes(node):
+        _collect_reassignments(child, reassigns)
+
+
+def _iter_binding_targets(target: ast.expr) -> Iterator[ast.Name | ast.Attribute]:
+    """Yield the Name / Attribute leaves a binding target rebinds.
+
+    Subscript leaves (`acc[i] = ...`) are per-slot writes, not a rebind of the
+    accumulator itself, so they are skipped.
+
+    Yields:
+        Each Name / Attribute node the target binds.
+
+    """
+    if isinstance(target, (ast.Tuple, ast.List)):
+        for elt in target.elts:
+            yield from _iter_binding_targets(elt)
+    elif isinstance(target, ast.Starred):
+        yield from _iter_binding_targets(target.value)
+    elif isinstance(target, (ast.Name, ast.Attribute)):
+        yield target
+
+
+def _is_accumulation_assign(target: ast.expr, value: ast.expr) -> bool:
+    if isinstance(value, ast.BinOp) and isinstance(value.op, ast.Add):
+        return _other_add_operand(target, value) is not None
+    return False
+
+
 def _other_add_operand(target: ast.expr, binop: ast.BinOp) -> ast.expr | None:
-    """The non-target operand of `target + x` / `x + target`, or None if absent."""
+    """Return the non-target operand of `target + x` / `x + target`.
+
+    Returns:
+        The other operand, or None if neither side matches the target.
+
+    """
     target_src = ast.unparse(target)
     if ast.unparse(binop.left) == target_src:
         return binop.right
@@ -119,17 +231,20 @@ def _other_add_operand(target: ast.expr, binop: ast.BinOp) -> ast.expr | None:
     return None
 
 
-def _string_typed_locals(func: ast.AST) -> frozenset[str]:
-    """Names assigned a string-literal-ish value in this function's own body.
+def _string_typed_locals(func: ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda) -> frozenset[str]:
+    """Collect names assigned a string-literal-ish value in this function's own body.
 
     Used as the string-typed signal for bare-`Name` accumulation (`buf += line`):
     a numeric accumulator (`total = 0`) is absent, so `total += x` stays clean.
+
+    Returns:
+        The frozenset of locally string-typed names.
+
     """
-    body = getattr(func, "body", None)
-    if not isinstance(body, list):
+    if isinstance(func, ast.Lambda):
         return frozenset()
     names: set[str] = set()
-    for stmt in body:
+    for stmt in func.body:
         _collect_string_targets(stmt, names)
     return frozenset(names)
 
@@ -153,11 +268,15 @@ def _collect_string_targets(node: ast.AST, names: set[str]) -> None:
 
 
 def _looks_like_string(node: ast.AST) -> bool:
-    """Heuristic for 'this expression is obviously a string at runtime'.
+    """Report whether this expression is obviously a string at runtime.
 
     Deliberately conservative: a bare call (`str(x)`, `",".join(...)`,
     `os.path.join(...)`) is NOT treated as a string — those shapes also appear in
     benign one-shot reassignment and are not the accumulation defect.
+
+    Returns:
+        True when the expression is heuristically string-typed.
+
     """
     if isinstance(node, ast.Constant) and isinstance(node.value, str):
         return True

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rules/no_comment_cruft.py

@@ -150,12 +150,16 @@ def _looks_like_code(body: str) -> bool:
 
 
 def _is_prose_line(body: str) -> bool:
-    """Return True if `body` reads as a natural-language sentence, not code.
+    """Report whether `body` reads as a natural-language sentence, not code.
 
     Used to spot a doc/prose comment that immediately precedes a code-shaped
     line: `# For example:` above `# result = {**a, **b}`, or a wrapped sentence
     whose second line happens to parse as an expression. Such a line is an
     illustration / prose continuation, not commented-out code.
+
+    Returns:
+        True when `body` reads as prose.
+
     """
     c = body.strip()
     if not c or _is_banner(c) or _is_directive(c) or _looks_like_code(c):
@@ -272,6 +276,10 @@ def _standalone_comments(source: str) -> tuple[list[tuple[int, int, str]], int]:
 
     A comment is standalone when it is the only content on its line. `first code
     line` is the row of the first real code token (a large sentinel if none).
+
+    Returns:
+        The standalone comments and the first code line's row.
+
     """
     out: list[tuple[int, int, str]] = []
     first_code_line = 1 << 30

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rules/no_cors_wildcard_with_credentials.py

@@ -15,6 +15,7 @@ would be a valid further tightening).
 
 References:
 - https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#credentialed_requests_and_wildcards
+
 """
 
 from __future__ import annotations
@@ -75,15 +76,24 @@ class NoCorsWildcardWithCredentials(Rule):
 
 
 def _is_true_literal(node: ast.expr) -> bool:
-    """True only for the literal `True` (not `1`, not a truthy expression)."""
+    """Report whether `node` is the literal `True` (not `1`, not a truthy expression).
+
+    Returns:
+        True only when `node` is the `True` constant.
+
+    """
     return isinstance(node, ast.Constant) and node.value is True
 
 
 def _contains_star_literal(node: ast.expr) -> bool:
-    """True if a `"*"` string `Constant` appears anywhere in `node`'s subtree.
+    """Report whether a `"*"` string `Constant` appears anywhere in `node`'s subtree.
 
     Walking the whole subtree catches both `["*"]` and the `allowed if flag else
     ["*"]` conditional branch. A dynamic `allow_origins=some_var` has no `"*"`
     literal, so it does not fire.
+
+    Returns:
+        True when a `"*"` literal appears in the subtree.
+
     """
     return any(isinstance(child, ast.Constant) and child.value == "*" for child in ast.walk(node))

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rules/no_fat_try_blocks.py

@@ -48,6 +48,7 @@ Prefer:
 References:
 - https://docs.python.org/3/tutorial/errors.html#handling-exceptions
 - https://docs.python.org/3/library/ast.html#ast.Try
+
 """
 
 from __future__ import annotations
@@ -66,31 +67,45 @@ if TYPE_CHECKING:
 
 _MAX_TRY_BODY_STATEMENTS = 3
 
-_NESTED_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
-
 
 def _walk_same_scope(node: ast.AST) -> Iterator[ast.AST]:
-    """Like `ast.walk`, but does not descend into the *bodies* of nested
-    `def` / `async def` / `lambda`. Those bodies do not run when the enclosing
-    `try` executes, so calls inside them must not count as throwing. Decorators
-    and default-argument expressions still run at definition time, so their
-    fields are walked normally."""
+    """Walk `node` without descending into nested `def` / `async def` / `lambda` bodies.
+
+    Those bodies do not run when the enclosing `try` executes, so calls inside
+    them must not count as throwing. Decorators and default-argument expressions
+    still run at definition time, so their fields are walked normally.
+
+    Yields:
+        Each AST node in the same execution scope as `node`.
+
+    """
     stack: list[ast.AST] = [node]
     while stack:
         current = stack.pop()
         yield current
-        for field, value in ast.iter_fields(current):
-            if isinstance(current, _NESTED_SCOPES) and field == "body":
-                continue
-            items = value if isinstance(value, list) else [value]
-            stack.extend(item for item in items if isinstance(item, ast.AST))
+        skipped_body = _nested_scope_body_ids(current)
+        stack.extend(child for child in ast.iter_child_nodes(current) if id(child) not in skipped_body)
+
+
+def _nested_scope_body_ids(node: ast.AST) -> frozenset[int]:
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return frozenset(id(stmt) for stmt in node.body)
+    if isinstance(node, ast.Lambda):
+        return frozenset({id(node.body)})
+    return frozenset()
 
 
 def _can_raise(stmt: ast.stmt) -> bool:
-    """True if the statement can plausibly raise when the `try` runs — i.e. its
-    same-scope subtree contains a call or `await`. Pure assignments / rebinds and
-    inert `def` / `lambda` definitions (whose bodies never execute here) are
-    free."""
+    """Report whether the statement can plausibly raise when the `try` runs.
+
+    A statement can raise when its same-scope subtree contains a call or `await`.
+    Pure assignments / rebinds and inert `def` / `lambda` definitions (whose
+    bodies never execute here) are free.
+
+    Returns:
+        True when the statement may throw.
+
+    """
     return any(isinstance(n, (ast.Call, ast.Await)) for n in _walk_same_scope(stmt))
 
 
@@ -101,9 +116,16 @@ class _Exit(enum.Enum):
 
 
 def _stmt_exits(stmt: ast.stmt) -> set[_Exit]:
-    """The set of ways control can leave `stmt`: propagate an exception
-    (`RAISE`), diverge without raising via return/break/continue (`SWALLOW`), or
-    complete normally and fall through to the next statement (`FALL`)."""
+    """Compute the set of ways control can leave `stmt`.
+
+    Control can propagate an exception (`RAISE`), diverge without raising via
+    return/break/continue (`SWALLOW`), or complete normally and fall through to
+    the next statement (`FALL`).
+
+    Returns:
+        The set of exit modes for `stmt`.
+
+    """
     match stmt:
         case ast.Raise():
             return {_Exit.RAISE}
@@ -130,11 +152,18 @@ def _body_exits(stmts: list[ast.stmt]) -> set[_Exit]:
 
 
 def _all_handlers_reraise(handlers: list[ast.ExceptHandler]) -> bool:
-    """True if every `except` handler is guaranteed to re-raise on all paths —
-    the block is uniform error-context/metric wrapping, not swallowing, so its
-    width is intentional. A handler with any path that returns / continues /
-    passes / falls through (including a conditional early return before a tail
-    `raise`) is swallowing and makes this False, so the block still fires."""
+    """Report whether every `except` handler is guaranteed to re-raise on all paths.
+
+    When it does, the block is uniform error-context/metric wrapping, not
+    swallowing, so its width is intentional. A handler with any path that returns
+    / continues / passes / falls through (including a conditional early return
+    before a tail `raise`) is swallowing and makes this False, so the block still
+    fires.
+
+    Returns:
+        True when all handlers unconditionally re-raise.
+
+    """
     return bool(handlers) and all(_body_exits(h.body) == {_Exit.RAISE} for h in handlers)