sarj-python-lint 1.39.0__tar.gz → 1.40.0__tar.gz

{sarj_python_lint-1.39.0 → sarj_python_lint-1.40.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.39.0
+Version: 1.40.0
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://code-standards.sarj.ai/rules/python/
 Project-URL: Documentation, https://code-standards.sarj.ai/rules/python/

{sarj_python_lint-1.39.0 → sarj_python_lint-1.40.0}/pyproject.toml

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

{sarj_python_lint-1.39.0 → sarj_python_lint-1.40.0}/src/sarj_python_lint/rules/_registry.py

@@ -67,6 +67,7 @@ from sarj_python_lint.rules.no_input_model_mutation import NoInputModelMutation
 from sarj_python_lint.rules.no_interpreter_source_arguments import NoInterpreterSourceArguments
 from sarj_python_lint.rules.no_invalid_argument_name_suppression import NoInvalidArgumentNameSuppression
 from sarj_python_lint.rules.no_loguru_exc_info import NoLoguruExcInfo
+from sarj_python_lint.rules.no_loguru_printf_format import NoLoguruPrintfFormat
 from sarj_python_lint.rules.no_mocked_pydantic_value_object import NoMockedPydanticValueObject
 from sarj_python_lint.rules.no_nested_pydantic_field_validator import NoNestedPydanticFieldValidator
 from sarj_python_lint.rules.no_nullable_dependency_fallback import NoNullableDependencyFallback
@@ -245,6 +246,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         AsyncMockCallWithoutAwaitAssertion.id: AsyncMockCallWithoutAwaitAssertion,
         NoAsyncFunctionCache.id: NoAsyncFunctionCache,
         NoLoguruExcInfo.id: NoLoguruExcInfo,
+        NoLoguruPrintfFormat.id: NoLoguruPrintfFormat,
         ComplexPostgresQueryRequiresArchitectureReview.id: ComplexPostgresQueryRequiresArchitectureReview,
         ExcessiveCommentary.id: ExcessiveCommentary,
         PreferWalrusAwaitedNoneGuard.id: PreferWalrusAwaitedNoneGuard,

sarj_python_lint-1.40.0/src/sarj_python_lint/rules/no_loguru_printf_format.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+import re
+from string import Formatter
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_METHODS = frozenset({"trace", "debug", "info", "success", "warning", "error", "critical", "exception", "log"})
+_LOGURU = frozenset({"loguru"})
+_CONVERSION = re.compile(r"%(?:\([^()]*\))?[-+ #0]*+(?:[0-9]+|\*)?(?:\.(?:[0-9]*|\*))?[hlL]?[diouxXeEfFgGcrsa]")
+
+
+@final
+class NoLoguruPrintfFormat(Rule):
+    id = "no-loguru-printf-format"
+    code = "SARJ509"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Use brace formatting for positional values passed to Loguru.",
+        rationale=(
+            "Loguru formats messages with str.format rather than printf interpolation. A percent-style message "
+            "with positional values keeps its placeholders and loses the values from the rendered diagnostic."
+        ),
+        remediation=(
+            "Use Loguru brace fields with equivalent formatting, or retain diagnostic values as named structured "
+            "fields. Review numeric, mapping and width specifications rather than mechanically replacing percent signs."
+        ),
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only unambiguous module-level Loguru imports and immediate bind/opt chains with a literal message and supplied positional formatting arguments are checked.",
+            "The message must contain a valid percent conversion and no brace fields. Escaped percent signs alone, malformed templates, dynamic messages and expanded arguments are excluded.",
+            "Standard logging, unknown receivers, stored aliases, shadowed or escaped imports, custom wrapper chains, keyword-only fields and generated files are excluded.",
+            "Visible namespace or logger mutations invalidate import proof. Interprocedural effects and runtime monkeypatches are not resolved.",
+            "Argument types and printf arity are not inferred. The warning requests review; no automatic conversion changes formatting or structured logging contracts.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="printf-values-ignored",
+                title="Loguru leaves printf placeholders unchanged",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py",
+                        'from loguru import logger\nlogger.error("Request %s failed with status %d", "request-marker", 503)\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="brace-values-rendered",
+                title="Brace fields render positional diagnostic values",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py",
+                        'from loguru import logger\nlogger.error("Request {} failed with status {}", "request-marker", 503)\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if "%" not in context.source or "loguru" not in context.source or context.generated or context.tree is None:
+            return []
+        provenance: ResourceProvenance | None = None
+        diagnostics: list[Diagnostic] = []
+        for call in context.nodes(ast.Call):
+            if not isinstance(call.func, ast.Attribute) or call.func.attr not in _METHODS or not _printf_message(call):
+                continue
+            receiver = _logger_root(call.func.value)
+            if receiver is None or not context.imports.resolves(receiver, sources=_LOGURU, symbol="logger"):
+                continue
+            if provenance is None:
+                provenance = ResourceProvenance(context, require_static_namespace=True)
+                if not _logger_imports_untouched(context, provenance):
+                    return []
+            if not provenance.imported(receiver, "loguru.logger") or is_suppressed(
+                context.source_lines, call.lineno, self.code
+            ):
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    path=context.path,
+                    line=call.lineno,
+                    col=call.col_offset + 1,
+                    code=self.code,
+                    message="Loguru leaves printf placeholders unchanged; use brace fields or named structured fields for these values.",
+                    severity=Severity.WARNING,
+                ),
+            )
+        return diagnostics
+
+
+def _logger_imports_untouched(context: PythonFileContext, provenance: ResourceProvenance) -> bool:
+    for node in context.nodes(ast.Name, ast.Attribute):
+        qualified = context.imports.resolved_qualified_name(node)
+        if qualified in {"loguru", "loguru.logger"} and not provenance.imported(node, qualified):
+            return False
+    return True
+
+
+def _logger_root(receiver: ast.expr) -> ast.expr | None:
+    while isinstance(receiver, ast.Call) and isinstance(receiver.func, ast.Attribute):
+        if (
+            receiver.func.attr not in {"bind", "opt"}
+            or any(isinstance(argument, ast.Starred) for argument in receiver.args)
+            or any(keyword.arg is None for keyword in receiver.keywords)
+        ):
+            return None
+        receiver = receiver.func.value
+    return receiver
+
+
+def _printf_message(call: ast.Call) -> bool:
+    index = int(isinstance(call.func, ast.Attribute) and call.func.attr == "log")
+    if (
+        len(call.args) <= index + 1
+        or any(isinstance(argument, ast.Starred) for argument in call.args)
+        or any(keyword.arg is None for keyword in call.keywords)
+    ):
+        return False
+    message = call.args[index]
+    if not isinstance(message, ast.Constant) or not isinstance(message.value, str):
+        return False
+    try:
+        if any(field is not None for _, field, _, _ in Formatter().parse(message.value)):
+            return False
+    except ValueError:
+        return False
+    position = 0
+    converted = False
+    while (position := message.value.find("%", position)) != -1:
+        if message.value.startswith("%%", position):
+            position += 2
+            continue
+        token = _CONVERSION.match(message.value, position)
+        if token is None:
+            return False
+        converted = True
+        position = token.end()
+    return converted

{sarj_python_lint-1.39.0 → sarj_python_lint-1.40.0}/src/sarj_python_lint/rules/no_repeated_string_literal.py

@@ -307,7 +307,7 @@ def _is_skipped_path(path: Path) -> bool:
             "snapshots",
         }
     )
-    return is_test_path(path) or bool(excluded_parts.intersection(part.lower() for part in path.parts))
+    return is_test_path(path) or not excluded_parts.isdisjoint(part.lower() for part in path.parts)
 
 
 def _exclude_scaffolding_strings(node: ast.Call, excluded: set[int]) -> None:

{sarj_python_lint-1.39.0 → sarj_python_lint-1.40.0}/src/sarj_python_lint/rules/prefer_constant_time_secret_compare.py

@@ -295,7 +295,7 @@ def _name_role(identifier: str) -> _Role:
     if not _is_authenticator_name(identifier):
         return _Role(external=False, expected=False)
     first = leading_word(identifier) or ""
-    external = first in _EXTERNAL_PREFIXES or ("header" in tokens and bool(set(tokens) & {"auth", "authorization"}))
+    external = first in _EXTERNAL_PREFIXES or ("header" in tokens and not {"auth", "authorization"}.isdisjoint(tokens))
     expected = first in _EXPECTED_PREFIXES or identifier.isupper()
     return _Role(external=external, expected=expected, password=_node_name_is_password(identifier))
 
@@ -400,7 +400,7 @@ def _node_is_password(node: ast.expr) -> bool:
 
 
 def _node_name_is_password(identifier: str) -> bool:
-    return bool(set(identifier_tokens(identifier)) & {"passwd", "password", "passwords"})
+    return not {"passwd", "password", "passwords"}.isdisjoint(identifier_tokens(identifier))
 
 
 def _environment_names(module: ast.Module) -> frozenset[str]:

{sarj_python_lint-1.39.0 → sarj_python_lint-1.40.0}/src/sarj_python_lint/rules/prefer_match_assert_never.py

@@ -204,7 +204,7 @@ def _ignores_argument_type(comment: str) -> bool:
     if match is None:
         return False
     codes = match.group(1)
-    return codes is None or bool({code.strip() for code in codes.split(",")} & {"reportArgumentType", "arg-type"})
+    return codes is None or not {"reportArgumentType", "arg-type"}.isdisjoint(code.strip() for code in codes.split(","))
 
 
 def _module_scope_classdefs(tree: ast.Module) -> list[ast.ClassDef]:

{sarj_python_lint-1.39.0 → sarj_python_lint-1.40.0}/src/sarj_python_lint/rules/prefer_set_isdisjoint.py

@@ -59,9 +59,10 @@ class PreferSetIsdisjoint(ProjectRule):
         category=RuleCategory.STYLE,
         autofix=AutofixPolicy.SUGGESTION,
         limitations=(
+            "Explicit unshadowed built-in bool calls are predicates even in assignments and returns. Raw stored or returned intersections remain values, not predicates.",
             "Set receivers must come from a literal, comprehension, constructor, dominating local assignment, or an unchanged parameter's directly declared first-party set/frozenset field.",
             "Dictionary key-view receivers require a literal/comprehension/constructor or one unreassigned, dominating local binding. Custom mappings and unproven parameters are excluded.",
-            "Declared fields rely on the annotated contract. Unknown or union field types, properties, explicit owner/field reassignment, branch-merged bindings, stored intersections, and generated files are excluded. The other operand must be a known iterable.",
+            "Declared fields rely on the annotated contract. Unknown or union field types, properties, explicit owner/field reassignment, branch-merged bindings, stored intersections, and generated files are excluded. Captured bindings in deferred lambda/generator bodies and starred intersection arguments are excluded. The other operand must be a known iterable.",
             "The suggestion is intentionally not an autofix because short-circuiting may make custom element equality or hashing side effects observable.",
         ),
         examples=(
@@ -73,7 +74,7 @@ class PreferSetIsdisjoint(ProjectRule):
                     ExampleFile(PurePosixPath("pyproject.toml"), '[project]\nname = "example"\nversion = "0.1.0"\n'),
                     ExampleFile.python(
                         "app/policy.py",
-                        "class AccessCase:\n    tags: frozenset[str]\n\ndef accepts(case: AccessCase):\n    if case.tags & {'read', 'write'}:\n        allow()\n",
+                        "class AccessCase:\n    tags: frozenset[str]\n\ndef accepts(case: AccessCase):\n    return bool(case.tags & {'read', 'write'})\n",
                     ),
                 ),
                 focus_path=PurePosixPath("app/policy.py"),
@@ -144,18 +145,22 @@ class _Scanner:
             self._update_binding(statement, local)
 
     def _scan_statement(self, statement: ast.stmt, exact: set[str]) -> None:
+        exact.difference_update(_named_expression_targets(statement))
+        if isinstance(
+            statement,
+            ast.If | ast.While | ast.For | ast.AsyncFor | ast.With | ast.AsyncWith | ast.Try | ast.Match,
+        ):
+            stored = _stored_names(statement)
+            if "*" in stored:
+                exact.clear()
+            else:
+                exact.difference_update(stored)
         match statement:
-            case ast.If():
+            case ast.If() | ast.While():
                 self._scan_boolean(statement.test, exact)
                 self._scan_embedded(statement.test, exact)
                 self.scan_body(statement.body, set(exact))
                 self.scan_body(statement.orelse, set(exact))
-            case ast.While():
-                loop_exact = exact - _stored_names(ast.Module(body=[*statement.body, *statement.orelse]))
-                self._scan_boolean(statement.test, loop_exact)
-                self._scan_embedded(statement.test, loop_exact)
-                self.scan_body(statement.body, set(exact))
-                self.scan_body(statement.orelse, set(exact))
             case ast.Assert(test=test):
                 self._scan_boolean(test, exact)
                 self._scan_embedded(test, exact)
@@ -172,7 +177,7 @@ class _Scanner:
             case ast.With() | ast.AsyncWith():
                 nested = set(exact)
                 for item in statement.items:
-                    self._scan_embedded(item.context_expr, exact)
+                    self._scan_embedded(item.context_expr, nested)
                     if item.optional_vars is not None:
                         nested.difference_update(_stored_names(item.optional_vars))
                 self.scan_body(statement.body, nested)
@@ -192,9 +197,14 @@ class _Scanner:
 
     def _scan_embedded(self, expression: ast.expr, exact: set[str]) -> None:
         if isinstance(expression, ast.Lambda):
-            nested = exact - _argument_names(expression.args)
-            self._scan_embedded(expression.body, nested)
+            self._scan_embedded(expression.body, set())
             return
+        if _is_builtin_bool_call(expression, self.shadowed) or (
+            isinstance(expression, ast.UnaryOp)
+            and isinstance(expression.op, ast.Not)
+            and _is_builtin_bool_call(expression.operand, self.shadowed)
+        ):
+            self._scan_boolean(expression, exact)
         if isinstance(expression, ast.IfExp):
             self._scan_boolean(expression.test, exact)
         if isinstance(expression, ast.DictComp):
@@ -202,6 +212,9 @@ class _Scanner:
             self._scan_embedded(expression.key, nested)
             self._scan_embedded(expression.value, nested)
             return
+        if isinstance(expression, ast.GeneratorExp):
+            self._scan_embedded(expression.generators[0].iter, exact)
+            exact = set()
         if isinstance(expression, ast.ListComp | ast.SetComp | ast.GeneratorExp):
             nested = self._scan_comprehensions(expression.generators, exact)
             self._scan_embedded(expression.elt, nested)
@@ -252,7 +265,6 @@ class _Scanner:
         )
 
     def _update_binding(self, statement: ast.stmt, exact: set[str]) -> None:
-        exact.difference_update(_named_expression_targets(statement))
         match statement:
             case ast.Assign(targets=[ast.Name(id=name)], value=value):
                 if _is_exact_set(value, exact, self.shadowed):
@@ -274,17 +286,6 @@ class _Scanner:
                 exact.difference_update(alias.asname or alias.name.split(".")[0] for alias in aliases)
             case ast.ImportFrom(names=aliases):
                 _invalidate_imported_bindings(aliases, exact)
-            case (
-                ast.If()
-                | ast.While()
-                | ast.For()
-                | ast.AsyncFor()
-                | ast.With()
-                | ast.AsyncWith()
-                | ast.Try()
-                | ast.Match()
-            ):
-                exact.difference_update(_stored_names(statement))
             case _:
                 pass
 
@@ -299,6 +300,7 @@ def _is_intersection(node: ast.expr, exact: set[str], shadowed: frozenset[str],
         and isinstance(node.func, ast.Attribute)
         and node.func.attr == "intersection"
         and len(node.args) == 1
+        and not isinstance(node.args[0], ast.Starred)
         and not node.keywords
         and _is_exact_set(node.func.value, exact, shadowed)
     )
@@ -356,45 +358,37 @@ def _is_proven_iterable(node: ast.expr, exact: set[str], shadowed: frozenset[str
     )
 
 
-def _stored_names(node: ast.AST) -> set[str]:
-    return {child.id for child in walk_ast(node) if isinstance(child, ast.Name) and isinstance(child.ctx, ast.Store)}
+def _stored_names(node: ast.AST, *, node_index: NodeIndex | None = None) -> set[str]:
+    names: set[str] = set()
+    for child in walk_ast(node, index=node_index):
+        match child:
+            case (
+                ast.Name(id=name, ctx=ast.Store() | ast.Del())
+                | ast.arg(arg=name)
+                | ast.FunctionDef(name=name)
+                | ast.AsyncFunctionDef(name=name)
+                | ast.ClassDef(name=name)
+                | ast.ExceptHandler(name=name)
+                | ast.MatchAs(name=name)
+                | ast.MatchStar(name=name)
+                | ast.MatchMapping(rest=name)
+            ):
+                if name is not None:
+                    names.add(name)
+            case ast.alias(name=name, asname=alias):
+                names.add(alias or name.split(".")[0])
+            case _:
+                pass
+    return names
 
 
 def _named_expression_targets(node: ast.AST) -> set[str]:
     return {expression.target.id for expression in walk_ast(node) if isinstance(expression, ast.NamedExpr)}
 
 
-def _argument_names(arguments: ast.arguments) -> set[str]:
-    return {
-        argument.arg
-        for argument in (
-            *arguments.posonlyargs,
-            *arguments.args,
-            *arguments.kwonlyargs,
-            *((arguments.vararg,) if arguments.vararg is not None else ()),
-            *((arguments.kwarg,) if arguments.kwarg is not None else ()),
-        )
-    }
-
-
 def _shadowed_builtins(tree: ast.Module, *, node_index: NodeIndex | None = None) -> frozenset[str]:
-    shadowed: set[str] = set()
-    for node in walk_ast(tree, index=node_index):
-        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store) and node.id in _TRACKED_BUILTINS:
-            shadowed.add(node.id)
-        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) and node.name in _TRACKED_BUILTINS:
-            shadowed.add(node.name)
-        elif isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names):
-            shadowed.update(_TRACKED_BUILTINS)
-        elif isinstance(node, ast.ExceptHandler | ast.MatchAs | ast.MatchStar) and node.name in _TRACKED_BUILTINS:
-            shadowed.add(node.name)
-        elif isinstance(node, ast.MatchMapping) and node.rest in _TRACKED_BUILTINS:
-            shadowed.add(node.rest)
-        elif isinstance(node, ast.arg) and node.arg in _TRACKED_BUILTINS:
-            shadowed.add(node.arg)
-        elif isinstance(node, ast.alias) and (node.asname or node.name.split(".")[0]) in _TRACKED_BUILTINS:
-            shadowed.add(node.asname or node.name.split(".")[0])
-    return frozenset(shadowed)
+    stored = _stored_names(tree, node_index=node_index)
+    return _TRACKED_BUILTINS if "*" in stored else frozenset(stored.intersection(_TRACKED_BUILTINS))
 
 
 def _invalidate_imported_bindings(aliases: list[ast.alias], exact: set[str]) -> None: