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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.61.1"
+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.63.0/src/sarj_python_lint/cast_access.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from sarj_python_lint._file_context import PythonFileContext
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_TYPING = frozenset({"typing", "typing_extensions"})
+_GETATTR_ARITIES = frozenset({2, 3})
+
+
+@dataclass(frozen=True, slots=True)
+class CastAccess:
+    node: ast.Call | ast.ImportFrom
+    qualified_api: str
+    kind: Literal["wildcard", "reflection"]
+
+
+def indirect_typing_cast_accesses(path: Path, source: str) -> tuple[CastAccess, ...]:
+    context = PythonFileContext(path, source)
+    if "*" not in source and "getattr" not in context.symbol_source:
+        return ()
+    if context.tree is None:
+        return ()
+    accesses = [
+        CastAccess(node, f"{node.module}.cast", "wildcard")
+        for node in context.nodes(ast.ImportFrom)
+        if node.level == 0 and node.module in _TYPING and any(alias.name == "*" for alias in node.names)
+    ]
+    provenance = ResourceProvenance(context, require_static_namespace=True)
+    if provenance.wildcard or provenance.dynamic_namespace or not provenance.builtin_namespace_untouched:
+        return tuple(accesses)
+    for call in context.nodes(ast.Call):
+        if not _getattr_call(call, provenance):
+            continue
+        module = _typing_receiver(call.args[0], provenance)
+        if module is not None:
+            accesses.append(CastAccess(call, f"{module}.cast", "reflection"))
+    return tuple(sorted(accesses, key=lambda access: (access.node.lineno, access.node.col_offset)))
+
+
+def _getattr_call(call: ast.Call, provenance: ResourceProvenance) -> bool:
+    if not (
+        isinstance(call.func, ast.Name)
+        and call.func.id == "getattr"
+        and len(call.args) in _GETATTR_ARITIES
+        and not call.keywords
+        and isinstance(call.args[1], ast.Constant)
+        and call.args[1].value == "cast"
+    ):
+        return False
+    scope = provenance.scope(call.func)
+    while scope is not None:
+        if "getattr" in provenance.bindings.get(scope, {}):
+            return False
+        scope = provenance.scope(scope)
+    return True
+
+
+def _typing_receiver(node: ast.expr, provenance: ResourceProvenance) -> str | None:
+    if not isinstance(node, ast.Name) or node.id in provenance.mutated | provenance.external_bindings:
+        return None
+    binding = provenance.binding(node.id, node)
+    if not (
+        isinstance(binding, ast.alias)
+        and isinstance(provenance.context.parents.get(binding), ast.Import)
+        and binding.name in _TYPING
+    ):
+        return None
+    for read in provenance.reads.get(node.id, ()):
+        if provenance.binding(read.id, read) is not binding:
+            continue
+        parent = provenance.context.parents.get(read)
+        if isinstance(parent, ast.Attribute) and parent.value is read:
+            continue
+        if isinstance(parent, ast.Call) and _getattr_call(parent, provenance) and parent.args[0] is read:
+            continue
+        return None
+    return binding.name

{sarj_python_lint-1.61.1 → 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.61.1 → sarj_python_lint-1.63.0}/src/sarj_python_lint/rules/_registry.py

@@ -44,6 +44,7 @@ from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
 from sarj_python_lint.rules.no_database_programmability import NoDatabaseProgrammability
 from sarj_python_lint.rules.no_delete_statement import NoDeleteStatement
 from sarj_python_lint.rules.no_discarded_validation_result import NoDiscardedValidationResult
+from sarj_python_lint.rules.no_dual_shape_model_field_reader import NoDualShapeModelFieldReader
 from sarj_python_lint.rules.no_dunder_all import NoDunderAll
 from sarj_python_lint.rules.no_duplicate_dunder_all_entry import NoDuplicateDunderAllEntry
 from sarj_python_lint.rules.no_excessive_cognitive_complexity import NoExcessiveCognitiveComplexity
@@ -214,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
 
@@ -238,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,
@@ -307,6 +328,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RequireKeywordOnlySwapProneParams.id: RequireKeywordOnlySwapProneParams,
         RequirePydanticForExternalJson.id: RequirePydanticForExternalJson,
         RequirePydanticForMappingShape.id: RequirePydanticForMappingShape,
+        NoDualShapeModelFieldReader.id: NoDualShapeModelFieldReader,
         PreferModuleLevelConstant.id: PreferModuleLevelConstant,
         PreferImmutableModuleConstant.id: PreferImmutableModuleConstant,
         PreferInjectedDependencyOverMonkeypatch.id: PreferInjectedDependencyOverMonkeypatch,

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.61.1 → sarj_python_lint-1.63.0}/src/sarj_python_lint/rules/duplicate_adjacent_exception_handler.py

@@ -3,10 +3,10 @@ from __future__ import annotations
 import ast
 import builtins
 from pathlib import PurePosixPath
+from types import MappingProxyType
 from typing import (
     TYPE_CHECKING,
     ClassVar,
-    cast,  # ruff: ignore[banned-api] -- vars exposes Any; the object view permits isinstance narrowing.
     final,
     override,
 )
@@ -31,14 +31,12 @@ from sarj_python_lint.rules._suppression_comments import scan_comments
 
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping
-
     from sarj_python_lint._file_context import PythonFileContext
     from sarj_python_lint.rules._project_index import SourceUnit, SymbolRef
     from sarj_python_lint.rules._suppression_comments import Comment
 
 
-_BUILTIN_NAMESPACE = cast("Mapping[str, object]", vars(builtins))
+_BUILTIN_NAMESPACE = MappingProxyType[str, object](vars(builtins))
 _BUILTIN_EXCEPTIONS = frozenset(
     name for name, value in _BUILTIN_NAMESPACE.items() if isinstance(value, type) and issubclass(value, Exception)
 )

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"]