sarj-python-lint 0.75.0__tar.gz → 0.77.0__tar.gz

{sarj_python_lint-0.75.0 → sarj_python_lint-0.77.0}/PKG-INFO

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

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

{sarj_python_lint-0.75.0 → sarj_python_lint-0.77.0}/src/sarj_python_lint/rules/_registry.py

@@ -33,10 +33,12 @@ from sarj_python_lint.rules.no_aggregation_in_store_query import (
     NoAggregationInStoreQuery,
 )
 from sarj_python_lint.rules.no_comment_cruft import NoCommentCruft
+from sarj_python_lint.rules.no_conftest_test_module_import import NoConftestTestModuleImport
 from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
     NoCorsWildcardWithCredentials,
 )
 from sarj_python_lint.rules.no_duplicate_dunder_all_entry import NoDuplicateDunderAllEntry
+from sarj_python_lint.rules.no_fastapi_on_event import NoFastapiOnEvent
 from sarj_python_lint.rules.no_file_level_escape_hatch_noqa import NoFileLevelEscapeHatchNoqa
 from sarj_python_lint.rules.no_first_party_private_import import (
     NoFirstPartyPrivateImport,
@@ -51,11 +53,13 @@ from sarj_python_lint.rules.no_hidden_constructor_fallback import (
 )
 from sarj_python_lint.rules.no_isinstance_union_chain import NoIsinstanceUnionChain
 from sarj_python_lint.rules.no_long_comment import NoLongComment
+from sarj_python_lint.rules.no_nested_pydantic_field_validator import NoNestedPydanticFieldValidator
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
 from sarj_python_lint.rules.no_optional_tenant_predicate import (
     NoOptionalTenantPredicate,
 )
 from sarj_python_lint.rules.no_query_with_many_joins import NoQueryWithManyJoins
+from sarj_python_lint.rules.no_redundant_literal_description import NoRedundantLiteralDescription
 from sarj_python_lint.rules.no_repeated_string_literal import NoRepeatedStringLiteral
 from sarj_python_lint.rules.no_restated_comment import NoRestatedComment
 from sarj_python_lint.rules.no_secret_in_log import NoSecretInLog
@@ -125,6 +129,9 @@ from sarj_python_lint.rules.repeated_static_call_cases import RepeatedStaticCall
 from sarj_python_lint.rules.require_keyword_only_swap_prone_params import (
     RequireKeywordOnlySwapProneParams,
 )
+from sarj_python_lint.rules.require_nodecode_for_splitting_settings_field import (
+    RequireNoDecodeForSplittingSettingsField,
+)
 from sarj_python_lint.rules.require_port_for_service import RequirePortForService
 from sarj_python_lint.rules.require_pydantic_for_external_json import (
     RequirePydanticForExternalJson,
@@ -169,6 +176,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferTimedeltaForDurations.id: PreferTimedeltaForDurations,
         PreferStructOverNamedtuple.id: PreferStructOverNamedtuple,
         NoCommentCruft.id: NoCommentCruft,
+        NoConftestTestModuleImport.id: NoConftestTestModuleImport,
         StoreInsertRequiresOnConflict.id: StoreInsertRequiresOnConflict,
         SourceCoupledTest.id: SourceCoupledTest,
         IacSourceCoupledTest.id: IacSourceCoupledTest,
@@ -198,6 +206,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoGenRandomUuidInSql.id: NoGenRandomUuidInSql,
         NoHiddenConstructorFallback.id: NoHiddenConstructorFallback,
         NoFileLevelEscapeHatchNoqa.id: NoFileLevelEscapeHatchNoqa,
+        NoFastapiOnEvent.id: NoFastapiOnEvent,
         NoOptionalTenantPredicate.id: NoOptionalTenantPredicate,
         NoTautologicalExpect.id: NoTautologicalExpect,
         PreferLibraryFake.id: PreferLibraryFake,
@@ -226,6 +235,8 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RestatedTestDocstring.id: RestatedTestDocstring,
         TestPhaseLabelComment.id: TestPhaseLabelComment,
         NoLongComment.id: NoLongComment,
+        NoNestedPydanticFieldValidator.id: NoNestedPydanticFieldValidator,
+        NoRedundantLiteralDescription.id: NoRedundantLiteralDescription,
         NoTypedDocSections.id: NoTypedDocSections,
         NoUnnecessaryDocstring.id: NoUnnecessaryDocstring,
         PreferNominalIdTypes.id: PreferNominalIdTypes,
@@ -239,6 +250,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreserveDeclaredNominalId.id: PreserveDeclaredNominalId,
         PreserveEnumTypes.id: PreserveEnumTypes,
         RequirePydanticOrdinalLowerBound.id: RequirePydanticOrdinalLowerBound,
+        RequireNoDecodeForSplittingSettingsField.id: RequireNoDecodeForSplittingSettingsField,
         NoVagueSuppressionDescription.id: NoVagueSuppressionDescription,
     }
 )

sarj_python_lint-0.77.0/src/sarj_python_lint/rules/no_conftest_test_module_import.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    parse_or_none,
+)
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@final
+class NoConftestTestModuleImport(Rule):
+    id = "no-conftest-test-module-import"
+    code = "SARJ426"
+    documentation = RuleDocumentation(
+        summary="Do not import individual test modules from conftest.py.",
+        rationale=(
+            "pytest imports conftest for every test module in its scope; importing a specific test from conftest "
+            "turns that test into global collection infrastructure and creates cycles and order dependence."
+        ),
+        remediation="Move shared fixtures or helpers into conftest.py or a dedicated support module.",
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only files named conftest.py are inspected.",
+            "A test module is recognized only when an explicit module-path component begins with `test_` or ends with `_test`.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="conftest-imports-test-module",
+                title="Conftest imports a specific test module",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("tests/conftest.py", "from tests.test_api import make_client\n"),),
+                focus_path=PurePosixPath("tests/conftest.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="conftest-imports-support-module",
+                title="Conftest imports dedicated support code",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("tests/conftest.py", "from tests.helpers import make_client\n"),),
+                focus_path=PurePosixPath("tests/conftest.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if path.name != "conftest.py":
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        diagnostics: list[Diagnostic] = []
+        for statement in tree.body:
+            targets: list[str] = []
+            match statement:
+                case ast.Import(names=names):
+                    targets.extend(alias.name for alias in names if _module_has_test_leaf(alias.name))
+                case ast.ImportFrom(module=module, names=names):
+                    if module is not None and _module_has_test_leaf(module):
+                        targets.append(module)
+                case _:
+                    continue
+            if not targets:
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    path=path,
+                    line=statement.lineno,
+                    col=statement.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        f"conftest.py imports test module `{targets[0]}`; move shared fixtures or helpers to "
+                        "conftest or a dedicated support module."
+                    ),
+                )
+            )
+        return diagnostics
+
+
+def _module_has_test_leaf(module: str) -> bool:
+    parts = module.split(".")
+    return any(_is_test_module_name(part) for part in parts)
+
+
+def _is_test_module_name(name: str) -> bool:
+    return name.startswith("test_") or name.endswith("_test")

sarj_python_lint-0.77.0/src/sarj_python_lint/rules/no_fastapi_on_event.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    parse_or_none,
+)
+from sarj_python_lint.rules._imports import ImportIndex
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_APP_TYPES = frozenset({("fastapi", "FastAPI"), ("starlette.applications", "Starlette")})
+_EVENT_NAMES = frozenset({"startup", "shutdown"})
+
+
+@final
+class NoFastapiOnEvent(Rule):
+    id = "no-fastapi-on-event"
+    code = "SARJ427"
+    documentation = RuleDocumentation(
+        summary="Deprecated FastAPI or Starlette on_event lifecycle registration.",
+        rationale=(
+            "The on_event API is deprecated and splits related startup and shutdown state across callbacks; lifespan "
+            "keeps acquisition and cleanup in one async context manager and is the supported lifecycle contract."
+        ),
+        remediation="Define an async lifespan context manager and pass it as FastAPI(lifespan=...) or Starlette(lifespan=...).",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only decorators on a directly constructed FastAPI/Starlette application or a parameter annotated with one are checked.",
+            "Factory-returned applications and dynamically selected event names are intentionally not inferred.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="deprecated-startup-event",
+                title="Do not register startup through on_event",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/main.py",
+                        'from fastapi import FastAPI\napp = FastAPI()\n\n@app.on_event("startup")\nasync def start() -> None:\n    pass\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app/main.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="lifespan-context-manager",
+                title="Pair startup and shutdown in lifespan",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/main.py",
+                        "from contextlib import asynccontextmanager\nfrom fastapi import FastAPI\n\n"
+                        "@asynccontextmanager\nasync def lifespan(app: FastAPI):\n    yield\n\napp = FastAPI(lifespan=lifespan)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/main.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        imports = ImportIndex.from_tree(tree)
+        return _scope_diagnostics(path, tree.body, imports)
+
+
+def _scope_diagnostics(
+    path: Path,
+    statements: list[ast.stmt],
+    imports: ImportIndex,
+    *,
+    extra_app_names: frozenset[str] = frozenset(),
+) -> list[Diagnostic]:
+    app_names = _assigned_app_names(statements, imports) | extra_app_names
+    findings: list[Diagnostic] = []
+    for statement in statements:
+        if not isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        findings.extend(
+            Diagnostic(
+                path=path,
+                line=decorator.lineno,
+                col=decorator.col_offset + 1,
+                code="SARJ427",
+                message=(
+                    "FastAPI/Starlette on_event is deprecated. Put startup and shutdown work in an async lifespan "
+                    "context manager and pass it to the application constructor."
+                ),
+            )
+            for decorator in statement.decorator_list
+            if _is_on_event_decorator(decorator, app_names)
+        )
+        findings.extend(
+            _scope_diagnostics(
+                path,
+                statement.body,
+                imports,
+                extra_app_names=_annotated_app_parameters(statement.args, imports),
+            )
+        )
+    return findings
+
+
+def _assigned_app_names(statements: list[ast.stmt], imports: ImportIndex) -> frozenset[str]:
+    names: set[str] = set()
+    for statement in statements:
+        if not isinstance(statement, (ast.Assign, ast.AnnAssign)):
+            continue
+        value = statement.value
+        if not isinstance(value, ast.Call) or not any(
+            imports.resolves(value.func, sources=frozenset({source}), symbol=symbol) for source, symbol in _APP_TYPES
+        ):
+            continue
+        targets = statement.targets if isinstance(statement, ast.Assign) else [statement.target]
+        names.update(target.id for target in targets if isinstance(target, ast.Name))
+    return frozenset(names)
+
+
+def _annotated_app_parameters(arguments: ast.arguments, imports: ImportIndex) -> frozenset[str]:
+    parameters = [*arguments.posonlyargs, *arguments.args, *arguments.kwonlyargs]
+    if arguments.vararg is not None:
+        parameters.append(arguments.vararg)
+    if arguments.kwarg is not None:
+        parameters.append(arguments.kwarg)
+    return frozenset(
+        parameter.arg
+        for parameter in parameters
+        if parameter.annotation is not None
+        and any(
+            imports.resolves(parameter.annotation, sources=frozenset({source}), symbol=symbol)
+            for source, symbol in _APP_TYPES
+        )
+    )
+
+
+def _is_on_event_decorator(node: ast.expr, app_names: frozenset[str]) -> bool:
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr == "on_event"
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id in app_names
+        and len(node.args) == 1
+        and isinstance(node.args[0], ast.Constant)
+        and node.args[0].value in _EVENT_NAMES
+    )

sarj_python_lint-0.77.0/src/sarj_python_lint/rules/no_nested_pydantic_field_validator.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    parse_or_none,
+)
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_PYDANTIC_BASE_MODEL_SOURCES = frozenset({"pydantic", "pydantic.main"})
+_PYDANTIC_SOURCES = frozenset({"pydantic", "pydantic.functional_validators"})
+
+
+@final
+class NoNestedPydanticFieldValidator(Rule):
+    id = "no-nested-pydantic-field-validator"
+    code = "SARJ425"
+    documentation = RuleDocumentation(
+        summary="Do not place an outer Pydantic model's field validator inside a nested helper class.",
+        rationale=(
+            "A decorator indented into a nested class registers on that class, not on the outer Pydantic model, "
+            "so the declared field silently loses validation."
+        ),
+        remediation="Move the field-validator method into the outer model class.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only direct BaseModel subclasses and validators directly owned by one nested class are inspected.",
+            "Nested classes with bases are excluded because inherited Pydantic fields cannot be resolved locally.",
+            "Test and generated files are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="validator-nested-in-config",
+                title="Validator accidentally belongs to Config",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/models.py",
+                        "from pydantic import BaseModel, field_validator\n\n"
+                        "class Settings(BaseModel):\n"
+                        "    language: str\n"
+                        "    class Config:\n"
+                        "        extra = 'forbid'\n"
+                        "        @field_validator('language')\n"
+                        "        @classmethod\n"
+                        "        def normalize(cls, value):\n"
+                        "            return value.lower()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/models.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="validator-owned-by-model",
+                title="Validator belongs to the model",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/models.py",
+                        "from pydantic import BaseModel, field_validator\n\n"
+                        "class Settings(BaseModel):\n"
+                        "    language: str\n"
+                        "    @field_validator('language')\n"
+                        "    @classmethod\n"
+                        "    def normalize(cls, value):\n"
+                        "        return value.lower()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/models.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_test_path(path) or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        imports = ImportIndex.from_tree(tree)
+        diagnostics: list[Diagnostic] = []
+        for outer in (node for node in ast.walk(tree) if isinstance(node, ast.ClassDef)):
+            if not _is_direct_model(outer, imports):
+                continue
+            outer_fields = _direct_fields(outer)
+            for nested in (statement for statement in outer.body if isinstance(statement, ast.ClassDef)):
+                # A based nested class may be an indirect Pydantic model whose inherited
+                # fields are unavailable to this file-local analysis. Only base-less
+                # Config/helper classes provide a deterministic ownership mistake.
+                if nested.bases:
+                    continue
+                nested_fields = _direct_fields(nested)
+                for function in (
+                    statement
+                    for statement in nested.body
+                    if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef))
+                ):
+                    for decorator, fields in _field_validators(function, imports):
+                        misplaced = sorted((fields & outer_fields) - nested_fields)
+                        if not misplaced:
+                            continue
+                        diagnostics.append(
+                            Diagnostic(
+                                path=path,
+                                line=decorator.lineno,
+                                col=decorator.col_offset + 1,
+                                code=self.code,
+                                message=(
+                                    f"Validator for outer field(s) {', '.join(f'`{name}`' for name in misplaced)} "
+                                    f"is nested inside `{nested.name}`; move it to `{outer.name}`."
+                                ),
+                            )
+                        )
+        return diagnostics
+
+
+def _is_direct_model(node: ast.ClassDef, imports: ImportIndex) -> bool:
+    return len(node.bases) == 1 and imports.resolves(
+        node.bases[0], sources=_PYDANTIC_BASE_MODEL_SOURCES, symbol="BaseModel"
+    )
+
+
+def _direct_fields(node: ast.ClassDef) -> frozenset[str]:
+    return frozenset(
+        statement.target.id
+        for statement in node.body
+        if isinstance(statement, ast.AnnAssign)
+        and isinstance(statement.target, ast.Name)
+        and not statement.target.id.startswith("_")
+        and statement.target.id != "model_config"
+    )
+
+
+def _field_validators(
+    node: ast.FunctionDef | ast.AsyncFunctionDef, imports: ImportIndex
+) -> tuple[tuple[ast.Call, frozenset[str]], ...]:
+    validators: list[tuple[ast.Call, frozenset[str]]] = []
+    for decorator in node.decorator_list:
+        if not isinstance(decorator, ast.Call) or not imports.resolves(
+            decorator.func, sources=_PYDANTIC_SOURCES, symbol="field_validator"
+        ):
+            continue
+        fields = frozenset(
+            argument.value
+            for argument in decorator.args
+            if isinstance(argument, ast.Constant) and isinstance(argument.value, str)
+        )
+        validators.append((decorator, fields))
+    return tuple(validators)