sarj-python-lint 0.17.0__tar.gz → 0.18.1__tar.gz

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/PKG-INFO

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

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

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rule_base.py

@@ -87,7 +87,7 @@ class Rule(ABC):
         raise NotImplementedError
 
 
-_last_parse: tuple[tuple[str, int, int], ast.Module | None] | None = None
+_last_parse: tuple[str, str, ast.Module | None] | None = None
 
 
 def parse_or_none(path: Path, source: str) -> ast.Module | None:
@@ -98,12 +98,12 @@ def parse_or_none(path: Path, source: str) -> ast.Module | None:
 
     """
     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:
-        return _last_parse[1]
+    path_key = str(path)
+    if _last_parse is not None and _last_parse[0] == path_key and _last_parse[1] is source:
+        return _last_parse[2]
     try:
         tree = ast.parse(source, filename=str(path))
     except SyntaxError:
         tree = None
-    _last_parse = (key, tree)
+    _last_parse = (path_key, source, tree)
     return tree

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/_paths.py

@@ -23,7 +23,12 @@ if TYPE_CHECKING:
 
 _TEST_DIR_NAMES = frozenset({"tests", "test"})
 
-_GENERATED_RE = re.compile(r"auto-?generated|generated by|do not edit", re.IGNORECASE)
+# `auto-?generated` misses "automatically generated", which is the phrase
+# @generated tooling, protoc and OpenAPI generators emit most often.
+_GENERATED_RE = re.compile(
+    r"auto(?:-|matically )?generated|generated by|do not edit|@generated",
+    re.IGNORECASE,
+)
 
 _GENERATED_HEADER_LINES = 5
 

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -34,6 +34,12 @@ References:
 - https://docs.python.org/3/library/stdtypes.html#str.join
 - https://wiki.python.org/moin/PythonSpeed/PerformanceTips
 
+* **generated files** (`_paths.is_generated_source`). Their layout is the
+  generator's, and re-running the generator discards any edit, so a finding
+  there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
+  files git-tracked across bulbul and noura-be — Speakeasy's
+  `python/sdk/src/sarj_platform_sdk/` accounts for all of them.
+
 """
 
 from __future__ import annotations
@@ -42,6 +48,7 @@ import ast
 from typing import TYPE_CHECKING, TypeGuard, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+from sarj_python_lint.rules._paths import is_generated_source
 
 
 if TYPE_CHECKING:
@@ -58,6 +65,10 @@ class InefficientStringConcatInLoop(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated_source(source):
+            return []
+        if "+" not in source or ("for " not in source and "while " not in source):
+            return []
         tree = parse_or_none(path, source)
         if tree is None:
             return []

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/kwonly_same_type_params.py

@@ -157,16 +157,30 @@ _DUCK_PROTOCOL_METHODS = frozenset(
 #: drawn entirely from one of these reads unambiguously positionally.
 _CONVENTIONAL_ORDER_GROUPS = (
     frozenset({"x", "y", "z"}),
+    frozenset({"lat", "lon", "alt"}),
+    frozenset({"latitude", "longitude", "altitude"}),
     frozenset({"width", "height", "depth"}),
     frozenset({"red", "green", "blue", "alpha"}),
     frozenset({"row", "column"}),
     frozenset({"top", "right", "bottom", "left"}),
+    frozenset({"left", "right"}),
+    frozenset({"lo", "hi"}),
+    frozenset({"low", "high"}),
+    frozenset({"minimum", "maximum"}),
+    frozenset({"min_value", "max_value"}),
+    frozenset({"begin", "end"}),
+    frozenset({"source", "sink"}),
     frozenset({"year", "month", "day"}),
     frozenset({"hour", "minute", "second", "microsecond"}),
     frozenset({"start", "stop", "step"}),
 )
 
 _EXEMPT_NAME_PREFIXES = ("visit_", "test_")
+_RISKY_NAME_PART_RE = re.compile(
+    r"(?:^|_)(?:id|key|token|secret|password|signature|hash|email|url|uri|path|file|"
+    r"source|src|target|dst|dest|destination|parent|child|from|to|old|new|"
+    r"before|after|previous|next|expected|actual|left_id|right_id)(?:_|$)"
+)
 
 
 class KwonlySameTypeParams(Rule):
@@ -350,11 +364,30 @@ def _swap_prone_annotation(args: ast.arguments) -> str | None:
     for name, arg_names in sorted(groups.items(), key=lambda kv: -len(kv[1])):
         if len(arg_names) >= _MIN_SAME_TYPE and not (
             _is_symmetric_numbering(arg_names) or _is_conventional_order(arg_names)
-        ):
+        ) and _is_high_value_group(name, arg_names):
             return name
     return None
 
 
+def _is_high_value_group(annotation: str, arg_names: list[str]) -> bool:
+    """Report whether a same-primitive group is worth enforcing globally.
+
+    Booleans are always high-risk because positional `True, False` carries no
+    call-site meaning. Other primitives fire only when the parameter names carry
+    production-domain identifiers or directed relationships (`source_id`,
+    `target_id`, `old_key`, `new_key`, `input_path`, `output_path`). This keeps
+    math / algorithm APIs such as `power(base, exponent)` and `f(a, b)` out of
+    the default rule while preserving the bug class the rule was written for.
+
+    Returns:
+        True when the group should be reported.
+
+    """
+    if annotation == "bool":
+        return True
+    return sum(1 for name in arg_names if _RISKY_NAME_PART_RE.search(name)) >= _MIN_SAME_TYPE
+
+
 def _is_dunder_prefixed(arg: str) -> bool:
     """Report whether `arg` uses the PEP 484 positional-only naming convention.
 

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/no_fat_try_blocks.py

@@ -69,6 +69,12 @@ References:
 - https://docs.python.org/3/tutorial/errors.html#handling-exceptions
 - https://docs.python.org/3/library/ast.html#ast.Try
 
+* **generated files** (`_paths.is_generated_source`). Their layout is the
+  generator's, and re-running the generator discards any edit, so a finding
+  there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
+  files git-tracked across bulbul and noura-be — Speakeasy's
+  `python/sdk/src/sarj_platform_sdk/` accounts for all of them.
+
 """
 
 from __future__ import annotations
@@ -79,6 +85,7 @@ from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
 from sarj_python_lint.rules._logging import is_logger_expr
+from sarj_python_lint.rules._paths import is_generated_source
 
 
 if TYPE_CHECKING:
@@ -124,38 +131,42 @@ def _nested_scope_body_ids(node: ast.AST) -> frozenset[int]:
 #: `set` and `record` are deliberately ABSENT — `cache.set(k, v)` /
 #: `store.record(row)` collide with them and are real work whose failure a handler
 #: is plausibly written for.
-_OBSERVABILITY_METHODS = frozenset({
-    "inc",
-    "dec",
-    "observe",
-    "set_to_current_time",
-    "labels",
-    "increment",
-    "decrement",
-    "gauge",
-    "timing",
-    "histogram",
-    "record_exception",
-    "add_event",
-    "set_attribute",
-    "set_attributes",
-    "set_status",
-})
+_OBSERVABILITY_METHODS = frozenset(
+    {
+        "inc",
+        "dec",
+        "observe",
+        "set_to_current_time",
+        "labels",
+        "increment",
+        "decrement",
+        "gauge",
+        "timing",
+        "histogram",
+        "record_exception",
+        "add_event",
+        "set_attribute",
+        "set_attributes",
+        "set_status",
+    }
+)
 
 #: Clock reads. `time.monotonic()` / `perf_counter()` / `time()` and
 #: `datetime.now()` / `utcnow()` cannot raise at all, but they are the calls that
 #: turn an elapsed-time bookkeeping line into a "throwing" statement.
 _CLOCK_ROOTS = frozenset({"time", "datetime", "date"})
-_CLOCK_METHODS = frozenset({
-    "monotonic",
-    "monotonic_ns",
-    "perf_counter",
-    "perf_counter_ns",
-    "time",
-    "time_ns",
-    "now",
-    "utcnow",
-})
+_CLOCK_METHODS = frozenset(
+    {
+        "monotonic",
+        "monotonic_ns",
+        "perf_counter",
+        "perf_counter_ns",
+        "time",
+        "time_ns",
+        "now",
+        "utcnow",
+    }
+)
 
 #: Value-shaping builtins. These are what an instrumentation line calls on its
 #: arguments — `logger.info(..., n=len(items), elapsed_s=round(t, 2))`,
@@ -163,21 +174,23 @@ _CLOCK_METHODS = frozenset({
 #: line passes them, so they don't make the statement a candidate for the
 #: handler. Builtins that genuinely do work and raise (`open`, `eval`, `next`,
 #: `getattr`) are deliberately absent.
-_INERT_BUILTINS = frozenset({
-    "abs",
-    "bool",
-    "float",
-    "format",
-    "id",
-    "int",
-    "len",
-    "list",
-    "repr",
-    "round",
-    "str",
-    "tuple",
-    "type",
-})
+_INERT_BUILTINS = frozenset(
+    {
+        "abs",
+        "bool",
+        "float",
+        "format",
+        "id",
+        "int",
+        "len",
+        "list",
+        "repr",
+        "round",
+        "str",
+        "tuple",
+        "type",
+    }
+)
 
 
 def _attr_root(expr: ast.expr) -> str | None:
@@ -316,6 +329,8 @@ class NoFatTryBlocks(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated_source(source):
+            return []
         tree = parse_or_none(path, source)
         if tree is None:
             return []

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/no_repeated_string_literal.py

@@ -70,6 +70,11 @@ duplicate can be suppressed per-line with `# sarj-noqa: SARJ024 — <reason>`.
 
 Skipped entirely: `conftest.py`, test files (`test_*.py` or under a `tests/`
 directory) — fixtures legitimately repeat literal payloads.
+* **generated files** (`_paths.is_generated_source`). Their layout is the
+  generator's, and re-running the generator discards any edit, so a finding
+  there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
+  files git-tracked across bulbul and noura-be — Speakeasy's
+  `python/sdk/src/sarj_platform_sdk/` accounts for all of them.
 """
 
 from __future__ import annotations
@@ -80,6 +85,7 @@ import re
 from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+from sarj_python_lint.rules._paths import is_generated_source
 
 
 if TYPE_CHECKING:
@@ -109,6 +115,8 @@ class NoRepeatedStringLiteral(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated_source(source):
+            return []
         if _is_skipped_path(path):
             return []
         tree = parse_or_none(path, source)

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/no_sequential_await.py

@@ -76,6 +76,8 @@ class NoSequentialAwait(Rule):
     def check(self, path: Path, source: str) -> list[Diagnostic]:
         if _is_test_path(path):
             return []
+        if "await" not in source or "for " not in source:
+            return []
         tree = parse_or_none(path, source)
         if tree is None:
             return []

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/prefer_namedtuple_over_tuple_return.py

@@ -70,6 +70,12 @@ Suppress a deliberate positional return with `# sarj-noqa: SARJ026 — <reason>`
 References:
 - https://docs.python.org/3/library/typing.html#typing.NamedTuple
 
+* **generated files** (`_paths.is_generated_source`). Their layout is the
+  generator's, and re-running the generator discards any edit, so a finding
+  there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
+  files git-tracked across bulbul and noura-be — Speakeasy's
+  `python/sdk/src/sarj_platform_sdk/` accounts for all of them.
+
 """
 
 from __future__ import annotations
@@ -80,7 +86,7 @@ from types import EllipsisType
 from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
-from sarj_python_lint.rules._paths import is_test_path
+from sarj_python_lint.rules._paths import is_generated_source, is_test_path
 
 
 if TYPE_CHECKING:
@@ -140,6 +146,8 @@ class PreferNamedtupleOverTupleReturn(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated_source(source):
+            return []
         if is_test_path(path):
             return []
         tree = parse_or_none(path, source)

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/prefer_str_enum.py

@@ -235,6 +235,8 @@ class PreferStrEnum(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not _has_str_enum_signal(source):
+            return []
         tree = parse_or_none(path, source)
         if tree is None:
             return []
@@ -332,6 +334,22 @@ class PreferStrEnum(Rule):
         return diags
 
 
+def _has_str_enum_signal(source: str) -> bool:
+    """Cheap source gate for files that cannot contain this rule's triggers.
+
+    Returns:
+        True when the source contains enough lexical signal to justify parsing.
+
+    """
+    has_string_literal = '"' in source or "'" in source
+    if "str" in source and any(name in source.lower() for name in CHOICES_ATTR_NAMES):
+        return True
+    return (
+        has_string_literal
+        and ("==" in source or "!=" in source or "case " in source or "match " in source)
+    )
+
+
 def _cluster_fires(key: str, entry: _ClusterEntry) -> bool:
     _line, _col, literals, eq_literals, ne_literals, in_literals = entry
     if not eq_literals and not ne_literals:

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/prefer_timedelta_for_durations.py

@@ -71,6 +71,12 @@ Suppress an intentional raw-numeric duration with `# sarj-noqa: SARJ014 — <rea
 References:
 - https://docs.python.org/3/library/datetime.html#timedelta-objects
 
+* **generated files** (`_paths.is_generated_source`). Their layout is the
+  generator's, and re-running the generator discards any edit, so a finding
+  there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
+  files git-tracked across bulbul and noura-be — Speakeasy's
+  `python/sdk/src/sarj_platform_sdk/` accounts for all of them.
+
 """
 
 from __future__ import annotations
@@ -80,7 +86,7 @@ import re
 from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
-from sarj_python_lint.rules._paths import is_test_path
+from sarj_python_lint.rules._paths import is_generated_source, is_test_path
 
 
 if TYPE_CHECKING:
@@ -104,6 +110,25 @@ _EXCLUDE_RE = re.compile(
 )
 
 _NUMERIC_NAMES = frozenset({"int", "float"})
+_BARE_UNIT_NAMES = frozenset(
+    {
+        "day",
+        "days",
+        "hour",
+        "hours",
+        "minute",
+        "minutes",
+        "min",
+        "mins",
+        "second",
+        "seconds",
+        "sec",
+        "secs",
+        "millisecond",
+        "milliseconds",
+        "ms",
+    }
+)
 
 #: Roots of the CLI frameworks whose decorators bind a parameter to an argv value.
 _CLI_MODULES = frozenset({"click", "typer"})
@@ -138,6 +163,8 @@ class PreferTimedeltaForDurations(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated_source(source):
+            return []
         if is_test_path(path):
             return []
         tree = parse_or_none(path, source)
@@ -172,6 +199,8 @@ class PreferTimedeltaForDurations(Rule):
     ) -> None:
         if annotation is None:
             return
+        if name.lower() in _BARE_UNIT_NAMES or name.lower().endswith(("_worked", "_elapsed")):
+            return
         if not _UNIT_RE.search(name) or _EXCLUDE_RE.search(name):
             return
         numeric = _numeric_annotation(annotation)

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/single_public_export.py

@@ -39,6 +39,11 @@ a `tests/` directory), and framework-convention filenames whose stem is fixed by
 a framework/tool and cannot be renamed (`models.py`, `views.py`, `base.py`, ...).
 Modules whose single export already snake-cases to the stem are not flagged
 (there is nothing to improve).
+* **generated files** (`_paths.is_generated_source`). Their layout is the
+  generator's, and re-running the generator discards any edit, so a finding
+  there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
+  files git-tracked across bulbul and noura-be — Speakeasy's
+  `python/sdk/src/sarj_platform_sdk/` accounts for all of them.
 """
 
 from __future__ import annotations
@@ -48,6 +53,7 @@ import re
 from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+from sarj_python_lint.rules._paths import is_generated_source
 
 
 if TYPE_CHECKING:
@@ -128,6 +134,8 @@ class SinglePublicExport(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated_source(source):
+            return []
         if _is_skipped_path(path):
             return []
         if path.stem.lower() not in _JUNK_DRAWER_STEMS:

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/stepdown.py

@@ -58,6 +58,11 @@ Never fires on:
   `_code_str`). Siblings are excluded — an identically-named sibling method is a
   different method. Callers in classes outside the module remain invisible to
   syntactic analysis.
+* **generated files** (`_paths.is_generated_source`). Their layout is the
+  generator's, and re-running the generator discards any edit, so a finding
+  there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
+  files git-tracked across bulbul and noura-be — Speakeasy's
+  `python/sdk/src/sarj_platform_sdk/` accounts for all of them.
 """
 
 from __future__ import annotations
@@ -67,6 +72,7 @@ from collections import Counter
 from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+from sarj_python_lint.rules._paths import is_generated_source
 
 
 if TYPE_CHECKING:
@@ -105,8 +111,12 @@ class Stepdown(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated_source(source):
+            return []
         if _is_test_path(path):
             return []
+        if "def _" not in source and "async def _" not in source:
+            return []
         tree = parse_or_none(path, source)
         if tree is None:
             return []

{sarj_python_lint-0.17.0 → sarj_python_lint-0.18.1}/src/sarj_python_lint/rules/xfail_requires_strict.py

@@ -189,7 +189,9 @@ def _is_rotting_xfail(dec: ast.expr) -> bool:
 _ENV_PROBE_MODULES = frozenset({"sys", "os", "platform", "sysconfig"})
 
 # Attribute / name words that identify an interpreter- or OS-version probe.
-_ENV_PROBE_RE = re.compile(r"version|implementation|platform|machine|pypy|jython|win32|windows|linux|darwin|macos", re.IGNORECASE)
+_ENV_PROBE_RE = re.compile(
+    r"version|implementation|platform|machine|pypy|jython|win32|windows|linux|darwin|macos", re.IGNORECASE
+)
 
 
 def _is_environment_gated(dec: ast.Call) -> bool: