sarj-python-lint 1.62.0__tar.gz → 1.63.0__tar.gz

{sarj_python_lint-1.62.0 → sarj_python_lint-1.63.0}/PKG-INFO

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

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

{sarj_python_lint-1.62.0 → sarj_python_lint-1.63.0}/src/sarj_python_lint/rules/_fastapi.py

@@ -47,6 +47,7 @@ class Route:
     inherited_hidden: bool = False
     inherited_responses: ast.expr | None = None
     inherited_response_class: ast.expr | None = None
+    inherited_prefix: ast.expr | None = None
 
     @property
     def keywords(self) -> dict[str, ast.expr]:
@@ -299,7 +300,7 @@ class FastapiIndex:
             self.receiver_defaults[key] = {
                 keyword.arg: keyword.value
                 for keyword in value.keywords
-                if keyword.arg in {"responses", "default_response_class"}
+                if keyword.arg in {"responses", "default_response_class", "prefix"}
             }
         if self._constructor_is_hidden(value):
             self.hidden_receivers.add(key)
@@ -398,6 +399,7 @@ class FastapiIndex:
                 inherited_hidden=receiver_key in self.hidden_receivers,
                 inherited_responses=defaults.get("responses"),
                 inherited_response_class=defaults.get("default_response_class"),
+                inherited_prefix=defaults.get("prefix"),
             )
             for route_method in route_methods
         )

{sarj_python_lint-1.62.0 → sarj_python_lint-1.63.0}/src/sarj_python_lint/rules/_registry.py

@@ -215,21 +215,31 @@ if TYPE_CHECKING:
     from collections.abc import Mapping
 
     from sarj_python_lint.rule_base import Rule
+from sarj_python_lint.rules.delete_route_returns_no_content import DeleteRouteReturnsNoContent
 from sarj_python_lint.rules.duplicate_adjacent_exception_handler import DuplicateAdjacentExceptionHandler
 from sarj_python_lint.rules.duplicate_closed_pure_helper import DuplicateClosedPureHelper
 from sarj_python_lint.rules.no_conflicting_pydantic_alias_validation import NoConflictingPydanticAliasValidation
 from sarj_python_lint.rules.no_contradictory_type_guard import NoContradictoryTypeGuard
+from sarj_python_lint.rules.no_create_verb_in_post_path import NoCreateVerbInPostPath
+from sarj_python_lint.rules.no_defaulted_environment_setting import NoDefaultedEnvironmentSetting
+from sarj_python_lint.rules.no_duplicate_field_validator_body import NoDuplicateFieldValidatorBody
+from sarj_python_lint.rules.no_exception_text_in_500_detail import NoExceptionTextIn500Detail
+from sarj_python_lint.rules.no_folded_bad_request_not_found import NoFoldedBadRequestNotFound
+from sarj_python_lint.rules.no_hasattr import NoHasattr
 from sarj_python_lint.rules.no_impossible_pydantic_field_bounds import NoImpossiblePydanticFieldBounds
 from sarj_python_lint.rules.no_invalid_pydantic_bypass import NoInvalidPydanticBypass
 from sarj_python_lint.rules.no_invalid_pydantic_validator_return import NoInvalidPydanticValidatorReturn
 from sarj_python_lint.rules.no_partial_type_is import NoPartialTypeIs
 from sarj_python_lint.rules.no_shallow_record_type_guard import NoShallowRecordTypeGuard
+from sarj_python_lint.rules.no_slash_collection_root_under_prefix import NoSlashCollectionRootUnderPrefix
 from sarj_python_lint.rules.no_unknown_pydantic_validator_field import NoUnknownPydanticValidatorField
+from sarj_python_lint.rules.no_work_verb_get_route import NoWorkVerbGetRoute
 from sarj_python_lint.rules.prefer_bulk_upsert import PreferBulkUpsert
 from sarj_python_lint.rules.prefer_discriminated_model_union import PreferDiscriminatedModelUnion
 from sarj_python_lint.rules.prefer_psycopg_executemany import PreferPsycopgExecutemany
 from sarj_python_lint.rules.redundant_test_constructor_forwarder import RedundantTestConstructorForwarder
 from sarj_python_lint.rules.repeated_unimplemented_test_contract import RepeatedUnimplementedTestContract
+from sarj_python_lint.rules.require_exp_on_jwt_decode import RequireExpOnJwtDecode
 from sarj_python_lint.rules.store_field_update_reuses_upsert import StoreFieldUpdateReusesUpsert
 from sarj_python_lint.rules.test_without_explicit_oracle import NoExplicitTestOracle
 
@@ -239,6 +249,16 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferBulkUpsert.id: PreferBulkUpsert,
         PreferPsycopgExecutemany.id: PreferPsycopgExecutemany,
         StoreFieldUpdateReusesUpsert.id: StoreFieldUpdateReusesUpsert,
+        DeleteRouteReturnsNoContent.id: DeleteRouteReturnsNoContent,
+        NoExceptionTextIn500Detail.id: NoExceptionTextIn500Detail,
+        RequireExpOnJwtDecode.id: RequireExpOnJwtDecode,
+        NoSlashCollectionRootUnderPrefix.id: NoSlashCollectionRootUnderPrefix,
+        NoWorkVerbGetRoute.id: NoWorkVerbGetRoute,
+        NoCreateVerbInPostPath.id: NoCreateVerbInPostPath,
+        NoHasattr.id: NoHasattr,
+        NoFoldedBadRequestNotFound.id: NoFoldedBadRequestNotFound,
+        NoDefaultedEnvironmentSetting.id: NoDefaultedEnvironmentSetting,
+        NoDuplicateFieldValidatorBody.id: NoDuplicateFieldValidatorBody,
         NoExplicitTestOracle.id: NoExplicitTestOracle,
         PreferDiscriminatedModelUnion.id: PreferDiscriminatedModelUnion,
         NoInvalidPydanticBypass.id: NoInvalidPydanticBypass,

sarj_python_lint-1.63.0/src/sarj_python_lint/rules/_route_shapes.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from http import HTTPStatus
+import re
+from typing import TYPE_CHECKING, Final
+
+from sarj_python_lint.rules._paths import is_test_path
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_STATUS_OWNERS: Final = frozenset({"HTTPStatus", "status"})
+_STARLETTE_STATUS: Final = re.compile(r"HTTP_(?P<code>[1-5][0-9]{2})_[A-Z_]+")
+_SEGMENT_WORD: Final = re.compile(r"[-_.]")
+
+
+@dataclass(frozen=True, slots=True)
+class RouteDecorator:
+    decorator: ast.Call
+    methods: frozenset[str]
+    path: str | None
+    prefix: ast.expr | None
+
+
+def route_decorators(context: PythonFileContext) -> Iterator[RouteDecorator]:
+    if context.tree is None or context.generated or is_test_path(context.path):
+        return
+    if "APIRouter" not in context.symbol_source and "FastAPI" not in context.symbol_source:
+        return
+    index = context.fastapi
+    for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
+        grouped: dict[int, list[str]] = {}
+        first: dict[int, RouteDecorator] = {}
+        for route in index.routes(function):
+            if route.has_unpack:
+                continue
+            grouped.setdefault(id(route.decorator), []).append(route.method)
+            first.setdefault(
+                id(route.decorator), RouteDecorator(route.decorator, frozenset(), route.path, route.inherited_prefix)
+            )
+        for key, methods in grouped.items():
+            shape = first[key]
+            yield RouteDecorator(shape.decorator, frozenset(methods), shape.path, shape.prefix)
+
+
+def final_segment_word(path: str) -> str | None:
+    segment = path.rstrip("/").rsplit("/", 1)[-1]
+    if not segment or segment.startswith("{"):
+        return None
+    return _SEGMENT_WORD.split(segment.lower(), maxsplit=1)[0]
+
+
+def final_segment_words(path: str) -> list[str]:
+    segment = path.rstrip("/").rsplit("/", 1)[-1]
+    if not segment or segment.startswith("{"):
+        return []
+    return [word for word in _SEGMENT_WORD.split(segment.lower()) if word]
+
+
+def http_status(node: ast.expr | None) -> int | None:
+    match node:
+        case ast.Constant(value=int() as value) if not isinstance(value, bool):
+            return value
+        case ast.Attribute(value=ast.Name(id=owner), attr=name) if owner in _STATUS_OWNERS:
+            if (match := _STARLETTE_STATUS.fullmatch(name)) is not None:
+                return int(match.group("code"))
+            member = HTTPStatus.__members__.get(name)
+            return None if member is None else member.value
+        case _:
+            return None

sarj_python_lint-1.63.0/src/sarj_python_lint/rules/delete_route_returns_no_content.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, Final, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+)
+from sarj_python_lint.rules._route_shapes import RouteDecorator, http_status, route_decorators
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_NO_CONTENT: Final = 204
+_MESSAGE = "DELETE route does not declare status_code=204; return no body and declare the 204 No Content status."
+
+
+@final
+class DeleteRouteReturnsNoContent(Rule):
+    id = "delete-route-returns-no-content"
+    code = "SARJ506"
+    documentation = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="FastAPI DELETE routes declare status code 204 No Content.",
+        rationale=(
+            "Without an explicit 204, FastAPI answers a DELETE with 200 and a JSON null body. Generated clients then "
+            "type the result as nullable data, and API routes disagree on what a successful removal returns."
+        ),
+        remediation="Declare `status_code=204` (or `status.HTTP_204_NO_CONTENT`) on the DELETE route and return None.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only DELETE-only decorators on a FastAPI or APIRouter receiver created in the same file are checked.",
+            (
+                "A status written as an integer, a Starlette `status.HTTP_*` name or an `HTTPStatus` member is resolved; "
+                "any other status expression and decorators with `**` keyword unpacking are accepted."
+            ),
+            "Tests and generated files are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="implicit-200",
+                title="A DELETE route answers 200 with a null body",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "api.py",
+                        "from fastapi import APIRouter\n\nrouter = APIRouter()\n\n"
+                        "@router.delete('/keys/{key_id}')\nasync def revoke(key_id: str) -> None:\n    return None\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("api.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="no-content",
+                title="A DELETE route declares 204",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "api.py",
+                        "from fastapi import APIRouter, status\n\nrouter = APIRouter()\n\n"
+                        "@router.delete('/keys/{key_id}', status_code=status.HTTP_204_NO_CONTENT)\n"
+                        "async def revoke(key_id: str) -> None:\n    return None\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("api.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        return [
+            Diagnostic(
+                context.path,
+                route.decorator.lineno,
+                route.decorator.col_offset + 1,
+                self.code,
+                _MESSAGE,
+                severity=Severity.WARNING,
+            )
+            for route in route_decorators(context)
+            if route.methods == {"delete"} and _lacks_no_content(route) and not _declares_body(route, context.parents)
+        ]
+
+
+def _declares_body(route: RouteDecorator, parents: Mapping[ast.AST, ast.AST]) -> bool:
+    model = next((keyword.value for keyword in route.decorator.keywords if keyword.arg == "response_model"), None)
+    if model is not None and not (isinstance(model, ast.Constant) and model.value is None):
+        return True
+    function = parents.get(route.decorator)
+    if not isinstance(function, (ast.FunctionDef, ast.AsyncFunctionDef)) or function.returns is None:
+        return False
+    return not (isinstance(function.returns, ast.Constant) and function.returns.value is None)
+
+
+def _lacks_no_content(route: RouteDecorator) -> bool:
+    status = next((keyword.value for keyword in route.decorator.keywords if keyword.arg == "status_code"), None)
+    if status is None:
+        return True
+    resolved = http_status(status)
+    return resolved is not None and resolved != _NO_CONTENT

sarj_python_lint-1.63.0/src/sarj_python_lint/rules/no_create_verb_in_post_path.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, Final, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+)
+from sarj_python_lint.rules._route_shapes import final_segment_words, route_decorators
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_CREATE_WORDS: Final = frozenset({"create", "add", "new"})
+_MESSAGE = (
+    "POST already means create; name the collection (POST /tickets) instead of a create, add or new segment, "
+    "and use PUT for an upsert."
+)
+
+
+@final
+class NoCreateVerbInPostPath(Rule):
+    id = "no-create-verb-in-post-path"
+    code = "SARJ500"
+    documentation = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="POST routes name their collection instead of ending in a create, add or new segment.",
+        rationale=(
+            "The HTTP method already states the action. A trailing create, add or new segment turns a resource API "
+            "into ad hoc RPC names, so clients cannot predict paths and PUT, PATCH and DELETE lose their pairing."
+        ),
+        remediation="POST to the collection path, use PUT on the item path for an upsert and PATCH for a partial update.",
+        category=RuleCategory.ARCHITECTURE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only literal route paths on a FastAPI or APIRouter receiver created in the same file are checked.",
+            "The final path segment is read; its first word (split on '-', '_' or '.') must be create, add or new.",
+            "A final path parameter is accepted, and tests and generated files are excluded.",
+            "Deliberate RPC-style integration endpoints exist; keep them with an exact suppression and its reason.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="create-segment",
+                title="A POST route repeats the verb in its path",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "api.py",
+                        "from fastapi import APIRouter\n\nrouter = APIRouter()\n\n"
+                        "@router.post('/tickets/create')\nasync def create_ticket() -> None:\n    return None\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("api.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="collection-path",
+                title="A POST route names its collection",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "api.py",
+                        "from fastapi import APIRouter\n\nrouter = APIRouter()\n\n"
+                        "@router.post('/tickets')\nasync def create_ticket() -> None:\n    return None\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("api.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        return [
+            Diagnostic(
+                context.path,
+                route.decorator.lineno,
+                route.decorator.col_offset + 1,
+                self.code,
+                _MESSAGE,
+                severity=Severity.WARNING,
+            )
+            for route in route_decorators(context)
+            if "post" in route.methods
+            and route.path is not None
+            and _is_create_segment(final_segment_words(route.path))
+        ]
+
+
+def _is_create_segment(words: list[str]) -> bool:
+    if not words or words[0] not in _CREATE_WORDS:
+        return False
+    if words[0] == "new":
+        return len(words) == 1
+    return words[:2] != ["add", "ons"]

sarj_python_lint-1.63.0/src/sarj_python_lint/rules/no_defaulted_environment_setting.py

@@ -0,0 +1,159 @@
+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,
+    Severity,
+)
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_SETTINGS_SOURCES = frozenset({"pydantic_settings", "pydantic_settings.main"})
+_FIELD_SOURCES = frozenset({"pydantic", "pydantic.fields"})
+_ENVIRONMENT = "environment"
+_ALIAS_KEYWORDS = frozenset({"alias", "validation_alias"})
+_DEFAULT_KEYWORDS = frozenset({"default", "default_factory"})
+
+
+@final
+class NoDefaultedEnvironmentSetting(Rule):
+    id = "no-defaulted-environment-setting"
+    code = "SARJ497"
+    documentation = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="A settings field that names the deployment environment must not declare a default.",
+        rationale=(
+            "A defaulted environment setting lets a deployment that forgot the variable start as the default "
+            "environment, so it quietly behaves like local or development code and can share state with another stack."
+        ),
+        remediation=(
+            'Declare the field without a default, for example `environment: Environment = Field(alias="ENVIRONMENT")`, '
+            "so a missing value fails at startup."
+        ),
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only classes deriving from pydantic-settings BaseSettings directly or through a class in the same file are checked.",
+            "A field qualifies when its name or literal alias is `environment` in any letter case.",
+            "Other environment-isolating settings, such as resource-name prefixes, have no stable name and are not checked.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="defaulted-environment",
+                title="A defaulted environment pretends to be local",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "service/settings.py",
+                        "from pydantic import Field\nfrom pydantic_settings import BaseSettings\n\n"
+                        "class Settings(BaseSettings):\n"
+                        "    environment: str = Field(default='local', alias='ENVIRONMENT')\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("service/settings.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="required-environment",
+                title="A required environment fails at startup when missing",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "service/settings.py",
+                        "from pydantic import Field\nfrom pydantic_settings import BaseSettings\n\n"
+                        "class Settings(BaseSettings):\n"
+                        "    environment: str = Field(alias='ENVIRONMENT')\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("service/settings.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        tree = context.tree
+        if tree is None or context.generated or "BaseSettings" not in context.symbol_source:
+            return []
+        imports = context.imports
+        settings_classes: set[str] = set()
+        diagnostics: list[Diagnostic] = []
+        for model in tree.body:
+            if not isinstance(model, ast.ClassDef) or not _is_settings_class(model, settings_classes, imports):
+                continue
+            settings_classes.add(model.name)
+            diagnostics.extend(
+                Diagnostic(
+                    context.path,
+                    field.lineno,
+                    field.col_offset + 1,
+                    self.code,
+                    "This environment setting has a default, so a deployment missing the variable starts as that "
+                    "environment. Remove the default so startup fails instead.",
+                    severity=Severity.WARNING,
+                )
+                for field in model.body
+                if isinstance(field, ast.AnnAssign) and _is_defaulted_environment(field, imports)
+            )
+        return diagnostics
+
+
+def _is_settings_class(model: ast.ClassDef, known: set[str], imports: ImportIndex) -> bool:
+    return any(
+        (isinstance(base, ast.Name) and base.id in known)
+        or imports.resolves(base, sources=_SETTINGS_SOURCES, symbol="BaseSettings")
+        for base in model.bases
+    )
+
+
+def _is_defaulted_environment(field: ast.AnnAssign, imports: ImportIndex) -> bool:
+    if not isinstance(field.target, ast.Name) or field.value is None or _is_none_default(field):
+        return False
+    value = field.value
+    if not (isinstance(value, ast.Call) and imports.resolves(value.func, sources=_FIELD_SOURCES, symbol="Field")):
+        return _is_environment_name(field.target.id, None)
+    alias = next(
+        (
+            keyword.value.value
+            for keyword in value.keywords
+            if keyword.arg in _ALIAS_KEYWORDS
+            and isinstance(keyword.value, ast.Constant)
+            and isinstance(keyword.value.value, str)
+        ),
+        None,
+    )
+    if not _is_environment_name(field.target.id, alias):
+        return False
+    positional_default = bool(value.args) and not (
+        isinstance(value.args[0], ast.Constant) and value.args[0].value is Ellipsis
+    )
+    return positional_default or any(keyword.arg in _DEFAULT_KEYWORDS for keyword in value.keywords)
+
+
+def _is_environment_name(name: str, alias: str | None) -> bool:
+    return name.lower() == _ENVIRONMENT or (alias is not None and alias.lower() == _ENVIRONMENT)
+
+
+def _is_none_default(field: ast.AnnAssign) -> bool:
+    value = field.value
+    if isinstance(value, ast.Call):
+        value = next((kw.value for kw in value.keywords if kw.arg == "default"), value.args[0] if value.args else None)
+    return isinstance(value, ast.Constant) and value.value is None