sarj-python-lint 0.28.0__tar.gz → 0.30.0__tar.gz

{sarj_python_lint-0.28.0 → sarj_python_lint-0.30.0}/PKG-INFO

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

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

{sarj_python_lint-0.28.0 → sarj_python_lint-0.30.0}/src/sarj_python_lint/rules/_logging.py

@@ -12,7 +12,10 @@ import ast
 
 _LOGGER_NAMES = frozenset({"logger", "log", "logging", "loguru", "_logger", "_log"})
 
-_LOGGER_FACTORIES = frozenset({"getlogger", "get_logger"})
+# Public: `no_fstring_in_log._chain_has_getlogger` must test the SAME set with
+# the SAME casing, or a factory can be a logger to one and not the other.
+LOGGER_FACTORIES = frozenset({"getlogger", "get_logger"})
+_LOGGER_FACTORIES = LOGGER_FACTORIES
 
 
 def is_logger_expr(expr: ast.expr) -> bool:

{sarj_python_lint-0.28.0 → sarj_python_lint-0.30.0}/src/sarj_python_lint/rules/_suppression_comments.py

@@ -57,13 +57,3 @@ def scan_comments(source: str) -> list[Comment]:
         )
         for line, col, body, standalone in ordered
     ]
-
-
-def comment_body(raw: str) -> str:
-    """Strip a comment token down to its directive text.
-
-    Returns:
-        The comment text without its leading `#` markers or surrounding space.
-
-    """
-    return raw.lstrip("#").strip()

{sarj_python_lint-0.28.0 → sarj_python_lint-0.30.0}/src/sarj_python_lint/rules/no_fstring_in_log.py

@@ -76,7 +76,7 @@ from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
 from sarj_python_lint.rules._ast_index import nodes
-from sarj_python_lint.rules._logging import is_logger_expr
+from sarj_python_lint.rules._logging import LOGGER_FACTORIES, is_logger_expr
 
 
 if TYPE_CHECKING:
@@ -102,6 +102,11 @@ _LOG_METHODS = frozenset(
 # Keyword arguments defined by stdlib `logging` (and never structured fields).
 # Their presence marks the call as a stdlib logger, for which the loguru-style
 # structured-keyword rewrite is wrong.
+# The stdlib factory spelling. `logging.getLogger` is camelCase; structlog uses
+# snake_case `get_logger`, and that difference is the only static signal telling
+# a dotted stdlib factory from a dotted structlog one.
+_STDLIB_FACTORY = "getLogger"
+
 _STDLIB_ONLY_KWARGS = frozenset({"exc_info", "stack_info", "extra"})
 
 
@@ -272,13 +277,45 @@ def _is_stdlib_logging_call(node: ast.Call, stdlib: _StdlibLoggers) -> bool:
 
 
 def _chain_has_getlogger(expr: ast.expr) -> bool:
+    """Report whether a stdlib `logging` factory appears anywhere in the receiver chain.
+
+    Matched against the SAME set and casing as `_logging.is_logger_expr`, and that
+    parity is load-bearing. When `is_logger_expr` learned to recognise a bare
+    `get_logger()` callee, this guard still tested the exact string `"getLogger"`,
+    so a snake_case factory returning a *stdlib* logger became a logger to the
+    rule but not a stdlib logger to the guard — and the rule then advised
+    `logger.info("msg", key=value)` on an API that rejects it.
+
+    That advice fails in the worst possible way: stdlib `Logger._log` raises
+    `TypeError: got an unexpected keyword argument`, but only when the call is
+    actually emitted, so the code is green at the default WARNING level and
+    breaks the moment log level is raised to INFO. The shim that triggers it —
+    `def get_logger(name): return logging.getLogger(name)` — ships in
+    huggingface_hub, transformers, fastmcp, mcp and speechmatics, all present in
+    consumer virtualenvs.
+
+    Returns:
+        True when the chain names a stdlib logging factory.
+
+    """
     node = expr
     while True:
         if isinstance(node, ast.Call):
             called = node.func
-            if isinstance(called, ast.Attribute) and called.attr == "getLogger":
+            # DOTTED callee: only the stdlib spelling counts. `structlog.get_logger()`
+            # must NOT be suppressed — structlog's keyword API is exactly what this
+            # rule's advice targets, and it is the rule's main true positive.
+            if isinstance(called, ast.Attribute) and called.attr == _STDLIB_FACTORY:
                 return True
-            if isinstance(called, ast.Name) and called.id == "getLogger":
+            # BARE callee: `get_logger()` and `getLogger()` are both ambiguous — the
+            # name alone cannot tell `from structlog import get_logger` from a shim
+            # `def get_logger(n): return logging.getLogger(n)`, and such shims ship in
+            # huggingface_hub, transformers, fastmcp, mcp and speechmatics. Suppress
+            # both, because the failure is asymmetric: a false NEGATIVE costs one
+            # style nit, while a false POSITIVE advises `logger.info("m", k=v)` on a
+            # stdlib logger, which raises `TypeError` — and only once log level is
+            # raised to INFO, so it is green in tests and breaks in production.
+            if isinstance(called, ast.Name) and called.id.lower() in LOGGER_FACTORIES:
                 return True
             node = called
         elif isinstance(node, ast.Attribute):

{sarj_python_lint-0.28.0 → sarj_python_lint-0.30.0}/src/sarj_python_lint/rules/no_gen_random_uuid_in_sql.py

@@ -66,11 +66,6 @@ if TYPE_CHECKING:
 
 _GEN_RANDOM_UUID_RE = re.compile(r"\bgen_random_uuid\s*\(", re.IGNORECASE)
 
-# The whole-source gate in `check`. Deliberately weaker than the pattern above —
-# the identifier alone, no paren — so it cannot exclude a file whose masked SQL
-# would have matched. See the comment at its use site.
-_NAMES_GEN_RANDOM_UUID_RE = re.compile(r"gen_random_uuid", re.IGNORECASE)
-
 # A string only counts as SQL when it carries a structural keyword. Without this
 # the rule fires on prose that names the function — including this module's own
 # docstring.
@@ -116,30 +111,6 @@ class NoGenRandomUuidInSql(Rule):
             The diagnostics, sorted by (line, col).
 
         """
-        # Naming the function is a NECESSARY condition for any finding: the
-        # match runs against `strip_sql_noise(literal)`, and that only ever
-        # removes characters, so text absent from the file cannot appear in the
-        # masked literal. Checking the raw source first skips the parse and the
-        # per-literal SQL masking for the ~100% of files that never mention it.
-        #
-        # This rule is not store-gated and so masked every string literal in
-        # every file, which made it the worst cost-per-finding in the registry
-        # (2 findings across 21 corpora, at ~125 ms each). The gate removes that
-        # for no loss of coverage — verified by measuring the corpus before and
-        # after, not by inspection.
-        #
-        # The gate deliberately tests only the identifier, NOT the full
-        # `_GEN_RANDOM_UUID_RE`, which also requires the open paren. Masking can
-        # delete characters *between* the name and its paren — `gen_random_uuid
-        # /* c */ ()` masks to `gen_random_uuid ()` and matches — so gating on
-        # the stricter pattern would drop a finding the rule would otherwise
-        # report. A gate must be strictly weaker than the predicate it guards.
-        #
-        # It is case-insensitive for the same reason `_GEN_RANDOM_UUID_RE` is: a
-        # `DEFAULT GEN_RANDOM_UUID()` in upper-case SQL is a real finding, and a
-        # plain `"gen_random_uuid" in source` test would silently drop it.
-        if not _NAMES_GEN_RANDOM_UUID_RE.search(source):
-            return []
         if is_generated_source(source):
             return []
         tree = parse_or_none(path, source)

{sarj_python_lint-0.28.0 → sarj_python_lint-0.30.0}/src/sarj_python_lint/rules/no_implicit_attribute_access.py

@@ -44,6 +44,34 @@ _EXCLUDED_BASES = {
 }
 
 
+# Typing constructs subscripted with string literals. `Literal["x"]` is a type,
+# not a lookup, so the rule's advice ("parse declaratively with Pydantic") is
+# nonsensical there -- the annotation already IS the declarative schema.
+_TYPE_SUBSCRIPTS = frozenset(
+    {
+        "Literal",
+        "Annotated",
+        "TypedDict",
+        "NamedTuple",
+        "Field",
+        "Doc",
+        "Required",
+        "NotRequired",
+        "ReadOnly",
+    }
+)
+
+
+def _looks_like_route_or_url(value: str) -> bool:
+    """Report whether a `.get()` argument is a route path or URL rather than a key.
+
+    Returns:
+        True for `"/users/{id}"`-shaped paths and anything carrying a scheme.
+
+    """
+    return value.startswith("/") or "://" in value
+
+
 def _get_base_name(node: ast.expr) -> str | None:
     if isinstance(node, ast.Name):
         return node.id
@@ -100,6 +128,14 @@ def _get_key(node: ast.Call) -> str | None:
     first = node.args[0]
     if not isinstance(first, ast.Constant) or not isinstance(first.value, str):
         return None
+    # `.get()` is also the HTTP verb and the route-registration decorator, and
+    # both take a string first argument, so the method name alone cannot tell
+    # them from a mapping lookup. The ARGUMENT can: a URL or a route path is not
+    # a dictionary key. Measured on bulbul + noura-be, this shape was 168 of the
+    # rule's 1,756 findings (9.6%) -- `@router.get("/available-events")` and
+    # `await self.http_client.get(url)` were reported as implicit schema access.
+    if _looks_like_route_or_url(first.value):
+        return None
     return None if _get_base_name(func.value) in _EXCLUDED_BASES else first.value
 
 
@@ -111,10 +147,25 @@ def _subscript_key(node: ast.Subscript) -> str | None:
         the base is one of the excluded receivers.
 
     """
+    # Writing to a mapping is the opposite of the defect. This rule is about
+    # PLUCKING fields out of a payload whose schema is already known -- building
+    # a dict up key by key (`field_dict["x"] = x`, `params["status"] = ...`) is
+    # ordinary construction, and a Pydantic model does not replace it. Measured
+    # on bulbul + noura-be this was 503 of 1,756 findings (28.6%), the single
+    # largest source, and every sampled instance was an assignment target.
+    if isinstance(node.ctx, (ast.Store, ast.Del)):
+        return None
+    # `Literal["a"]`, `Annotated[T, "..."]` and friends are type expressions that
+    # merely LOOK like subscripts. They are not dictionary access at all, and no
+    # Pydantic model can replace them -- `Literal["user"]` IS the schema. 470 of
+    # 1,756 findings (26.8%) were this, second only to assignment targets.
+    base_name = _get_base_name(node.value)
+    if base_name in _TYPE_SUBSCRIPTS:
+        return None
     index = node.slice
     if not isinstance(index, ast.Constant) or not isinstance(index.value, str):
         return None
-    return None if _get_base_name(node.value) in _EXCLUDED_BASES else index.value
+    return None if base_name in _EXCLUDED_BASES else index.value
 
 
 def _is_test_path(path: Path) -> bool:

{sarj_python_lint-0.28.0 → sarj_python_lint-0.30.0}/src/sarj_python_lint/rules/prefer_match_type_dispatch.py

@@ -1,38 +1,12 @@
-"""SARJ080: prefer match/case over sequential sentinel/type guards.
+"""SARJ080: prefer match/case over control-flow try/raise and sequential type guards.
 
 Parsers and field deserializers often contain hideous type-dispatch idioms:
-sequential `if x is None: return x` / `if isinstance(x, Unset): return x` guards
-walking a value through one shape at a time, where a single `match` states the
-whole dispatch at once.
-
-DELIBERATELY NOT FLAGGED: `raise` inside a `try` block
-------------------------------------------------------
-
-This rule used to carry a second detector for the other half of that idiom —
-raising inside a `try` purely to jump into its own `except` handler, i.e. using
-`raise` as a goto. That detector was removed because ruff already reports it and
-our shipped config already enables it.
-
-`ruff.strict.toml` selects `ALL` and does not ignore `TRY`, so `TRY301`
-(`raise-within-try`, "Abstract `raise` to an inner function") is live in every
-consumer. Measured across 21 corpora, the removed arm produced 1,756 findings of
-which 1,649 (93.9%) sat on a line ruff already flagged, and construction
-confirms the columns match exactly, not merely the line:
-
-    try:
-        if not isinstance(x, str):
-            raise TypeError        # ruff TRY301 at 13:13, old SARJ080 at 13:13
-
-The 107 positions TRY301 structurally misses are `raise`s inside an `except`
-body caught by an *outer* `try`. That is a real gap, but not one worth 1,649
-double reports — and 5 of those positions already carry an explicit
-`# noqa: TRY301`, a decision the team made that a second code would quietly
-re-open.
-
-The surviving sequential-guard detector has NO ruff counterpart: the same sweep
-found 0 of its 476 positions shared with TRY301, and `RET505` is the closest
-thing ruff has, firing only on `elif`-after-`return` rather than on separate
-`if ...: return` statements.
+sequential `if x is None: return x` / `if isinstance(x, Unset): return x` guards,
+followed by a `try` block containing `if not isinstance(x, T): raise TypeError()`
+to artificially jump control flow into an `except (TypeError, ...): pass` block.
+
+Raising an exception inside a `try` block solely to trigger that block's `except`
+handler is using `raise` as a goto (control flow via exceptions).
 
 Preferred Python 3.10+ match/case patterns:
 - For `None`: `case None:`
@@ -68,9 +42,59 @@ if TYPE_CHECKING:
     from pathlib import Path
 
 
+_GENERIC_EXCEPTIONS = frozenset({"Exception", "BaseException"})
 _MIN_SENTINEL_COUNT = 2
 
 
+def _get_caught_exception_names(handlers: list[ast.ExceptHandler]) -> set[str] | None:
+    """Extract caught exception class names.
+
+    Returns:
+        A set of exception class names, or None if a catch-all handler (bare `except:`) is present.
+
+    """
+    caught: set[str] = set()
+    for h in handlers:
+        if h.type is None:
+            return None
+        if isinstance(h.type, ast.Name):
+            caught.add(h.type.id)
+        elif isinstance(h.type, ast.Tuple):
+            for elt in h.type.elts:
+                if isinstance(elt, ast.Name):
+                    caught.add(elt.id)
+                elif isinstance(elt, ast.Attribute):
+                    caught.add(elt.attr)
+                    caught.add(ast.unparse(elt))
+        elif isinstance(h.type, ast.Attribute):
+            caught.add(h.type.attr)
+            caught.add(ast.unparse(h.type))
+    return caught
+
+
+def _raised_exception_name(raise_node: ast.Raise) -> str | None:
+    """Extract exception class name from `raise Exc()` or `raise Exc`.
+
+    Returns:
+        The exception class name, or None if no exception is specified.
+
+    """
+    exc = raise_node.exc
+    if exc is None:
+        return None
+    if isinstance(exc, ast.Call):
+        func = exc.func
+        if isinstance(func, ast.Name):
+            return func.id
+        if isinstance(func, ast.Attribute):
+            return func.attr
+    elif isinstance(exc, ast.Name):
+        return exc.id
+    elif isinstance(exc, ast.Attribute):
+        return exc.attr
+    return None
+
+
 def _guard_target_var_name(stmt: ast.stmt) -> str | None:
     """Extract target variable name if statement is `if x is None: return ...` or `if isinstance(x, ...): return ...`.
 
@@ -167,25 +191,75 @@ class _TypeDispatchVisitor(ast.NodeVisitor):
         self.path: Path = path
         self.code: str = code
         self.diags: list[Diagnostic] = []
+        self.try_stack: list[set[str] | None] = []
+
+    def visit_Try(self, node: ast.Try | ast.TryStar) -> None:
+        caught = _get_caught_exception_names(node.handlers)
+        self.try_stack.append(caught)
+        for stmt in node.body:
+            self.visit(stmt)
+        self.try_stack.pop()
+        for handler in node.handlers:
+            self.visit(handler)
+        for stmt in node.orelse:
+            self.visit(stmt)
+        for stmt in node.finalbody:
+            self.visit(stmt)
+
+    @override
+    def visit_TryStar(self, node: ast.TryStar) -> None:
+        self.visit_Try(node)
+
+    def visit_Raise(self, node: ast.Raise) -> None:
+        if self.try_stack:
+            exc_name = _raised_exception_name(node)
+            if exc_name is not None:
+                # Search outward through active try scopes
+                for caught in reversed(self.try_stack):
+                    is_caught = caught is None or exc_name in caught or bool(caught & _GENERIC_EXCEPTIONS)
+                    if is_caught:
+                        self.diags.append(
+                            Diagnostic(
+                                path=self.path,
+                                line=node.lineno,
+                                col=node.col_offset + 1,
+                                code=self.code,
+                                message=(
+                                    f"Control-flow raise in try block — 'raise {exc_name}()' "
+                                    f"jumps directly to local except handler. Refactor to 'match/case' "
+                                    f"(e.g., 'case str():') to handle types directly."
+                                ),
+                            )
+                        )
+                        break
+        self.generic_visit(node)
 
     def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
         self.diags.extend(_check_sequential_type_guards(node, self.path, self.code))
+        saved_stack = self.try_stack
+        self.try_stack = []
         self.generic_visit(node)
+        self.try_stack = saved_stack
 
     def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
         self.diags.extend(_check_sequential_type_guards(node, self.path, self.code))
+        saved_stack = self.try_stack
+        self.try_stack = []
         self.generic_visit(node)
+        self.try_stack = saved_stack
 
     def visit_ClassDef(self, node: ast.ClassDef) -> None:
         self.generic_visit(node)
 
 
 class PreferMatchTypeDispatch(Rule):
-    """Prefer match/case over sequential sentinel/type guards."""
+    """Prefer match/case over try/raise control flow and sequential type guards."""
 
     id: str = "prefer-match-type-dispatch"
     code: str = "SARJ080"
-    description: str = "Sequential sentinel/type guards — prefer Python 3.10+ match/case pattern matching."
+    description: str = (
+        "Control-flow raise in try block or sequential type guards — prefer Python 3.10+ match/case pattern matching."
+    )
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]: