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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.37.0
+Version: 1.39.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.37.0 → sarj_python_lint-1.39.0}/pyproject.toml

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

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

@@ -32,6 +32,7 @@ from sarj_python_lint.rules.no_analytical_aggregation_in_postgres_store import (
     NoAnalyticalAggregationInPostgresStore,
 )
 from sarj_python_lint.rules.no_any_mapping_types import NoAnyMappingTypes
+from sarj_python_lint.rules.no_async_function_cache import NoAsyncFunctionCache
 from sarj_python_lint.rules.no_before_validator_input_mutation import NoBeforeValidatorInputMutation
 from sarj_python_lint.rules.no_broad_keyword_capture import NoBroadKeywordCapture
 from sarj_python_lint.rules.no_comment_cruft import NoCommentCruft
@@ -65,6 +66,7 @@ from sarj_python_lint.rules.no_injected_module_loader import NoInjectedModuleLoa
 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_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
@@ -241,6 +243,8 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoSwallowedAsyncioCancellation.id: NoSwallowedAsyncioCancellation,
         RequireExplicitPsycopgTransaction.id: RequireExplicitPsycopgTransaction,
         AsyncMockCallWithoutAwaitAssertion.id: AsyncMockCallWithoutAwaitAssertion,
+        NoAsyncFunctionCache.id: NoAsyncFunctionCache,
+        NoLoguruExcInfo.id: NoLoguruExcInfo,
         ComplexPostgresQueryRequiresArchitectureReview.id: ComplexPostgresQueryRequiresArchitectureReview,
         ExcessiveCommentary.id: ExcessiveCommentary,
         PreferWalrusAwaitedNoneGuard.id: PreferWalrusAwaitedNoneGuard,

sarj_python_lint-1.39.0/src/sarj_python_lint/rules/no_async_function_cache.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+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._ast_index import children
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_FUNCTOOLS = frozenset({"functools"})
+_COROUTINE_CACHES = frozenset({"cache", "cached_property", "lru_cache"})
+_LRU_CACHE_POSITIONAL_ARGUMENTS = 2
+
+
+@final
+class NoAsyncFunctionCache(Rule):
+    id = "no-async-function-cache"
+    code = "SARJ507"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Standard library cache decorates a coroutine function and retains single-use coroutine objects.",
+        rationale=(
+            "`functools.cache`, `lru_cache`, and `cached_property` store the coroutine object returned by an async "
+            "function rather than its awaited value. A subsequent cache hit can raise `RuntimeError: cannot reuse "
+            "already awaited coroutine`."
+        ),
+        remediation="Remove the standard library cache or use an async-aware cache that stores completed results.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only a proven functools import used as the innermost decorator on a coroutine function is reported.",
+            "Async generators, transformed functions, ambiguous or rebound imports, and generated files are excluded.",
+            "Wildcard imports and names rebound by relative imports or imports outside the module body are excluded conservatively.",
+            "lru_cache with disabled, dynamic, or unpacked maxsize arguments is excluded; an omitted size or literal positive integer or None is required.",
+            "Indirect wrapping calls and runtime monkeypatches are not resolved. Test code is checked because coroutine reuse fails there too.",
+            "No automatic rewrite is offered because cache lifetime, cancellation, and concurrency require an explicit design decision.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="cached-coroutine-function",
+                title="A standard cache retains an exhausted coroutine",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/cache.py",
+                        "from functools import cache\n\n@cache\nasync def load() -> int:\n    return 1\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/cache.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="fresh-coroutine-function",
+                title="Each call creates a fresh coroutine",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/cache.py", "async def load() -> int:\n    return 1\n"),),
+                focus_path=PurePosixPath("app/cache.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if "async" not in context.source or context.generated or context.tree is None:
+            return []
+        shadowed = _nested_import_names(context)
+        if "*" in shadowed:
+            return []
+        diagnostics: list[Diagnostic] = []
+        for function in context.nodes(ast.AsyncFunctionDef):
+            if not function.decorator_list:
+                continue
+            decorator = function.decorator_list[-1]
+            if (
+                not _is_coroutine_cache(decorator, context.imports, shadowed)
+                or _has_own_yield(function)
+                or is_suppressed(context.source_lines, decorator.lineno, self.code)
+            ):
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    path=context.path,
+                    line=decorator.lineno,
+                    col=decorator.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        "Standard library cache retains a single-use coroutine; remove it or use an async-aware "
+                        "cache that stores awaited results."
+                    ),
+                    severity=Severity.WARNING,
+                ),
+            )
+        return diagnostics
+
+
+def _nested_import_names(context: PythonFileContext) -> frozenset[str]:
+    return frozenset(
+        alias.asname or alias.name.partition(".")[0]
+        for node in context.nodes(ast.Import, ast.ImportFrom)
+        for alias in node.names
+        if context.parents[node] is not context.tree
+        or (isinstance(node, ast.ImportFrom) and node.level > 0)
+        or alias.name == "*"
+    )
+
+
+def _is_coroutine_cache(decorator: ast.expr, imports: ImportIndex, shadowed: frozenset[str]) -> bool:
+    target = decorator.func if isinstance(decorator, ast.Call) else decorator
+    root = target
+    while isinstance(root, ast.Attribute):
+        root = root.value
+    if isinstance(root, ast.Name) and root.id in shadowed:
+        return False
+    symbol = imports.resolved_symbol(target, sources=_FUNCTOOLS)
+    if symbol not in _COROUTINE_CACHES:
+        return False
+    if not isinstance(decorator, ast.Call):
+        return True
+    if symbol != "lru_cache" or any(keyword.arg is None for keyword in decorator.keywords):
+        return False
+    if len(decorator.args) > _LRU_CACHE_POSITIONAL_ARGUMENTS or any(
+        isinstance(argument, ast.Starred) for argument in decorator.args
+    ):
+        return False
+    sizes = [keyword.value for keyword in decorator.keywords if keyword.arg == "maxsize"]
+    if decorator.args:
+        sizes.append(decorator.args[0])
+    if not sizes:
+        return True
+    if len(sizes) != 1:
+        return False
+    match sizes[0]:
+        case ast.Constant(value=None):
+            return True
+        case ast.Constant(value=int() as size) | ast.UnaryOp(op=ast.UAdd(), operand=ast.Constant(value=int() as size)):
+            return size > 0
+        case _:
+            return False
+
+
+def _has_own_yield(function: ast.AsyncFunctionDef) -> bool:
+    pending: list[ast.AST] = list(function.body)
+    while pending:
+        match pending.pop():
+            case ast.Yield() | ast.YieldFrom():
+                return True
+            case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.Lambda() as definition:
+                pending.extend(definition.args.defaults)
+                pending.extend(default for default in definition.args.kw_defaults if default is not None)
+                if not isinstance(definition, ast.Lambda):
+                    pending.extend(definition.decorator_list)
+            case ast.ClassDef() as definition:
+                pending.extend(definition.bases)
+                pending.extend(keyword.value for keyword in definition.keywords)
+                pending.extend(definition.decorator_list)
+            case node:
+                pending.extend(children(node))
+    return False

sarj_python_lint-1.39.0/src/sarj_python_lint/rules/no_loguru_exc_info.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+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,
+)
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_METHODS = frozenset({"trace", "debug", "info", "success", "warning", "error", "critical", "log"})
+_LOGURU = frozenset({"loguru"})
+
+
+@final
+class NoLoguruExcInfo(Rule):
+    id = "no-loguru-exc-info"
+    code = "SARJ508"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Loguru exc_info=True adds a field rather than retaining the exception traceback.",
+        rationale=(
+            "Loguru accepts logging keyword arguments as structured fields. The standard logging `exc_info=True` "
+            "argument therefore does not attach an exception, leaving failure logs without their traceback."
+        ),
+        remediation="Use `logger.opt(exception=True)` or `logger.exception(...)` when reporting the active exception.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only unambiguous Loguru imports and immediate bind/opt chains with literal exc_info=True are checked.",
+            "A literal message is required; templates using exc_info or the record, explicit exception capture, and exception() are excluded.",
+            "Unknown receivers, stored logger aliases, dynamic exc_info values, ambiguous imports, and generated files are excluded.",
+            "Runtime monkeypatches of Loguru objects or methods are not resolved.",
+            "An intentionally stored field can use a diagnostic-specific suppression. No automatic rewrite changes logging context.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="stdlib-argument-on-loguru",
+                title="A standard logging argument does not capture the exception",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py",
+                        'from loguru import logger\ntry:\n    int("invalid")\nexcept ValueError:\n    logger.warning("failed", exc_info=True)\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="loguru-exception-option",
+                title="Loguru captures the exception through opt",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py",
+                        'from loguru import logger\ntry:\n    int("invalid")\nexcept ValueError:\n    logger.opt(exception=True).warning("failed")\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 "exc_info" not in context.source or context.generated or context.tree is None:
+            return []
+        shadowed = _ambiguous_import_names(context)
+        if "*" in shadowed:
+            return []
+        diagnostics: list[Diagnostic] = []
+        for call in context.nodes(ast.Call):
+            if not isinstance(call.func, ast.Attribute) or call.func.attr not in _METHODS:
+                continue
+            keyword = next((item for item in call.keywords if item.arg == "exc_info"), None)
+            if keyword is None or not isinstance(keyword.value, ast.Constant) or keyword.value.value is not True:
+                continue
+            if (
+                not _is_unconfigured_loguru(call.func.value, context, shadowed)
+                or not _has_unused_exc_info(call)
+                or is_suppressed(context.source_lines, keyword.lineno, self.code)
+            ):
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    path=context.path,
+                    line=keyword.lineno,
+                    col=keyword.col_offset + 1,
+                    code=self.code,
+                    message="Loguru treats exc_info=True as a field; use opt(exception=True) or exception() to retain the traceback.",
+                    severity=Severity.WARNING,
+                ),
+            )
+        return diagnostics
+
+
+def _ambiguous_import_names(context: PythonFileContext) -> frozenset[str]:
+    return frozenset(
+        alias.asname or alias.name.partition(".")[0]
+        for node in context.nodes(ast.Import, ast.ImportFrom)
+        for alias in node.names
+        if context.parents[node] is not context.tree
+        or (isinstance(node, ast.ImportFrom) and node.level > 0)
+        or alias.name == "*"
+    )
+
+
+def _is_unconfigured_loguru(receiver: ast.expr, context: PythonFileContext, shadowed: frozenset[str]) -> bool:
+    opted = False
+    while isinstance(receiver, ast.Call) and isinstance(receiver.func, ast.Attribute):
+        method = receiver.func.attr
+        if method not in {"bind", "opt"}:
+            return False
+        if method == "opt" and not opted:
+            opted = True
+            if any(
+                keyword.arg is None
+                or (
+                    keyword.arg == "exception"
+                    and not (isinstance(keyword.value, ast.Constant) and not keyword.value.value)
+                )
+                for keyword in receiver.keywords
+            ):
+                return False
+        receiver = receiver.func.value
+    root = receiver
+    while isinstance(root, ast.Attribute):
+        root = root.value
+    return not (isinstance(root, ast.Name) and root.id in shadowed) and context.imports.resolves(
+        receiver, sources=_LOGURU, symbol="logger"
+    )
+
+
+def _has_unused_exc_info(call: ast.Call) -> bool:
+    message_index = int(isinstance(call.func, ast.Attribute) and call.func.attr == "log")
+    message = (
+        call.args[message_index]
+        if len(call.args) > message_index
+        else next((keyword.value for keyword in call.keywords if keyword.arg == "message"), None)
+    )
+    if not isinstance(message, ast.Constant) or not isinstance(message.value, str):
+        return False
+    return not _template_may_use_exc_info(message.value)
+
+
+def _template_may_use_exc_info(template: str) -> bool:
+    pending = [template]
+    try:
+        while pending:
+            for _, field, spec, _ in Formatter().parse(pending.pop()):
+                if field is not None:
+                    if field.partition(".")[0].partition("[")[0] in {"exc_info", "record"}:
+                        return True
+                    if spec:
+                        pending.append(spec)
+    except ValueError:
+        return True
+    return False