fastapi-openrpc 0.1.3__py3-none-any.whl

fastapi_openrpc/decorator.py

@@ -0,0 +1,517 @@
+"""@method() decorator and type inference."""
+
+from __future__ import annotations
+
+import inspect
+import types
+import typing
+from collections.abc import Callable
+from typing import Annotated, Any, cast, get_args, get_origin, get_type_hints
+
+from fastapi_openrpc.registry import add
+from fastapi_openrpc.types import MethodMeta, Require, _is_rpc_context_param
+
+# ----------------------------------------------------------------------
+# Type Inference
+# ----------------------------------------------------------------------
+
+
+def _get_json_schema_type(python_type: type[Any] | None) -> str:
+    """Map Python type to JSON Schema type string."""
+    if python_type is None:
+        return "object"
+    # Check type aliases
+    type_name = getattr(python_type, "__name__", str(python_type))
+    if type_name in ("str", "String"):
+        return "string"
+    if type_name in ("int", "Integer", "int64", "int32"):
+        return "integer"
+    if type_name in ("float", "Float", "double", "Number"):
+        return "number"
+    if type_name in ("bool", "Boolean"):
+        return "boolean"
+    if type_name in ("list", "List", "tuple", "Tuple"):
+        return "array"
+    if type_name in ("dict", "Dict", "Mapping"):
+        return "object"
+    return "object"
+
+
+def _infer_param_schema(annotation: type[Any] | None) -> dict[str, Any]:
+    """Infer JSON Schema from a single parameter annotation.
+
+    - Pydantic BaseModel -> recursively use model_json_schema()
+    - Basic types -> direct mapping
+    - Optional[T] -> extract inner type
+    - List[T] / dict etc -> type: array / object
+    - No annotation -> {"type": "object"}
+    """
+    import typing
+
+    if annotation is None:
+        return {"type": "object"}
+
+    # Prefer typing.get_origin/get_args (Python 3.8+), overriding getattr version
+    # because get_origin correctly handles Optional[str] (__origin__=None but
+    # get_origin returns Union)
+    try:
+        origin = typing.get_origin(annotation)
+        args = typing.get_args(annotation)
+    except Exception:
+        origin = getattr(annotation, "__origin__", None)
+        args = getattr(annotation, "__args__", ())
+
+    # Optional[X] -> X (Union with None)
+    if origin is not None:
+        # typing.Optional / typing.Union[X, None]
+        none_type = type(None)
+        non_none = [a for a in args if a is not none_type]
+        if len(non_none) == 1 and none_type in args:
+            # Optional[T]
+            return _infer_param_schema(non_none[0])
+
+        # List[T] / tuple
+        if origin is list or origin is tuple:
+            if args:
+                return {
+                    "type": "array",
+                    "items": _infer_param_schema(args[0]),
+                }
+            return {"type": "array"}
+
+        # Dict[str, T]
+        if origin is dict:
+            if len(args) >= 2:
+                return {
+                    "type": "object",
+                    "additionalProperties": _infer_param_schema(args[1]),
+                }
+            return {"type": "object"}
+
+        # Set[T]
+        if origin is set:
+            if args:
+                return {
+                    "type": "array",
+                    "items": _infer_param_schema(args[0]),
+                    "uniqueItems": True,
+                }
+            return {"type": "array"}
+
+    # Pydantic V2 BaseModel -> expand fields to top-level properties
+    if _is_pydantic_model(annotation):
+        return _expand_pydantic_model_to_params(annotation)
+
+    # typing.NewType -> extract underlying type
+    if hasattr(annotation, "__supertype__"):
+        return _infer_param_schema(annotation.__supertype__)
+
+    return {"type": _get_json_schema_type(annotation)}
+
+
+def _is_pydantic_model(annotation: type[Any]) -> bool:
+    """Check if annotation is a Pydantic BaseModel subclass."""
+    # Avoid importing pydantic at module level (reduce import overhead)
+    try:
+        from pydantic import BaseModel
+
+        return isinstance(annotation, type) and issubclass(annotation, BaseModel)
+    except ImportError:
+        return False
+
+
+def _unwrap_union(annotation: type[Any]) -> type[Any] | None:
+    """Extract the first non-None type from a Union type (e.g., Optional[T], T | None)."""
+    try:
+        origin = typing.get_origin(annotation)
+        args = typing.get_args(annotation)
+    except (TypeError, AttributeError):
+        origin = getattr(annotation, "__origin__", None)
+        args = getattr(annotation, "__args__", ())
+
+    # Handle typing.Union (Optional[T]) and types.UnionType (T | None)
+    if origin is typing.Union or origin is types.UnionType:
+        for arg in args:
+            if arg is not type(None):
+                return cast(type[Any], arg)
+    return None
+
+
+def _expand_pydantic_model_to_params(model_cls: type) -> dict[str, Any]:
+    """Expand a Pydantic BaseModel's fields into an OpenRPC params SchemaObject.
+
+    When a Pydantic model is used to describe parameter structure (e.g., handler
+    parameter is GetSchemaRequest), each field corresponds to one OpenRPC parameter.
+
+    For example, GetSchemaRequest(qualified_name: str) generates:
+    {
+        "type": "object",
+        "properties": {"qualified_name": {"type": "string", "description": "..."}},
+        "required": ["qualified_name"]
+    }
+
+    This way the JSON-RPC request still uses a flat structure:
+    {"jsonrpc": "2.0", "method": "getSchema", "params": {"qualified_name": "..."}}
+    """
+    schema = _pydantic_model_schema(model_cls)
+    properties = schema.get("properties", {})
+
+    # Collect required fields (Pydantic model_json_schema omits top-level required;
+    # derive from fields)
+    model_required = schema.get("required", [])
+    if not model_required:
+        # Get required info via model_fields
+        try:
+            if hasattr(model_cls, "model_fields"):
+                model_required = [
+                    name
+                    for name, field_info in model_cls.model_fields.items()
+                    if field_info.is_required()
+                ]
+        except Exception:
+            pass
+
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": model_required,
+    }
+
+
+def _pydantic_model_schema(model_cls: type) -> dict[str, Any]:
+    """Generate JSON Schema using Pydantic V2 model_json_schema()."""
+    try:
+        from pydantic import BaseModel
+
+        if not issubclass(model_cls, BaseModel):
+            return {"type": "object"}
+        # Pydantic V2
+        return model_cls.model_json_schema()
+    except (ImportError, AttributeError):
+        # Pydantic V1 fallback
+        try:
+            return cast("BaseModel", model_cls).schema()
+        except AttributeError:
+            return {"type": "object"}
+
+
+def infer_params_schema(func: Callable[..., Any]) -> dict[str, Any]:
+    """Infer parameter JSON Schema from function signature.
+
+    Uses typing.get_type_hints() to resolve PEP 563 deferred annotations
+    (from __future__ import annotations), ensuring correct type inference even in
+    modules with that future directive.
+
+    Args:
+        func: The decorated handler function.
+
+    Returns:
+        OpenRPC params SchemaObject:
+        {
+            "type": "object",
+            "properties": {<name>: <schema>},
+            "required": [<name>, ...]
+        }
+    """
+    # get_type_hints() resolves deferred annotation strings;
+    # include_extras=True preserves Annotated wrappers
+    type_hints: dict[str, Any]
+    try:
+        type_hints = get_type_hints(func, include_extras=True)
+    except NameError:
+        # Some annotations cannot be resolved (e.g., locally defined classes);
+        # fall back to inspect.signature, still try to resolve types accessible from
+        # func.__globals__ (e.g., RpcContext)
+        sig = inspect.signature(func)
+        type_hints = {}
+        for p in sig.parameters.values():
+            if p.annotation is inspect.Parameter.empty:
+                continue
+            ann: Any = p.annotation
+            # Try to resolve string annotations (only from function global scope,
+            # not eval local scope)
+            if isinstance(ann, str):
+                try:
+                    ann = eval(ann, func.__globals__)
+                except Exception:
+                    pass  # Keep string; _is_rpc_context_param will handle it specially
+            if get_origin(ann) is Annotated:
+                ann = get_args(ann)[0]
+            type_hints[p.name] = ann
+
+    sig = inspect.signature(func)
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    for param_name, param in sig.parameters.items():
+        # Skip FastAPI Depends parameters (injected by OpenRpcRouter, not part of RPC params)
+        from fastapi.params import Depends as FastAPIDepends
+
+        if isinstance(param.default, FastAPIDepends):
+            continue
+
+        annotation = type_hints.get(param_name)
+
+        # Skip RpcContext parameters (injected by dispatcher, not part of RPC params)
+        if _is_rpc_context_param(annotation):
+            continue
+
+        # Pydantic BaseModel parameter: expand model fields to top-level.
+        # For example handler(params: GetSchemaRequest) -> params_schema only has
+        # qualified_name field, not nested in params object. This way JSON-RPC flat
+        # params {"qualified_name": "..."} can pass through _validate_params directly,
+        # and dispatcher packs it into a model instance at runtime.
+        if annotation is not None and _is_pydantic_model(cast(type[Any], annotation)):
+            expanded = _expand_pydantic_model_to_params(cast(type[Any], annotation))
+            # Merge fields into top-level properties and required
+            for fname, fschema in expanded.get("properties", {}).items():
+                properties[fname] = fschema
+            for fname in expanded.get("required", []):
+                required.append(fname)
+            continue
+
+        schema = _infer_param_schema(annotation)
+        properties[param_name] = schema
+
+        # required: no default value and not Optional
+        if param.default is inspect.Parameter.empty:
+            required.append(param_name)
+        elif param.default is not None:
+            # Has default value -> set as optional, provide default
+            properties[param_name]["default"] = param.default
+
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": list(dict.fromkeys(required)),
+    }
+
+
+def infer_result_schema(func: Callable[..., Any]) -> dict[str, Any]:
+    """Infer return value JSON Schema from function signature.
+
+    Uses typing.get_type_hints() to resolve PEP 563 deferred annotations.
+
+    - Pydantic BaseModel -> model_json_schema()
+    - Basic types -> direct mapping
+    - No annotation -> {"type": "object"}
+    """
+    import typing
+
+    # Use get_type_hints to resolve PEP 563 deferred annotations
+    try:
+        type_hints = typing.get_type_hints(func)
+        return_type = type_hints.get("return")
+    except Exception:
+        sig = inspect.signature(func)
+        return_type = sig.return_annotation
+
+    if return_type is None:
+        return {"type": "object"}
+
+    # Pydantic BaseModel
+    if _is_pydantic_model(return_type):
+        return _pydantic_model_schema(return_type)
+
+    # typing.List[T]
+    try:
+        origin = typing.get_origin(return_type)
+        args = typing.get_args(return_type)
+    except Exception:
+        origin = getattr(return_type, "__origin__", None)
+        args = getattr(return_type, "__args__", ())
+    if origin is list or origin is tuple:
+        if args:
+            return {
+                "type": "array",
+                "items": _infer_param_schema(args[0]),
+            }
+        return {"type": "array"}
+
+    # Union type (e.g., str | None, int | None) -- extract non-None type
+    # _infer_param_schema already handles Optional[T], reuse it
+    if origin is not None:
+        none_type = type(None)
+        non_none = [a for a in args if a is not none_type]
+        if len(non_none) == 1 and none_type in args:
+            return _infer_param_schema(non_none[0])
+
+    return {"type": _get_json_schema_type(return_type)}
+
+
+# ----------------------------------------------------------------------
+# @method() Decorator
+# ----------------------------------------------------------------------
+
+
+def method(
+    *,
+    name: str | None = None,
+    tags: list[str] | None = None,
+    params_schema: dict[str, Any] | None = None,
+    params_model: type | None = None,
+    result_schema: dict[str, Any] | None = None,
+    result_model: type | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    deprecated: bool = False,
+    examples: list[dict[str, Any]] | None = None,
+    required_roles: list[str] | None = None,
+    require: Require | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Declaratively register a JSON-RPC method.
+
+    Example::
+
+        from pydantic import BaseModel
+
+        class User(BaseModel):
+            id: str
+            name: str
+
+        @method(name="getUser", result_model=User)
+        async def get_user(ctx: RpcContext, user_id: str) -> User:
+            '''Get user information.'''
+            return User(id=user_id, name="Alice")
+
+    Args:
+        name: RPC method name. Defaults to function __name__.
+        tags: OpenRPC method tag grouping.
+        params_schema: Explicit parameter schema, overrides automatic inference.
+        result_schema: Explicit return value schema, overrides automatic inference.
+        result_model: Pydantic BaseModel subclass; automatically infers result_schema and
+                     calls .model_dump() to serialize the return value.
+        summary: Method short description (for documentation).
+        description: Method detailed description. Inferred from docstring by default.
+        deprecated: Whether to mark as deprecated.
+        examples: List of parameter and return value examples.
+        required_roles: List of roles required by the method; None means no permission check.
+        require: Role combination semantics, Require.ANY (default) or Require.ALL.
+    """
+    # rpc.discover is a reserved method name
+    _name = name or ""
+    if _name == "rpc.discover":
+        raise ValueError("'rpc.discover' is a reserved method name and cannot be registered.")
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        # Infer schema (pass func directly; let get_type_hints resolve PEP 563 annotations)
+        inferred_params = infer_params_schema(func)
+        inferred_result = infer_result_schema(func)
+
+        # Infer description from docstring
+        inferred_description = inspect.getdoc(func)
+
+        final_name = name or func.__name__
+        final_description = description if description is not None else inferred_description
+
+        # result_model handling: generate schema + mark serialization type
+        final_result_schema = result_schema
+        resolved_result_model: type | None = None
+
+        # Priority: explicit argument > automatic inference
+        if resolved_result_model is None:
+            # Infer result_model from return type annotation
+            # (supports -> UnifiedSchemaResponse syntax)
+            try:
+                import typing
+
+                type_hints = typing.get_type_hints(func)
+                return_type = type_hints.get("return")
+                if return_type is not None:
+                    # Handle Union types like Optional[User], User | None
+                    unwrapped = _unwrap_union(return_type)
+                    if _is_pydantic_model(return_type):
+                        resolved_result_model = cast(type[Any], return_type)
+                        if result_schema is None:
+                            final_result_schema = _pydantic_model_schema(
+                                cast(type[Any], return_type)
+                            )
+                    elif unwrapped is not None and _is_pydantic_model(unwrapped):
+                        # Union type contains Pydantic model (e.g., User | None)
+                        resolved_result_model = unwrapped
+                        if result_schema is None:
+                            final_result_schema = _pydantic_model_schema(unwrapped)
+            except Exception:
+                pass  # Silent fallback on parse failure; maintain backward compatibility
+
+        # Explicit result_model passed but result_schema not passed -> generate schema
+        if result_model is not None and result_schema is None:
+            final_result_schema = _pydantic_model_schema(result_model)
+
+        # params_model inference: detect first Pydantic BaseModel parameter in handler signature
+        resolved_params_model: type | None = None
+        if params_model is None:
+            # params_model not explicitly passed; infer from function signature
+            import typing as _typing
+
+            try:
+                _hints = _typing.get_type_hints(func, include_extras=True)
+            except Exception:
+                _hints = {}
+            sig = inspect.signature(func)
+
+            for _param_name, _param in sig.parameters.items():
+                _annotation = _hints.get(_param_name)
+                # Try to resolve string annotations
+                if _annotation is None or isinstance(_annotation, str):
+                    _raw = sig.parameters[_param_name].annotation
+                    if not isinstance(_raw, str):
+                        _raw = str(_raw)
+                    try:
+                        _resolved = eval(_raw, func.__globals__)
+                        if _annotation is None:
+                            _annotation = _resolved
+                    except Exception:
+                        pass
+                if _is_rpc_context_param(_annotation):
+                    continue
+                from fastapi.params import Depends as _FastAPIDepends
+
+                if isinstance(_param.default, _FastAPIDepends):
+                    continue
+                if _annotation is not None and _is_pydantic_model(cast(type[Any], _annotation)):
+                    if resolved_params_model is None:
+                        # Only take the first Pydantic parameter;
+                        # subsequent params_model remain None
+                        resolved_params_model = cast(type, _annotation)
+                    else:
+                        # Multiple Pydantic parameters: degrade to inline behavior (no params_model)
+                        resolved_params_model = None
+                        break
+        else:
+            resolved_params_model = params_model
+
+        # Handle required_roles: deduplicate + lowercase
+        final_required_roles: list[str] = []
+        if required_roles is not None:
+            final_required_roles = list(dict.fromkeys(r.lower() for r in required_roles))
+
+        # Handle require: default Require.ANY
+        final_require: Require = Require.ANY
+        if require is not None:
+            final_require = require
+
+        meta = MethodMeta(
+            name=final_name,
+            func=func,
+            params_schema=(params_schema if params_schema is not None else inferred_params),
+            result_schema=(
+                final_result_schema if final_result_schema is not None else inferred_result
+            ),
+            result_model=resolved_result_model,
+            params_model=resolved_params_model,
+            tags=list(tags) if tags else [],
+            summary=summary,
+            description=final_description,
+            deprecated=deprecated,
+            examples=list(examples) if examples else [],
+            required_roles=final_required_roles,
+            require=final_require,
+        )
+        add(meta)
+        return func
+
+    return decorator
+
+
+__all__ = ["method", "infer_params_schema", "infer_result_schema"]