python-platform 0.1.1__py3-none-any.whl

python_platform/fastapi/http_router.py

@@ -0,0 +1,212 @@
+"""延迟编译 HTTP 声明；当前 Application 的最终服务图决定纯类型注入。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Mapping, Sequence
+from copy import copy
+from dataclasses import dataclass
+from functools import wraps
+from types import MappingProxyType
+from typing import Annotated, Any, get_args, get_origin, get_type_hints
+
+from dishka import AsyncContainer, FromComponent, Scope
+from dishka.integrations.base import default_parse_dependency
+from fastapi import APIRouter
+from fastapi.dependencies.models import Dependant
+from fastapi.dependencies.utils import add_non_field_param_to_dependency
+from fastapi.exceptions import FastAPIError
+from fastapi.params import Depends
+from pydantic.fields import FieldInfo
+from starlette.routing import compile_path
+
+from ..authorization import PermissionName
+from ..authorization.contracts import _authorization_requirement, _AuthorizationRequirement
+from ..invocation.callables import _dependency_key
+from ..unit_of_work.options import _declaration
+from .errors import FastApiAdapterError
+from .filters import ServiceFilter, _filters_for, _ordered_filters, _validate_filters
+from .manual_action import _action_route_type, _ActionDefinition, _ActionRoute, _wrap_action
+
+
+@dataclass(frozen=True, slots=True)
+class _HttpDeclaration:
+    path: str
+    endpoint: Callable[..., Any]
+    options: Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class _RouterInclusion:
+    router: APIRouter
+    options: Mapping[str, Any]
+
+
+class HttpRouter(APIRouter):
+    """沿用 FastAPI 路由声明 API；安装前只保存声明，不提前解析服务参数。"""
+
+    def __init__(
+        self,
+        *args: Any,
+        permissions: Sequence[PermissionName] | None = None,
+        filters: Sequence[ServiceFilter] = (),
+        **kwargs: Any,
+    ) -> None:
+        self._permissions = None if permissions is None else tuple(permissions)
+        self._filters = tuple(filters)
+        kwargs.setdefault("route_class", _ActionRoute)
+        super().__init__(*args, **kwargs)
+        self._compiled = False
+        self._declarations: list[_HttpDeclaration | _RouterInclusion] = []
+
+    def add_api_route(self, path: str, endpoint: Callable[..., Any], **kwargs: Any) -> None:
+        if self._compiled:
+            return super().add_api_route(path, endpoint, **kwargs)
+        self._declarations.append(_HttpDeclaration(path, endpoint, MappingProxyType(dict(kwargs))))
+
+    def include_router(self, router: APIRouter, **kwargs: Any) -> None:
+        if self._compiled:
+            return super().include_router(router, **kwargs)
+        self._declarations.append(_RouterInclusion(router, MappingProxyType(dict(kwargs))))
+
+    def _compile(
+        self,
+        container: AsyncContainer,
+        prefix: str = "",
+        inherited_permissions: tuple[PermissionName, ...] | None = None,
+        inherited_filters: tuple[ServiceFilter, ...] = (),
+    ) -> APIRouter:
+        # 复制原生 router 配置，避免重新维护 FastAPI 默认值/配置字段第二清单。
+        # 每个 Application 只修改自己的 routes 和 endpoint wrapper。
+        permissions = (
+            None
+            if self._permissions is None and inherited_permissions is None
+            else (*(inherited_permissions or ()), *(self._permissions or ()))
+        )
+        filters = (*inherited_filters, *self._filters)
+        compiled = copy(self)
+        compiled._compiled = True
+        compiled.route_class = _action_route_type(self.route_class)
+        compiled.routes = list(self.routes)
+        compiled._declarations = []
+        for declaration in tuple(self._declarations):
+            if isinstance(declaration, _RouterInclusion):
+                child = declaration.router
+                if isinstance(child, HttpRouter):
+                    child = child._compile(
+                        container,
+                        prefix + self.prefix + declaration.options.get("prefix", ""),
+                        permissions,
+                        filters,
+                    )
+                elif permissions is not None or filters:
+                    raise FastApiAdapterError(
+                        f"HttpRouter at {prefix + self.prefix or '/'} cannot apply inherited "
+                        f"permissions/filters to native {type(child).__qualname__} at "
+                        f"{child.prefix or '/'}; use a nested HttpRouter"
+                    )
+                APIRouter.include_router(compiled, child, **declaration.options)
+            else:
+                path = prefix + self.prefix + declaration.path
+                endpoint = _compile_endpoint(declaration.endpoint, path, container)
+                authorization = _authorization_requirement(object, declaration.endpoint)
+                if permissions is not None and not authorization.allows_anonymous:
+                    authorization = _AuthorizationRequirement(
+                        True,
+                        tuple(dict.fromkeys((*permissions, *authorization.permissions))),
+                        False,
+                    )
+                definition = _ActionDefinition(
+                    declaration.endpoint,
+                    authorization,
+                    _declaration(type(self), declaration.endpoint),
+                    _ordered_filters(filters, _filters_for(declaration.endpoint)),
+                )
+                _validate_filters(definition.filters, container)
+                endpoint = _wrap_action(endpoint, definition)
+                options = dict(declaration.options)
+                if options.get("route_class_override") is not None:
+                    options["route_class_override"] = _action_route_type(
+                        options["route_class_override"]
+                    )
+                try:
+                    APIRouter.add_api_route(
+                        compiled,
+                        declaration.path,
+                        endpoint,
+                        **options,
+                    )
+                except (TypeError, ValueError, FastAPIError) as error:
+                    raise FastApiAdapterError(
+                        f"{endpoint.__qualname__} at {path}: {error}"
+                    ) from error
+        return compiled
+
+
+def _compile_endpoint(
+    endpoint: Callable[..., Any],
+    path: str,
+    container: AsyncContainer,
+) -> Callable[..., Any]:
+    try:
+        hints = get_type_hints(endpoint, include_extras=True)
+        signature = inspect.signature(endpoint)
+        _, _, path_parameters = compile_path(path)
+        parameters = []
+        for parameter in signature.parameters.values():
+            hint = hints.get(parameter.name, parameter.annotation)
+            parameters.append(_compile_parameter(parameter, hint, path_parameters, container))
+    except (TypeError, NameError) as error:
+        raise FastApiAdapterError(f"{endpoint.__qualname__} at {path}: {error}") from error
+
+    if inspect.iscoroutinefunction(endpoint):
+
+        @wraps(endpoint)
+        async def target(*args: Any, **kwargs: Any) -> Any:
+            return await endpoint(*args, **kwargs)
+    else:
+
+        @wraps(endpoint)
+        def target(*args: Any, **kwargs: Any) -> Any:
+            return endpoint(*args, **kwargs)
+
+    target.__signature__ = signature.replace(  # type: ignore[attr-defined]
+        parameters=parameters,
+        return_annotation=hints.get("return", signature.return_annotation),
+    )
+    target.__annotations__ = {parameter.name: parameter.annotation for parameter in parameters}
+    if "return" in hints:
+        target.__annotations__["return"] = hints["return"]
+    return target
+
+
+def _compile_parameter(
+    parameter: inspect.Parameter,
+    hint: object,
+    path_parameters: Mapping[str, object],
+    container: AsyncContainer,
+    *,
+    infer_services: bool = True,
+) -> inspect.Parameter:
+    metadata = get_args(hint)[1:] if get_origin(hint) is Annotated else ()
+    hint_type = get_args(hint)[0] if metadata else hint
+    explicit_di = default_parse_dependency(parameter, hint)
+    http_bound = parameter.name in path_parameters or any(
+        isinstance(value, (FieldInfo, Depends)) for value in (*metadata, parameter.default)
+    )
+    # 特殊参数由 FastAPI 的版本匹配原生规则解释，不复制 Request/Response 等类型列表。
+    native_special = add_non_field_param_to_dependency(
+        param_name=parameter.name,
+        type_annotation=hint_type,
+        dependant=Dependant(),
+    )
+    if http_bound or native_special:
+        if explicit_di is not None:
+            raise TypeError(f"{parameter.name}: explicit HTTP source conflicts with FromComponent")
+        return parameter.replace(annotation=hint)
+    if not infer_services and explicit_di is None:
+        return parameter.replace(annotation=hint)
+    key = _dependency_key(parameter, hint, container, Scope.REQUEST)
+    if key is not None:
+        hint = Annotated[key.type_hint, FromComponent(key.component or "")]
+    return parameter.replace(annotation=hint)

python_platform/fastapi/manual_action.py

@@ -0,0 +1,105 @@
+"""手写 Action 的绑定后执行与绑定前策略，保留原生 FastAPI 依赖和线程池。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, cast
+
+from dishka.integrations.fastapi import DishkaRoute
+from fastapi.routing import APIRoute
+from starlette.concurrency import run_in_threadpool
+from starlette.requests import Request
+from starlette.responses import Response
+
+from ..application_services.dispatcher import _ApplicationServiceDispatcher
+from ..authorization.contracts import _AuthorizationRequirement
+from ..unit_of_work.options import UnitOfWorkDeclaration
+from .action import _HttpActionOwner, _request_parameter
+from .filters import ServiceFilter, _ordered_filters
+from .parameters import _HttpParameterValidator
+from .transfer import _manage_stream
+from .uploads import _prepare_upload
+
+_ACTION = "__python_platform_action_definition__"
+
+
+@dataclass(frozen=True, slots=True)
+class _ActionDefinition:
+    endpoint: Callable[..., Any]
+    authorization: _AuthorizationRequirement
+    work: UnitOfWorkDeclaration
+    filters: tuple[ServiceFilter, ...]
+
+
+class _ActionRoute(DishkaRoute):
+    def __init__(self, path: str, endpoint: Callable[..., Any], **kwargs: Any) -> None:
+        self._definition: _ActionDefinition = getattr(endpoint, _ACTION)
+        super().__init__(path, endpoint, **kwargs)
+        setattr(self.endpoint, _ACTION, self._definition)
+
+    def get_route_handler(self) -> Callable[[Request], Any]:
+        native = super().get_route_handler()
+        definition = self._definition
+
+        async def handle(request: Request) -> Response:
+            owner = await _HttpActionOwner.install(request)
+            try:
+                dispatcher = await owner.container.get(_ApplicationServiceDispatcher)
+                await dispatcher._authorize(definition.authorization)
+                await _prepare_upload(request, definition.endpoint, self)
+                result = await native(request)
+                _manage_stream(request, result)
+                owner.response_ready = True
+                return result
+            except BaseException as failure:
+                owner.failure = failure
+                raise
+
+        return handle
+
+
+def _wrap_action(endpoint: Callable[..., Any], definition: _ActionDefinition) -> Callable[..., Any]:
+    signature = inspect.signature(endpoint)
+    validator = _HttpParameterValidator(signature)
+    parameters = tuple(signature.parameters.values())
+    request_parameter, injected_request = _request_parameter(parameters)
+    request_name = request_parameter.name
+    if injected_request:
+        parameters += (request_parameter,)
+
+    @wraps(endpoint)
+    async def target(**values: Any) -> Any:
+        request = cast(
+            Request, values.pop(request_name) if injected_request else values[request_name]
+        )
+        owner: _HttpActionOwner = request.state.python_platform_action
+        await owner.activate(definition.work, definition.endpoint.__name__)
+        snapshots = validator.capture(values)
+
+        async def invoke(actual: dict[str, object]) -> object:
+            if filters:
+                validator.validate_changes(actual, snapshots)
+            if inspect.iscoroutinefunction(endpoint):
+                return await endpoint(**actual)
+            return await run_in_threadpool(endpoint, **actual)
+
+        filters = _ordered_filters(
+            getattr(request.app.state, "python_platform_filters", ()), definition.filters
+        )
+        return await owner.invoke(definition.endpoint, values, filters, invoke)
+
+    target.__signature__ = signature.replace(parameters=parameters)  # type: ignore[attr-defined]
+    target.__annotations__ = {p.name: p.annotation for p in parameters}
+    target.__annotations__["return"] = signature.return_annotation
+    setattr(target, _ACTION, definition)
+    return target
+
+
+def _action_route_type(native: type[APIRoute]) -> type[APIRoute]:
+    if issubclass(native, _ActionRoute):
+        return native
+    # 原生自定义 APIRoute 继续拥有它的 handler 扩展；平台只增加同一 Action 边界。
+    return type(f"Managed{native.__name__}", (_ActionRoute, native), {})

python_platform/fastapi/middleware.py

@@ -0,0 +1,93 @@
+"""Host 有序 middleware 声明编译；原生实例共享，DI 处理对象按请求解析。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from dishka import AsyncContainer, Scope
+from starlette.middleware import Middleware
+from starlette.requests import Request
+from starlette.types import ASGIApp, Receive, Send
+from starlette.types import Scope as AsgiScope
+
+from ..invocation.callables import _CallablePlan, _dependency_key
+from .errors import FastApiAdapterError
+from .request_context import _RequestTaskMiddleware
+
+
+@dataclass(frozen=True, slots=True)
+class DiMiddleware:
+    """原生 ASGI：async invoke(scope, receive, send, call_next, ...DI参数)。"""
+
+    handler: type | Callable[..., Awaitable[None]]
+
+
+class _DiMiddleware:
+    def __init__(self, app: ASGIApp, *, declaration: DiMiddleware, plan: _CallablePlan) -> None:
+        self._app = app
+        self._declaration = declaration
+        self._plan = plan
+
+    async def __call__(self, scope: AsgiScope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self._app(scope, receive, send)
+            return
+        # 不创建转发 task；REQUEST generator 与 ContextVar 在解析它们的 task 中退出。
+        container = Request(scope).state.dishka_container
+        handler = self._declaration.handler
+        if isinstance(handler, type):
+            instance = await container.get(handler)
+            handler = instance.invoke
+        await self._plan.invoke(handler, container, (scope, receive, send, self._app), {})
+
+
+class _NativeMiddleware:
+    def __init__(self, app: ASGIApp, *, middleware: Middleware) -> None:
+        cls, args, kwargs = middleware
+        # 每个下游入口检查前置短 UoW；BaseHTTPMiddleware 切 task 时也走同一入口。
+        self._app = _RequestTaskMiddleware(cls(_RequestTaskMiddleware(app), *args, **kwargs))
+
+    async def __call__(self, *args: Any) -> None:
+        await self._app(*args)
+
+
+def _compile_middlewares(
+    items: Sequence[Middleware | DiMiddleware], container: AsyncContainer
+) -> tuple[Middleware, ...]:
+    compiled: list[Middleware] = []
+    for item in items:
+        if isinstance(item, DiMiddleware):
+            handler = item.handler
+            if isinstance(handler, type):
+                parameter = inspect.Parameter("middleware", inspect.Parameter.KEYWORD_ONLY)
+                if _dependency_key(parameter, handler, container, Scope.REQUEST) is None:
+                    raise FastApiAdapterError("DI middleware type is not registered")
+                function = getattr(handler, "invoke", None)
+                if function is None:
+                    raise FastApiAdapterError("DI middleware requires async invoke")
+                unbound = _CallablePlan.compile(
+                    function, container, Scope.REQUEST, business_parameters=5
+                )
+                plan = _CallablePlan(
+                    unbound.signature.replace(
+                        parameters=tuple(unbound.signature.parameters.values())[1:]
+                    ),
+                    unbound.dependencies,
+                )
+            else:
+                plan = _CallablePlan.compile(
+                    handler, container, Scope.REQUEST, business_parameters=4
+                )
+            if len(plan.signature.parameters) != 4:
+                raise FastApiAdapterError(
+                    "DI middleware must accept scope, receive, send and call_next"
+                )
+            plan.signature.bind(None, None, None, None)
+            item = Middleware(_DiMiddleware, declaration=item, plan=plan)
+        elif not isinstance(item, Middleware):
+            raise FastApiAdapterError("Host middleware must be Middleware or DiMiddleware")
+        compiled.append(Middleware(_NativeMiddleware, middleware=item))
+    return tuple(compiled)

python_platform/fastapi/parameters.py

@@ -0,0 +1,97 @@
+"""HTTP Filter 改参后的验证边界；validator 由当前应用的路由编译结果拥有。"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Annotated, Any, cast, get_args, get_origin
+
+from dishka.integrations.base import default_parse_dependency
+from fastapi.dependencies.models import Dependant
+from fastapi.dependencies.utils import add_non_field_param_to_dependency
+from fastapi.exceptions import RequestValidationError
+from pydantic import ConfigDict, Field, TypeAdapter, ValidationError
+from pydantic.fields import FieldInfo
+from pydantic_core import CoreSchema, SchemaValidator
+
+from ..application_services.execution import _InvocationArguments
+
+
+def _revalidation_schema(value: Any) -> Any:
+    # 只复制 schema 的容器，不复制模型 class、validator 或默认业务对象。
+    # 显式覆盖每个嵌套模型/数据类，不能改变业务模型的全局配置。
+    if isinstance(value, dict):
+        result = {
+            key: item if key in ("default", "metadata", "config") else _revalidation_schema(item)
+            for key, item in value.items()
+        }
+        if result.get("type") in ("model", "dataclass"):
+            result["revalidate_instances"] = "always"
+        return result
+    if isinstance(value, list):
+        return [_revalidation_schema(item) for item in value]
+    return value
+
+
+class _HttpParameterValidator:
+    def __init__(self, signature: inspect.Signature) -> None:
+        self._signature = signature
+        self._validators: dict[str, SchemaValidator] = {}
+        for name, parameter in signature.parameters.items():
+            annotation = parameter.annotation
+            if isinstance(parameter.default, FieldInfo):
+                annotation = Annotated[annotation, parameter.default]
+            base = get_args(annotation)[0] if get_origin(annotation) is Annotated else annotation
+            if (
+                annotation is inspect.Parameter.empty
+                or default_parse_dependency(parameter, annotation) is not None
+                or add_non_field_param_to_dependency(
+                    param_name=name, type_annotation=base, dependant=Dependant()
+                )
+            ):
+                continue
+            if parameter.default is not inspect.Parameter.empty and not isinstance(
+                parameter.default, FieldInfo
+            ):
+                annotation = Annotated[annotation, Field(default=parameter.default)]
+            adapter = TypeAdapter(
+                tuple[annotation],  # type: ignore[valid-type]
+                config=ConfigDict(arbitrary_types_allowed=True),
+            )
+            self._validators[name] = SchemaValidator(
+                cast(CoreSchema, _revalidation_schema(adapter.core_schema)), _use_prebuilt=False
+            )
+
+    def capture(self, actual: dict[str, object]) -> dict[str, _InvocationArguments]:
+        # 只追踪 HTTP 可验证参数；Request/DI 对象不参与 DTO 的变更判断。
+        snapshots = {}
+        for name in self._validators:
+            if name in actual:
+                arguments = _InvocationArguments((actual[name],), {})
+                arguments.mark_validated()
+                arguments.exposed = True
+                snapshots[name] = arguments
+        return snapshots
+
+    def validate_changes(
+        self, actual: dict[str, object], snapshots: dict[str, _InvocationArguments]
+    ) -> None:
+        try:
+            self._signature.bind(**actual)
+        except TypeError:
+            raise RequestValidationError(
+                [{"loc": (), "msg": "Invalid action arguments", "type": "arguments"}]
+            ) from None
+        try:
+            for name, validator in self._validators.items():
+                values = (actual[name],) if name in actual else ()
+                previous = snapshots.get(name)
+                if previous is not None:
+                    if not values or previous.args[0] is not values[0]:
+                        previous.args = values
+                    if not previous.needs_validation:
+                        continue
+                # 独立参数各自重验；改动 scalar 不能重复执行未变 DTO 的非幂等 validator。
+                # 已绑定实例内部使用字段名；Filter 替换输入仍接受原 schema 的别名。
+                actual[name] = validator.validate_python(values, by_name=True)[0]
+        except ValidationError as error:
+            raise RequestValidationError(error.errors()) from None

python_platform/fastapi/realtime/__init__.py

@@ -0,0 +1,13 @@
+"""FastAPI-only managed WebSocket capability。"""
+
+from .authentication import websocket_connection
+from .connection import WebSocketConnection
+from .module import FastApiRealtimeModule
+from .options import FastApiRealtimeOptions
+
+__all__ = (
+    "FastApiRealtimeModule",
+    "FastApiRealtimeOptions",
+    "WebSocketConnection",
+    "websocket_connection",
+)