sarj-python-lint 0.15.1__tar.gz → 0.16.0__tar.gz

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/PKG-INFO

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

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

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/src/sarj_python_lint/rules/kwonly_same_type_params.py

@@ -82,9 +82,7 @@ _PRIMITIVES = frozenset({"str", "int", "float", "bool"})
 
 _EXEMPT_DECORATORS = frozenset({"override", "overload", "abstractmethod"})
 
-_HTTP_ROUTE_METHODS = frozenset(
-    {"get", "post", "put", "patch", "delete", "head", "options", "websocket"}
-)
+_HTTP_ROUTE_METHODS = frozenset({"get", "post", "put", "patch", "delete", "head", "options", "websocket"})
 
 _EXEMPT_NAME_PREFIXES = ("visit_", "test_")
 
@@ -229,9 +227,7 @@ def _value_referenced_names(tree: ast.AST) -> frozenset[str]:
         The set of names loaded outside call position.
 
     """
-    call_funcs = {
-        id(node.func) for node in ast.walk(tree) if isinstance(node, ast.Call)
-    }
+    call_funcs = {id(node.func) for node in ast.walk(tree) if isinstance(node, ast.Call)}
     return frozenset(
         node.id
         for node in ast.walk(tree)

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/src/sarj_python_lint/rules/no_comment_cruft.py

@@ -53,6 +53,7 @@ from sarj_python_lint.rules._paths import is_generated_source
 
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
     from pathlib import Path
 
 
@@ -144,6 +145,55 @@ def _is_word_char(ch: str) -> bool:
     return ch.isalnum() or ch == "_"
 
 
+_CODING_COOKIE_RE = re.compile(r"coding[:=]\s*[-_.a-zA-Z0-9]+")
+
+# Only `>>>` arms a doctest block. A bare `...` cannot: an ASCII banner of
+# dots starts with it, and exempting on that alone silently disabled the
+# banner check.
+_DOCTEST_PROMPT = ">>>"
+
+
+def _is_coding_cookie(body: str) -> bool:
+    """Report whether the comment is a PEP 263 source-encoding declaration.
+
+    `# encoding=utf-8` / `# -*- coding: utf-8 -*-` are read by the interpreter,
+    not commentary, and `rich` carries them at the top of test modules.
+
+    Returns:
+        True when the body declares a source encoding.
+
+    """
+    return bool(_CODING_COOKIE_RE.search(body))
+
+
+def _doctest_block_lines(standalone: Sequence[tuple[int, int, str]]) -> set[int]:
+    """Collect every line of a contiguous comment run that contains a doctest prompt.
+
+    A commented doctest is documentation, not dead code, but its *expected
+    output* lines look exactly like commented-out code — `# URL('https://...')`
+    in httpx's `_client.py` is the canonical shape. Exempting only the `>>>`
+    lines would still flag the output beneath them, so the whole run goes.
+
+    Returns:
+        The line numbers belonging to a doctest comment block.
+
+    """
+    exempt: set[int] = set()
+    block: list[tuple[int, str]] = []
+
+    def flush() -> None:
+        if any(body.startswith(_DOCTEST_PROMPT) for _, body in block):
+            exempt.update(line for line, _ in block)
+        block.clear()
+
+    for line, _, body in sorted(standalone):
+        if block and line != block[-1][0] + 1:
+            flush()
+        block.append((line, body))
+    flush()
+    return exempt
+
+
 def _is_directive(body: str) -> bool:
     low = body.lower()
     for prefix in _DIRECTIVE_PREFIXES:
@@ -186,11 +236,7 @@ def _is_heading_underline(body: str, prev_body: str | None) -> bool:
         return False
     if prev_body is None:
         return False
-    return (
-        any(_is_word_char(ch) for ch in prev_body)
-        and not _is_banner(prev_body)
-        and not _looks_like_code(prev_body)
-    )
+    return any(_is_word_char(ch) for ch in prev_body) and not _is_banner(prev_body) and not _looks_like_code(prev_body)
 
 
 def _is_banner(body: str) -> bool:
@@ -288,8 +334,9 @@ class NoCommentCruft(Rule):
             return []
         diags: dict[int, Diagnostic] = {}
         by_line = {line: body for line, _, body in standalone}
+        doctest_lines = _doctest_block_lines(standalone)
         for line, col, body in standalone:
-            if _is_directive(body):
+            if _is_directive(body) or _is_coding_cookie(body) or line in doctest_lines:
                 continue
             prev_body = by_line.get(line - 1)
             msg = self._classify(body, prev_body)

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/src/sarj_python_lint/rules/no_cors_wildcard_with_credentials.py

@@ -36,8 +36,7 @@ class NoCorsWildcardWithCredentials(Rule):
     id: str = "no-cors-wildcard-with-credentials"
     code: str = "SARJ028"
     description: str = (
-        'CORS `allow_credentials=True` with `"*"` in `allow_origins` lets any '
-        "site read authenticated responses."
+        'CORS `allow_credentials=True` with `"*"` in `allow_origins` lets any site read authenticated responses.'
     )
 
     @override

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/src/sarj_python_lint/rules/no_isinstance_union_chain.py

@@ -126,9 +126,7 @@ class NoIsinstanceUnionChain(Rule):
         tree = parse_or_none(path, source)
         if tree is None:
             return []
-        local_classes = frozenset(
-            node.name for node in ast.walk(tree) if isinstance(node, ast.ClassDef)
-        )
+        local_classes = frozenset(node.name for node in ast.walk(tree) if isinstance(node, ast.ClassDef))
         elif_nodes: set[int] = set()
         diags: list[Diagnostic] = []
         for node in ast.walk(tree):

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/src/sarj_python_lint/rules/no_offset_pagination.py

@@ -44,9 +44,7 @@ if TYPE_CHECKING:
 # `OFFSET` followed by a value/param token — the real pagination construct. This
 # excludes the English word ("no base offset"), `'offset'` dict keys, and BigQuery
 # `UNNEST(...) WITH OFFSET AS col` (array indexing, no value token after OFFSET).
-_OFFSET_PAGINATION = re.compile(
-    r"\bOFFSET\s+(?:%s|%\(\w+\)s|:\w+|@\w+|\$\d+|\d+)", re.IGNORECASE
-)
+_OFFSET_PAGINATION = re.compile(r"\bOFFSET\s+(?:%s|%\(\w+\)s|:\w+|@\w+|\$\d+|\d+)", re.IGNORECASE)
 
 
 class NoOffsetPagination(Rule):

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/src/sarj_python_lint/rules/no_sentinel_return_on_except.py

@@ -123,8 +123,7 @@ class NoSentinelReturnOnExcept(Rule):
                 col=handler.col_offset + 1,
                 code=self.code,
                 message=(
-                    "Bare `except: pass` silently swallows the exception — "
-                    "re-raise, log it, or handle it explicitly."
+                    "Bare `except: pass` silently swallows the exception — re-raise, log it, or handle it explicitly."
                 ),
             )
         return None

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/src/sarj_python_lint/rules/parametrize_case_needs_id.py

@@ -15,10 +15,18 @@ Fires when ALL of these hold:
   bare `parametrize` imported from pytest),
 * the decorator does **not** pass `ids=` — one `ids=` covers the whole table, so
   its presence exempts every case,
-* and a case value is opaque to pytest's id generation: a `dict`, `set`,
-  comprehension, or a constructor/factory `Call`. For a multi-argument case the
-  check descends into the tuple, since one opaque column is enough to poison the
-  generated id,
+* and **every** column of the case is opaque to pytest's id generation: a
+  `dict`, `set`, comprehension, or a constructor/factory `Call`.
+
+  Requiring *every* column, not any, is the difference between a useful rule and
+  a noisy one. pytest builds an id by joining the per-argument ids with `-`, so a
+  single nameable column still distinguishes the case: `("0.0", Decimal("0.0"))`
+  reports as `0.0-value1`, which a reader can find. A third-party sweep over
+  pydantic, flask, httpx, requests and rich flagged 372 tables under the
+  any-column reading; the overwhelming majority paired an opaque value with a
+  perfectly nameable string or number — `Decimal('0.0')`, `datetime(2012, 4, 9)`,
+  `UUID(...)`, `timedelta(hours=10)`, `Err('...')` — and were false positives.
+  Only a case whose columns are *all* opaque degenerates to `case0`, `case1`,
 * and that specific case is not individually named by `pytest.param(..., id=...)`.
 
 The `pytest.param` unwrap is the load-bearing false-positive guard. A first pass
@@ -142,12 +150,14 @@ def _is_unnameable(case: ast.expr) -> bool:
         # An explicitly named case is fine however opaque its payload is.
         if _has_keyword(case, "id"):
             return False
-        return any(_is_opaque_value(arg) for arg in case.args)
+        return bool(case.args) and all(_is_opaque_value(arg) for arg in case.args)
     return _is_opaque_value(case)
 
 
 def _is_opaque_value(value: ast.expr) -> bool:
-    # A multi-column case is a tuple; one opaque column poisons the whole id.
+    # A multi-column case is a tuple. pytest joins the per-column ids with `-`,
+    # so one nameable column is enough to tell the case apart — only an
+    # all-opaque case degenerates to `case0`.
     if isinstance(value, ast.Tuple):
-        return any(_is_opaque_value(elt) for elt in value.elts)
+        return bool(value.elts) and all(_is_opaque_value(elt) for elt in value.elts)
     return isinstance(value, _OPAQUE_NODES)

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/src/sarj_python_lint/rules/prefer_match_assert_never.py

@@ -244,9 +244,7 @@ def _module_scope_classdefs(tree: ast.Module) -> list[ast.ClassDef]:
     return found
 
 
-def _enum_member_names(
-    classdefs: list[ast.ClassDef], local_enums: frozenset[str]
-) -> dict[str, frozenset[str]]:
+def _enum_member_names(classdefs: list[ast.ClassDef], local_enums: frozenset[str]) -> dict[str, frozenset[str]]:
     """Map each module-scope enum's name to the member names it declares.
 
     A member is a plain `NAME = <value>` assignment in the class body. Methods,
@@ -296,16 +294,13 @@ def _grown_dict_names(tree: ast.Module) -> frozenset[str]:
     grown: set[str] = set()
     for node in ast.walk(tree):
         match node:
-            case ast.Call(
-                func=ast.Attribute(value=ast.Name(id=name), attr=attr)
-            ) if attr in _DICT_GROWING_METHODS:
+            case ast.Call(func=ast.Attribute(value=ast.Name(id=name), attr=attr)) if attr in _DICT_GROWING_METHODS:
                 grown.add(name)
             case ast.Assign(targets=targets):
                 grown.update(
                     subscript.value.id
                     for subscript in targets
-                    if isinstance(subscript, ast.Subscript)
-                    and isinstance(subscript.value, ast.Name)
+                    if isinstance(subscript, ast.Subscript) and isinstance(subscript.value, ast.Name)
                 )
             case _:
                 pass
@@ -347,9 +342,7 @@ def _incomplete_dispatch_map(
     if owner is None or owner not in enum_members:
         return None
     declared = enum_members[owner]
-    covered = {
-        key.attr for key in mapping.keys if isinstance(key, ast.Attribute) and key.attr in declared
-    }
+    covered = {key.attr for key in mapping.keys if isinstance(key, ast.Attribute) and key.attr in declared}
     if len(covered) != len(mapping.keys) or not covered < declared:
         return None
     missing = ", ".join(f"{owner}.{name}" for name in sorted(declared - covered))
@@ -483,9 +476,7 @@ def _is_silent_body(body: list[ast.stmt]) -> bool:
             return False
 
 
-def _all_one_owner_member_arms(
-    cases: list[ast.match_case], member_owners: frozenset[str]
-) -> bool:
+def _all_one_owner_member_arms(cases: list[ast.match_case], member_owners: frozenset[str]) -> bool:
     """Report whether every arm matches enum-member values of one owner class.
 
     The owner must be a name that can actually bind a class here: defined by a
@@ -535,9 +526,7 @@ def _is_local_class_pattern(pattern: ast.pattern, local_classes: frozenset[str])
             return False
 
 
-def _silent_enum_chain(
-    head: ast.If, local_enums: frozenset[str], consumed_elifs: set[int]
-) -> str | None:
+def _silent_enum_chain(head: ast.If, local_enums: frozenset[str], consumed_elifs: set[int]) -> str | None:
     """Parse `head` as an ==/in chain over one local enum with a silent `else`.
 
     Each nested `elif` that genuinely continues the chain (same target, same

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/src/sarj_python_lint/rules/xfail_requires_strict.py

@@ -32,6 +32,14 @@ reason mentioning intermittence.
 
 Deliberately NOT flagged:
 
+* **property-based and fuzz tests.** A `@given(...)` (hypothesis) or
+  `<schema>.parametrize()` (schemathesis) decorator means one test function
+  expands into many generated cases, and a documented bug is typically tripped
+  by only a subset of them — the rest legitimately XPASS. `strict=True` there
+  turns every passing generated input into a failure, which is why these suites
+  set `strict=False` deliberately. Found against bulbul's
+  `test_calls_fuzz_known_bugs`, where the unroutable-id shapes trip the bug and
+  the other generated ids do not,
 * `xfail` with no `reason=`, or a reason describing an environment gate rather
   than a defect ("no GPU on CI") — those are not bug pins,
 * `pytest.xfail(...)` called imperatively inside a body — that aborts the test
@@ -65,6 +73,14 @@ _NONDETERMINISM_RE = re.compile(r"intermittent|flak|sometimes|non-?deterministic
 # Sibling markers that declare a nondeterministic dependency.
 _NONDETERMINISTIC_MARKERS = frozenset({"real_llm", "flaky", "network", "integration"})
 
+# Hypothesis' entry point. One `@given` expands into many generated inputs.
+_PROPERTY_DECORATORS = frozenset({"given"})
+
+# schemathesis binds `.parametrize()` on a schema object. `pytest.mark.parametrize`
+# is a fixed table and is NOT this — it is excluded by checking the receiver.
+_PARAMETRIZE_ATTR = "parametrize"
+_PYTEST_MARK = "mark"
+
 _FUNC_NODES = (ast.FunctionDef, ast.AsyncFunctionDef)
 
 
@@ -119,7 +135,26 @@ def _rotting_bug_pins(tree: ast.Module) -> list[ast.Call]:
 
 
 def _has_nondeterministic_marker(decorators: list[ast.expr]) -> bool:
-    return any(_marker_name(dec) in _NONDETERMINISTIC_MARKERS for dec in decorators)
+    return any(_marker_name(dec) in _NONDETERMINISTIC_MARKERS or _is_property_based(dec) for dec in decorators)
+
+
+def _is_property_based(dec: ast.expr) -> bool:
+    """Report whether `dec` expands the test into many generated inputs.
+
+    Returns:
+        True for a hypothesis `@given(...)` or a schemathesis
+        `<schema>.parametrize()`, both of which make a partial XPASS normal.
+
+    """
+    target = dec.func if isinstance(dec, ast.Call) else dec
+    if isinstance(target, ast.Name):
+        return target.id in _PROPERTY_DECORATORS
+    if not isinstance(target, ast.Attribute) or target.attr != _PARAMETRIZE_ATTR:
+        return False
+    # `pytest.mark.parametrize` is a fixed table, not a generator — the receiver
+    # is `mark`. A schemathesis schema object is anything else.
+    receiver = target.value
+    return not (isinstance(receiver, ast.Attribute) and receiver.attr == _PYTEST_MARK)
 
 
 def _marker_name(dec: ast.expr) -> str | None:

{sarj_python_lint-0.15.1 → sarj_python_lint-0.16.0}/src/sarj_python_lint/rules/zero_assertion_test.py

@@ -39,7 +39,17 @@ Deliberately NOT flagged:
 
 * a test marked `@pytest.mark.skip`/`skipif`/`xfail` — it is not expected to
   verify anything right now,
-* a fixture, helper, or any function not named `test_*`,
+* **a `test_*` function nested inside another function.** pytest only collects
+  module-level functions and methods of `Test*` classes, so a nested one is not
+  a test at all — it is a callback that happens to be named for what it does.
+  Flask route handlers are the canonical case: `def test_index()` registered
+  with `@app.route("/", subdomain="test")` inside a test that asserts on the
+  response afterwards. A third-party sweep found 36 such hits, every one a false
+  positive. Only functions whose parent is the module or a class are considered.
+* **a `@pytest.fixture`**, whatever it is named. `flask/tests/conftest.py`
+  defines `def test_apps(monkeypatch)` as a fixture; it sets up `sys.path` and
+  yields, and asserting nothing is exactly right for it,
+* a helper, or any function not named `test_*`,
 * an abstract or stub body (`...`, `pass`, docstring only) — an intentionally
   empty placeholder is a different problem from a half-written test,
 * anything under a `scripts/` directory. `digital-bank/banking-ai/chat/scripts/`
@@ -75,6 +85,8 @@ _FLUENT_ATTRS = frozenset({"expect"})
 
 _SKIP_MARKERS = frozenset({"skip", "skipif", "xfail"})
 
+_FIXTURE = "fixture"
+
 _FUNC_NODES = (ast.FunctionDef, ast.AsyncFunctionDef)
 
 # Manual CLI probes live here under test_*.py names but are never collected.
@@ -126,15 +138,40 @@ def _is_uncollected(path: Path) -> bool:
 
 def _unverifying_tests(tree: ast.Module) -> list[ast.FunctionDef | ast.AsyncFunctionDef]:
     hits: list[ast.FunctionDef | ast.AsyncFunctionDef] = []
-    for node in ast.walk(tree):
-        if not isinstance(node, _FUNC_NODES) or not node.name.startswith("test_"):
-            continue
-        if _is_skipped(node) or _is_placeholder(node) or _verifies_something(node):
+    for node in _collectible_tests(tree):
+        if _is_skipped(node) or _is_fixture(node) or _is_placeholder(node) or _verifies_something(node):
             continue
         hits.append(node)
     return hits
 
 
+def _collectible_tests(tree: ast.Module) -> list[ast.FunctionDef | ast.AsyncFunctionDef]:
+    """Collect the `test_*` functions pytest would actually run.
+
+    Only module-level functions and methods of a class qualify. A `test_*`
+    nested inside another function is a callback, not a test — pytest never
+    collects it — so descending into function bodies would invent findings.
+
+    Returns:
+        The test functions in the order they appear.
+
+    """
+    found: list[ast.FunctionDef | ast.AsyncFunctionDef] = []
+    containers: list[ast.Module | ast.ClassDef] = [tree]
+    while containers:
+        for stmt in containers.pop().body:
+            if isinstance(stmt, ast.ClassDef):
+                containers.append(stmt)
+            elif isinstance(stmt, _FUNC_NODES) and stmt.name.startswith("test_"):
+                found.append(stmt)
+    found.sort(key=lambda n: (n.lineno, n.col_offset))
+    return found
+
+
+def _is_fixture(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    return any(_marker_name(dec) == _FIXTURE for dec in node.decorator_list)
+
+
 def _is_skipped(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
     return any(_marker_name(dec) in _SKIP_MARKERS for dec in node.decorator_list)