sarj-python-lint 1.88.1__tar.gz → 1.88.20__tar.gz

{sarj_python_lint-1.88.1 → sarj_python_lint-1.88.20}/PKG-INFO

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

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

{sarj_python_lint-1.88.1 → sarj_python_lint-1.88.20}/src/sarj_python_lint/rules/_fastapi.py

@@ -3,6 +3,10 @@ from __future__ import annotations
 import ast
 from collections import Counter
 from dataclasses import dataclass
+from functools import cached_property
+from http import HTTPStatus
+import re
+from types import MappingProxyType
 from typing import TYPE_CHECKING, Literal, NamedTuple
 
 from sarj_python_lint._source import read_python_source
@@ -19,19 +23,24 @@ HTTP_METHODS = frozenset({"get", "post", "put", "patch", "delete", "options", "h
 PARAM_MARKERS = frozenset({"Path", "Query", "Header", "Cookie", "Body", "Form", "File", "Depends", "Security"})
 SCHEMA_MARKERS = PARAM_MARKERS - {"Depends", "Security"}
 INJECTION_TYPES = frozenset({"Request", "Response", "WebSocket", "HTTPConnection", "BackgroundTasks", "SecurityScopes"})
-RESPONSE_TYPES = frozenset(
+_RESPONSE_DEFAULT_STATUSES = MappingProxyType(
     {
-        "Response",
-        "JSONResponse",
-        "HTMLResponse",
-        "PlainTextResponse",
-        "RedirectResponse",
-        "StreamingResponse",
-        "FileResponse",
-        "ORJSONResponse",
-        "UJSONResponse",
+        "Response": HTTPStatus.OK,
+        "JSONResponse": HTTPStatus.OK,
+        "HTMLResponse": HTTPStatus.OK,
+        "PlainTextResponse": HTTPStatus.OK,
+        "RedirectResponse": HTTPStatus.TEMPORARY_REDIRECT,
+        "StreamingResponse": HTTPStatus.OK,
+        "FileResponse": HTTPStatus.OK,
+        "ORJSONResponse": HTTPStatus.OK,
+        "UJSONResponse": HTTPStatus.OK,
     }
 )
+RESPONSE_TYPES = frozenset(_RESPONSE_DEFAULT_STATUSES)
+_STARLETTE_RESPONSE_TYPES = RESPONSE_TYPES - {"ORJSONResponse", "UJSONResponse"}
+_JSON_RESPONSE_TYPES = frozenset({"JSONResponse", "ORJSONResponse", "UJSONResponse"})
+NO_BODY_STATUSES = frozenset({204, 205, 304})
+_STATUS_MEMBER = re.compile(r"HTTP_(\d{3})_[A-Z0-9_]+")
 _DEPENDENCY_MARKERS = frozenset({"Depends", "Security"})
 _CONSTRUCTOR_SOURCES = frozenset({"fastapi", "fastapi.applications", "fastapi.routing"})
 _MAX_IMPORTED_MODULE_BYTES = 500_000
@@ -50,6 +59,7 @@ class Route:
     inherited_responses: ast.expr | None = None
     inherited_response_class: ast.expr | None = None
     inherited_prefix: ast.expr | None = None
+    inherited_has_unpack: bool = False
 
     @property
     def keywords(self) -> dict[str, ast.expr]:
@@ -154,6 +164,7 @@ class FastapiIndex:
         self.receiver_kinds: dict[_ReceiverKey, Literal["FastAPI", "APIRouter"]] = {}
         self.hidden_receivers: set[_ReceiverKey] = set()
         self.receiver_defaults: dict[_ReceiverKey, dict[str, ast.expr]] = {}
+        self.unpacked_receivers: set[_ReceiverKey] = set()
         self.decorators: dict[_ReceiverKey, _DecoratorBinding] = {}
         self.bound_names: set[_ReceiverKey] = set()
         self._node_scopes: dict[int, int] = {}
@@ -394,6 +405,8 @@ class FastapiIndex:
                 for keyword in value.keywords
                 if keyword.arg in {"responses", "default_response_class", "prefix"}
             }
+            if any(keyword.arg is None for keyword in value.keywords):
+                self.unpacked_receivers.add(key)
         if self._constructor_is_hidden(value):
             self.hidden_receivers.add(key)
 
@@ -497,6 +510,7 @@ class FastapiIndex:
                 inherited_responses=defaults.get("responses"),
                 inherited_response_class=defaults.get("default_response_class"),
                 inherited_prefix=defaults.get("prefix"),
+                inherited_has_unpack=origin in self.unpacked_receivers,
             )
             for route_method in route_methods
         )
@@ -541,6 +555,167 @@ class FastapiIndex:
             case _:
                 return ""
 
+    def status_code(self, node: ast.expr | None) -> int | None:
+        if isinstance(node, ast.Constant) and isinstance(node.value, int):
+            return node.value
+        if not isinstance(node, (ast.Name, ast.Attribute)) or self._is_shadowed_in_enclosing_scope(node):
+            return None
+        qualified = self.imports.resolved_qualified_name(node) or ""
+        module, _, member = qualified.rpartition(".")
+        if (
+            module == "starlette.status"
+            and module not in self._unstable_native_providers
+            and (match := _STATUS_MEMBER.fullmatch(member))
+        ):
+            return int(match.group(1))
+        if not isinstance(node, ast.Attribute):
+            return None
+        owner = self._status_provider(node.value)
+        if owner in self._unstable_native_providers:
+            return None
+        if owner == "starlette.status" and (match := _STATUS_MEMBER.fullmatch(node.attr)):
+            return int(match.group(1))
+        if owner == "http.HTTPStatus":
+            status = HTTPStatus.__members__.get(node.attr)
+            return status.value if status is not None else None
+        return None
+
+    def operation_status_code(self, route: Route) -> int | None:
+        node = route.keywords.get("status_code")
+        if node is None and route.has_unpack:
+            return None
+        if node is None or (isinstance(node, ast.Constant) and node.value is None):
+            if not self.response_classes_are_stable:
+                return None
+            if route.has_unpack and "response_class" not in route.keywords:
+                return None
+            response_class = route.keywords.get("response_class") or route.inherited_response_class
+            if response_class is None:
+                return None if route.inherited_has_unpack else HTTPStatus.OK
+            response_name = self.response_class_name(response_class)
+            return _RESPONSE_DEFAULT_STATUSES.get(response_name) if response_name is not None else None
+        return self.status_code(node)
+
+    def response_class_name(self, node: ast.expr) -> str | None:
+        if not self.response_classes_are_stable:
+            return None
+        return self._native_response_name(self._response_import(node))
+
+    def can_infer_json_response(self, route: Route) -> bool:
+        if route.has_unpack:
+            return False
+        status = self.operation_status_code(route)
+        if status is None or status in NO_BODY_STATUSES:
+            return False
+        response_class = route.keywords.get("response_class") or route.inherited_response_class
+        if response_class is None:
+            return not route.inherited_has_unpack and self.response_classes_are_stable
+        return self.response_class_name(response_class) in _JSON_RESPONSE_TYPES
+
+    @property
+    def response_classes_are_stable(self) -> bool:
+        return "responses" not in self._unstable_native_providers
+
+    @staticmethod
+    def _native_response_name(qualified: str | None) -> str | None:
+        if qualified is None:
+            return None
+        module, _, name = qualified.rpartition(".")
+        if module == "fastapi" and name == "Response":
+            return name
+        if module == "fastapi.responses" and name in RESPONSE_TYPES:
+            return name
+        if module == "starlette.responses" and name in _STARLETTE_RESPONSE_TYPES:
+            return name
+        return None
+
+    def _response_import(self, node: ast.expr) -> str | None:
+        if not isinstance(node, (ast.Name, ast.Attribute)) or self._is_shadowed_in_enclosing_scope(node):
+            return None
+        qualified = self.imports.resolved_qualified_name(node)
+        if isinstance(node, ast.Name) and qualified is None:
+            binding = self.imports.bindings.get(node.id)
+            return binding.module if binding is not None and binding.symbol is None else None
+        if isinstance(node, ast.Attribute) and qualified is None:
+            module = self.imports.resolved_qualified_name(node.value)
+            return f"{module}.{node.attr}" if module is not None else None
+        return qualified
+
+    def _status_provider(self, node: ast.expr) -> str | None:
+        if not isinstance(node, (ast.Name, ast.Attribute)) or self._is_shadowed_in_enclosing_scope(node):
+            return None
+        qualified = self.imports.resolved_qualified_name(node)
+        if isinstance(node, ast.Name) and qualified is None:
+            binding = self.imports.bindings.get(node.id)
+            qualified = (
+                binding.module
+                if binding is not None and binding.symbol is None and binding.module != "fastapi.status"
+                else None
+            )
+        # FastAPI exports Starlette's status module rather than a status submodule.
+        if qualified == "fastapi.status":
+            return "starlette.status"
+        return qualified if qualified in {"starlette.status", "http.HTTPStatus"} else None
+
+    @cached_property
+    def _unstable_native_providers(self) -> frozenset[str]:
+        providers: set[str] = set()
+        route_calls: set[int] = set()
+        for node in walk_ast(self.tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                route_calls.update(id(route.decorator) for route in self.routes(node))
+                continue
+            values = self._provider_values(node)
+            if not values:
+                continue
+            for value in values:
+                if (provider := self._status_provider(value)) is not None:
+                    providers.add(provider)
+            for value in self._response_provider_values(node, values, route_calls):
+                qualified = self._response_import(value)
+                if qualified in {"fastapi.responses", "starlette.responses"} or self._native_response_name(qualified):
+                    providers.add("responses")
+        return frozenset(providers)
+
+    @staticmethod
+    def _provider_values(node: ast.AST) -> tuple[ast.expr, ...]:
+        match node:
+            case ast.Attribute(value=value, ctx=ast.Store() | ast.Del()):
+                return node, value
+            case ast.Assign(value=value) | ast.AnnAssign(value=ast.expr() as value) | ast.NamedExpr(value=value):
+                return (value,)
+            case ast.Return(value=ast.expr() as value):
+                return (value,)
+            case ast.Call(args=args, keywords=keywords):
+                return (*args, *(keyword.value for keyword in keywords))
+            case _:
+                return ()
+
+    def _response_provider_values(
+        self, node: ast.AST, values: tuple[ast.expr, ...], route_calls: set[int]
+    ) -> tuple[ast.expr, ...]:
+        if not isinstance(node, ast.Call):
+            return values
+        trusted_keyword = self._trusted_response_keyword(node, route_calls)
+        return (*node.args, *(keyword.value for keyword in node.keywords if keyword.arg != trusted_keyword))
+
+    def _trusted_response_keyword(self, node: ast.Call, route_calls: set[int]) -> str | None:
+        trusted_keyword = "response_class" if id(node) in route_calls else None
+        if (
+            any(keyword.arg == "default_response_class" for keyword in node.keywords)
+            and self.constructor_kind(node) is not None
+        ):
+            return "default_response_class"
+        if not isinstance(node.func, ast.Attribute) or node.func.attr not in {"include_router", "add_api_route"}:
+            return trusted_keyword
+        scope = self._node_scopes.get(id(node), 0)
+        receiver = _binding_name(node.func.value)
+        if receiver.startswith("self."):
+            scope = self._node_classes.get(id(node)) or scope
+        if self._receiver_key(scope, receiver) is None:
+            return trusted_keyword
+        return "default_response_class" if node.func.attr == "include_router" else "response_class"
+
     @staticmethod
     def _root_name(node: ast.Attribute) -> str:
         value: ast.expr = node

{sarj_python_lint-1.88.1 → sarj_python_lint-1.88.20}/src/sarj_python_lint/rules/fastapi_class_router_contract.py

@@ -27,7 +27,6 @@ if TYPE_CHECKING:
     from sarj_python_lint.rules._ast_index import NodeIndex
 
 
-_NO_BODY = frozenset({204, 304})
 _NON_JSON_RESPONSES = frozenset(
     {"FileResponse", "HTMLResponse", "PlainTextResponse", "RedirectResponse", "StreamingResponse"}
 )
@@ -56,7 +55,9 @@ class FastapiClassRouterContract(Rule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Tests, generated code, and hidden routes are excluded. FastAPI application construction and include_router composition are allowed.",
-            "Response-model checks exclude 204/304 responses and explicit stream/file/HTML/text/redirect responses.",
+            "Response-model checks exclude literal or import-proven 204/205/304 statuses and proven non-JSON response classes, including raw Response.",
+            "Unpacked metadata or an explicit unresolved status cannot prove a JSON response; receiver ownership remains checked while response-model inference abstains.",
+            "Response classes require unshadowed native import provenance; direct provider writes/escapes, custom classes, and unresolved defaults disable JSON-model inference.",
         ),
         examples=(
             RuleExample(
@@ -211,12 +212,11 @@ def _response_problem(
     function: ast.FunctionDef | ast.AsyncFunctionDef, route: Route, index: FastapiIndex
 ) -> str | None:
     keywords = route.keywords
-    status = keywords.get("status_code")
-    if isinstance(status, ast.Constant) and status.value in _NO_BODY:
-        return None
     response_class = keywords.get("response_class") or route.inherited_response_class
     if response_class is not None and flat_name(response_class) in _NON_JSON_RESPONSES:
         return None
+    if not index.can_infer_json_response(route):
+        return None
     response_model = keywords.get("response_model")
     if response_model is None or (isinstance(response_model, ast.Constant) and response_model.value is None):
         return "JSON operation requires explicit `response_model=NamedResponse`"

{sarj_python_lint-1.88.1 → sarj_python_lint-1.88.20}/src/sarj_python_lint/rules/fastapi_explicit_openapi_contract.py

@@ -20,6 +20,7 @@ from sarj_python_lint.rule_base import (
 )
 from sarj_python_lint.rules._ast_index import children
 from sarj_python_lint.rules._fastapi import (
+    NO_BODY_STATUSES,
     SCHEMA_MARKERS,
     FastapiIndex,
     Route,
@@ -89,6 +90,9 @@ class FastapiExplicitOpenapiContract(Rule):
         limitations=(
             "Hidden routes, WebSocket handlers, tests, generated files, documentation-source examples, and unrelated decorators are excluded.",
             "Dynamic response mappings are accepted when their contents cannot be resolved statically.",
+            "Response-body/model inference abstains for unresolved status/class metadata, direct native-provider writes/escapes, and opaque unpacked defaults; no-body JSON metadata includes 205.",
+            "Direct-status alias/callee/catch recognition retains its existing limits; broader coverage requires separate reachability and runtime-dispatch evidence.",
+            "Route conflicts require unconditional registrations on the same local router; conditional composition requires trusted route/schema validation.",
             "Operation ID conflicts require unconditional registrations with literal IDs and paths on the same local router; conditional registrations, dynamic IDs, OpenAPI overrides, and cross-router composition require generated-schema validation.",
             "Explicit status and parameter-location findings are organizational policy even when FastAPI inference would generate valid OpenAPI.",
             (
@@ -268,7 +272,7 @@ class FastapiExplicitOpenapiContract(Rule):
                 findings.extend(_check_metadata(route, index))
                 findings.extend(_check_projection(route))
                 findings.extend(_check_response_statuses(route, index))
-        findings.extend(_check_route_conflicts(declared))
+        findings.extend(_check_route_conflicts(declared, context.parents))
         findings.extend(_check_operation_ids(declared, context.parents))
         return [
             Diagnostic(
@@ -548,7 +552,9 @@ def _check_inferred_return(
     if not builds_fixed_record(function, imports=index.imports):
         return []
     for route in _operations(routes):
-        if route.has_unpack:
+        if route.inherited_has_unpack and route.inherited_responses is None:
+            continue
+        if not index.can_infer_json_response(route):
             continue
         response_model = route.keywords.get("response_model")
         status = _status_code(route.keywords.get("status_code"), index) or HTTPStatus.OK
@@ -572,13 +578,22 @@ def _check_return_route(route: Route, contract: _ReturnContract, index: FastapiI
     if contract.erases_schema and not _concrete_response_model(response_model, index):
         problems.add("response annotation erases its OpenAPI schema; define an output model")
     status = _status_code(keywords.get("status_code"), index)
+    proven_status = index.operation_status_code(route)
+    body_status_is_known = proven_status is not None and proven_status not in NO_BODY_STATUSES
     response_class = keywords.get("response_class") or route.inherited_response_class
-    if contract.is_response and status not in _NO_CONTENT_STATUSES and response_class is None:
+    default_class_is_known = not route.inherited_has_unpack and index.response_classes_are_stable
+    if (
+        contract.is_response
+        and status not in _NO_CONTENT_STATUSES
+        and body_status_is_known
+        and response_class is None
+        and default_class_is_known
+    ):
         problems.add("direct Response return requires response_class= for accurate OpenAPI")
     _check_response_body(route, contract, index, problems)
     if response_model is not None and not response_model_none and _schema_erasing(response_model, index):
         problems.add("response_model erases its OpenAPI schema; define an output model")
-    if status in _NO_CONTENT_STATUSES:
+    if status in _NO_CONTENT_STATUSES and status == proven_status:
         if response_model is not None and not response_model_none:
             problems.add(f"status {status} must not declare a response model")
         if not (contract.is_none or contract.is_response):
@@ -589,19 +604,30 @@ def _check_response_body(route: Route, contract: _ReturnContract, index: Fastapi
     response_model = route.keywords.get("response_model")
     response_model_none = response_model is not None and _literal_none(response_model)
     status = _status_code(route.keywords.get("status_code"), index)
+    proven_status = index.operation_status_code(route)
     response_class = route.keywords.get("response_class") or route.inherited_response_class
     response_name = index.response_name(contract.annotation)
     class_name = index.response_name(response_class)
-    response_class_is_unresolved = response_class is not None and not class_name
+    proven_class_name = index.response_class_name(response_class) if response_class is not None else None
+    response_class_is_unresolved = (response_class is not None and (not class_name or proven_class_name is None)) or (
+        response_class is None and (route.inherited_has_unpack or not index.response_classes_are_stable)
+    )
     has_documented_body = (
         _concrete_response_model(response_model, index)
         or any(_documents_response_content(node, status, index) for node in _route_response_nodes(route))
         or class_name in _SELF_DOCUMENTING_RESPONSE_CLASSES
+        or proven_class_name in _SELF_DOCUMENTING_RESPONSE_CLASSES
         or response_class_is_unresolved
     )
-    if response_name not in {"", "Response"} and class_name and response_name != class_name:
+    if (
+        response_name not in {"", "Response"}
+        and class_name
+        and proven_class_name is not None
+        and response_name != class_name
+    ):
         problems.add(f"return type {response_name} conflicts with response_class={class_name}")
-    if contract.is_response and status not in _NO_CONTENT_STATUSES and not has_documented_body:
+    body_status_is_known = proven_status is not None and proven_status not in NO_BODY_STATUSES
+    if contract.is_response and status not in _NO_CONTENT_STATUSES and body_status_is_known and not has_documented_body:
         problems.add("direct Response return requires a concrete response_model or responses content schema")
     elif not contract.is_response and not contract.is_none and response_model_none:
         problems.add("response_model=None suppresses the declared response schema")
@@ -725,14 +751,7 @@ def _check_direct_responses(
     if not direct.statuses:
         return findings
     for route in _operations(routes):
-        responses = _route_response_nodes(route)
-        if any(not isinstance(node, ast.Dict) for node in responses):
-            continue
-        documented = {
-            status for node in responses if isinstance(node, ast.Dict) for status in _response_codes(node, index)
-        }
-        primary = _status_code(route.keywords.get("status_code"), index)
-        missing = sorted(direct.statuses - documented - ({primary} if primary is not None else set()))
+        missing = _undocumented_direct_statuses(route, direct.statuses, index)
         if missing:
             findings.append(
                 _Finding(
@@ -743,6 +762,23 @@ def _check_direct_responses(
     return findings
 
 
+def _undocumented_direct_statuses(route: Route, statuses: set[int], index: FastapiIndex) -> list[int]:
+    if route.has_unpack or (route.inherited_has_unpack and route.inherited_responses is None):
+        return []
+    proven_primary = index.operation_status_code(route)
+    if proven_primary is None:
+        return []
+    responses = _route_response_nodes(route)
+    if any(not isinstance(node, ast.Dict) for node in responses):
+        return []
+    documented = {status for node in responses if isinstance(node, ast.Dict) for status in _response_codes(node, index)}
+    primary = _status_code(route.keywords.get("status_code"), index)
+    primary_statuses = {proven_primary}
+    if primary is not None:
+        primary_statuses.add(primary)
+    return sorted(statuses - documented - primary_statuses)
+
+
 @dataclass(frozen=True, slots=True)
 class _DirectResponseStatuses:
     statuses: set[int]
@@ -794,13 +830,15 @@ def _direct_statuses(
     statuses: list[tuple[ast.Call, int]] = []
     call = current.exc if isinstance(current, ast.Raise) else None
     if isinstance(call, ast.Call) and index.is_http_exception(call.func) and not catches_http_exception:
-        status = _status_code(_keyword(call, "status_code") or (call.args[0] if call.args else None), index)
-        if status is not None:
+        status_node = _keyword(call, "status_code") or (call.args[0] if call.args else None)
+        status = _status_code(status_node, index)
+        if status is not None and index.status_code(status_node) == status:
             statuses.append((call, status))
     returned = current.value if isinstance(current, ast.Return) else None
     if isinstance(returned, ast.Call) and index.is_response(returned.func):
-        status = _status_code(_keyword(returned, "status_code"), index)
-        if status is not None:
+        status_node = _keyword(returned, "status_code")
+        status = _status_code(status_node, index)
+        if status is not None and index.status_code(status_node) == status:
             statuses.append((returned, status))
     return statuses
 
@@ -890,12 +928,12 @@ def _function_scopes(tree: ast.Module) -> dict[int, int]:
     return scopes
 
 
-def _check_route_conflicts(routes: list[tuple[int, Route]]) -> list[_Finding]:
+def _check_route_conflicts(routes: list[tuple[int, Route]], parents: Mapping[ast.AST, ast.AST]) -> list[_Finding]:
     findings: list[_Finding] = []
     seen: dict[tuple[int, str, str, str], Route] = {}
     dynamic: dict[tuple[int, str, str], list[tuple[Route, re.Pattern[str]]]] = {}
     for scope, route in sorted(routes, key=lambda item: item[1].decorator.lineno):
-        if route.path is None or route.method == "*":
+        if route.path is None or route.method == "*" or _conditional_registration(route.decorator, parents):
             continue
         key = scope, route.receiver, route.method, route.path
         if key in seen: