tachyon-api 0.5.10__py3-none-any.whl → 0.6.0__py3-none-any.whl

tachyon_api/openapi/builder.py

@@ -0,0 +1,315 @@
+"""
+OpenAPI Documentation Builder for Tachyon API
+
+This module handles the generation and management of OpenAPI documentation
+for the Tachyon framework, including schema generation, parameter processing,
+and documentation endpoint setup.
+"""
+
+import inspect
+from typing import Any, Dict, Type, Union, Callable
+from starlette.responses import HTMLResponse
+
+from ..schemas.models import Struct
+from ..schemas.parameters import Body, Query, Path
+from .schema import (
+    OpenAPIGenerator,
+    OpenAPIConfig,
+    build_components_for_struct,
+)
+
+
+class OpenAPIBuilder:
+    """
+    Handles OpenAPI documentation generation and management.
+
+    This class centralizes all OpenAPI-related functionality, including
+    schema generation, parameter processing, and documentation endpoint setup.
+    """
+
+    def __init__(
+        self, openapi_config: OpenAPIConfig, openapi_generator: OpenAPIGenerator
+    ):
+        """
+        Initialize the OpenAPI builder.
+
+        Args:
+            openapi_config: OpenAPI configuration
+            openapi_generator: OpenAPI generator instance
+        """
+        self.openapi_config = openapi_config
+        self.openapi_generator = openapi_generator
+
+    def generate_openapi_for_route(
+        self, path: str, method: str, endpoint_func: Callable, **kwargs
+    ):
+        """
+        Generate OpenAPI documentation for a specific route.
+
+        This method analyzes the endpoint function signature and generates appropriate
+        OpenAPI schema entries for parameters, request body, and responses.
+
+        Args:
+            path: URL path pattern
+            method: HTTP method
+            endpoint_func: The endpoint function
+            **kwargs: Additional route metadata (summary, description, tags, etc.)
+        """
+        sig = inspect.signature(endpoint_func)
+
+        # Ensure common error schemas exist in components
+        self.openapi_generator.add_schema(
+            "ValidationErrorResponse",
+            {
+                "type": "object",
+                "properties": {
+                    "success": {"type": "boolean"},
+                    "error": {"type": "string"},
+                    "code": {"type": "string"},
+                    "errors": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                        },
+                    },
+                },
+                "required": ["success", "error", "code"],
+            },
+        )
+        self.openapi_generator.add_schema(
+            "ResponseValidationError",
+            {
+                "type": "object",
+                "properties": {
+                    "success": {"type": "boolean"},
+                    "error": {"type": "string"},
+                    "detail": {"type": "string"},
+                    "code": {"type": "string"},
+                },
+                "required": ["success", "error", "code"],
+            },
+        )
+
+        # Build the OpenAPI operation object
+        operation = {
+            "summary": kwargs.get(
+                "summary", self._generate_summary_from_function(endpoint_func)
+            ),
+            "description": kwargs.get("description", endpoint_func.__doc__ or ""),
+            "responses": {
+                "200": {
+                    "description": "Successful Response",
+                    "content": {"application/json": {"schema": {"type": "object"}}},
+                },
+                "422": {
+                    "description": "Validation Error",
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/ValidationErrorResponse"
+                            }
+                        }
+                    },
+                },
+                "500": {
+                    "description": "Response Validation Error",
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/ResponseValidationError"
+                            }
+                        }
+                    },
+                },
+            },
+        }
+
+        # If a response_model is provided and is a Struct, use it for the 200 response schema
+        response_model = kwargs.get("response_model")
+        if response_model is not None and issubclass(response_model, Struct):
+            comps = build_components_for_struct(response_model)
+            for name, schema in comps.items():
+                self.openapi_generator.add_schema(name, schema)
+            operation["responses"]["200"]["content"]["application/json"]["schema"] = {
+                "$ref": f"#/components/schemas/{response_model.__name__}"
+            }
+
+        # Add tags if provided
+        if "tags" in kwargs:
+            operation["tags"] = kwargs["tags"]
+
+        # Process parameters from function signature
+        parameters = []
+        request_body_schema = None
+
+        for param in sig.parameters.values():
+            # Skip dependency parameters
+            if isinstance(
+                param.default, (Body.__class__, Query.__class__, Path.__class__)
+            ) or (
+                param.default is inspect.Parameter.empty
+                and param.annotation.__name__ in ["Depends"]
+            ):
+                continue
+
+            # Process query parameters
+            elif isinstance(param.default, Query):
+                parameters.append(
+                    {
+                        "name": param.name,
+                        "in": "query",
+                        "required": param.default.default is ...,
+                        "schema": self._build_param_openapi_schema(param.annotation),
+                        "description": getattr(param.default, "description", ""),
+                    }
+                )
+
+            # Process path parameters
+            elif isinstance(param.default, Path) or self._is_path_parameter(
+                param.name, path
+            ):
+                parameters.append(
+                    {
+                        "name": param.name,
+                        "in": "path",
+                        "required": True,
+                        "schema": self._build_param_openapi_schema(param.annotation),
+                        "description": getattr(param.default, "description", "")
+                        if isinstance(param.default, Path)
+                        else "",
+                    }
+                )
+
+            # Process body parameters
+            elif isinstance(param.default, Body):
+                model_class = param.annotation
+                if issubclass(model_class, Struct):
+                    comps = build_components_for_struct(model_class)
+                    for name, schema in comps.items():
+                        self.openapi_generator.add_schema(name, schema)
+
+                    request_body_schema = {
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": f"#/components/schemas/{model_class.__name__}"
+                                }
+                            }
+                        },
+                        "required": True,
+                    }
+
+        # Add parameters to operation if any exist
+        if parameters:
+            operation["parameters"] = parameters
+
+        if request_body_schema:
+            operation["requestBody"] = request_body_schema
+
+        self.openapi_generator.add_path(path, method, operation)
+
+    @staticmethod
+    def _generate_summary_from_function(func: Callable) -> str:
+        """Generate a human-readable summary from function name."""
+        return func.__name__.replace("_", " ").title()
+
+    @staticmethod
+    def _is_path_parameter(param_name: str, path: str) -> bool:
+        """Check if a parameter name corresponds to a path parameter in the URL."""
+        return f"{{{param_name}}}" in path
+
+    @staticmethod
+    def _get_openapi_type(python_type: Type) -> str:
+        """Convert Python type to OpenAPI schema type."""
+        type_map: Dict[Type, str] = {
+            int: "integer",
+            str: "string",
+            bool: "boolean",
+            float: "number",
+        }
+        return type_map.get(python_type, "string")
+
+    @staticmethod
+    def _build_param_openapi_schema(python_type: Type) -> Dict[str, Any]:
+        """Build OpenAPI schema for parameter types, supporting Optional[T] and List[T]."""
+        import typing
+
+        origin = typing.get_origin(python_type)
+        args = typing.get_args(python_type)
+        nullable = False
+        # Optional[T]
+        if origin is Union and args:
+            non_none = [a for a in args if a is not type(None)]  # noqa: E721
+            if len(non_none) == 1:
+                python_type = non_none[0]
+                nullable = True
+        # List[T] (and List[Optional[T]])
+        origin = typing.get_origin(python_type)
+        args = typing.get_args(python_type)
+        if origin in (list, typing.List):
+            item_type = args[0] if args else str
+            # Unwrap Optional in items for List[Optional[T]]
+            item_origin = typing.get_origin(item_type)
+            item_args = typing.get_args(item_type)
+            item_nullable = False
+            if item_origin is Union and item_args:
+                item_non_none = [a for a in item_args if a is not type(None)]  # noqa: E721
+                if len(item_non_none) == 1:
+                    item_type = item_non_none[0]
+                    item_nullable = True
+            schema = {
+                "type": "array",
+                "items": {"type": OpenAPIBuilder._get_openapi_type(item_type)},
+            }
+            if item_nullable:
+                schema["items"]["nullable"] = True
+        else:
+            schema = {"type": OpenAPIBuilder._get_openapi_type(python_type)}
+        if nullable:
+            schema["nullable"] = True
+        return schema
+
+    def setup_docs(self, app):
+        """
+        Setup OpenAPI documentation endpoints.
+
+        This method registers the routes for serving OpenAPI JSON schema,
+        Swagger UI, and ReDoc documentation interfaces.
+
+        Args:
+            app: The Tachyon application instance
+        """
+
+        # OpenAPI JSON schema endpoint
+        @app.get(self.openapi_config.openapi_url, include_in_schema=False)
+        def get_openapi_schema():
+            """Serve the OpenAPI JSON schema."""
+            return self.openapi_generator.get_openapi_schema()
+
+        # Scalar API Reference documentation endpoint (default for /docs)
+        @app.get(self.openapi_config.docs_url, include_in_schema=False)
+        def get_scalar_docs():
+            """Serve the Scalar API Reference documentation interface."""
+            html = self.openapi_generator.get_scalar_html(
+                self.openapi_config.openapi_url, self.openapi_config.info.title
+            )
+            return HTMLResponse(html)
+
+        # Swagger UI documentation endpoint (legacy support)
+        @app.get("/swagger", include_in_schema=False)
+        def get_swagger_ui():
+            """Serve the Swagger UI documentation interface."""
+            html = self.openapi_generator.get_swagger_ui_html(
+                self.openapi_config.openapi_url, self.openapi_config.info.title
+            )
+            return HTMLResponse(html)
+
+        # ReDoc documentation endpoint
+        @app.get(self.openapi_config.redoc_url, include_in_schema=False)
+        def get_redoc():
+            """Serve the ReDoc documentation interface."""
+            html = self.openapi_generator.get_redoc_html(
+                self.openapi_config.openapi_url, self.openapi_config.info.title
+            )
+            return HTMLResponse(html)

tachyon_api/{openapi.py → openapi/schema.py}

@@ -5,7 +5,7 @@ import uuid
 import typing
 import json
 
-from .models import Struct
+from ..schemas.models import Struct
 
 # Type mapping from Python types to OpenAPI schema types
 TYPE_MAP = {int: "integer", str: "string", bool: "boolean", float: "number"}

tachyon_api/processing/__init__.py

@@ -0,0 +1,8 @@
+"""
+Tachyon API request/response processing.
+"""
+
+from .parameters import ParameterProcessor, _NotProcessed
+from .responses import ResponseProcessor
+
+__all__ = ["ParameterProcessor", "_NotProcessed", "ResponseProcessor"]

tachyon_api/processing/parameters.py

@@ -0,0 +1,308 @@
+"""
+Parameter Processing System for Tachyon API
+
+This module handles the processing and validation of different parameter types
+(Body, Query, Path) for endpoint functions.
+"""
+
+import inspect
+import typing
+from typing import Any, Union
+from starlette.responses import JSONResponse
+
+import msgspec
+
+from ..schemas.models import Struct
+from ..schemas.parameters import Body, Query, Path
+from ..schemas.responses import validation_error_response
+from ..utils.type_converter import TypeConverter
+from ..utils.type_utils import TypeUtils
+
+
+class _NotProcessed:
+    """Sentinel value to indicate that a parameter was not processed by ParameterProcessor."""
+
+    pass
+
+
+class ParameterProcessor:
+    """
+    Handles processing and validation of endpoint parameters.
+
+    This class processes Body, Query, and Path parameters, performing type conversion,
+    validation, and error handling for each parameter type.
+    """
+
+    @staticmethod
+    async def process_body_parameter(
+        param, model_class, _raw_body, request
+    ) -> Union[Any, JSONResponse]:
+        """
+        Process a Body parameter from the request.
+
+        Args:
+            param: The parameter object from function signature
+            model_class: The expected model class (must be a Struct)
+            _raw_body: Cached raw body data
+            request: The Starlette request object
+
+        Returns:
+            Validated body data or JSONResponse with validation error
+        """
+        if not issubclass(model_class, Struct):
+            raise TypeError(
+                "Body type must be an instance of Tachyon_api.models.Struct"
+            )
+
+        decoder = msgspec.json.Decoder(model_class)
+        try:
+            if _raw_body is None:
+                _raw_body = await request.body()
+            validated_data = decoder.decode(_raw_body)
+            return validated_data
+        except msgspec.ValidationError as e:
+            # Attempt to build field errors map using e.path
+            field_errors = None
+            try:
+                path = getattr(e, "path", None)
+                if path:
+                    # Choose last string-ish path element as field name
+                    field_name = None
+                    for p in reversed(path):
+                        if isinstance(p, str):
+                            field_name = p
+                            break
+                    if field_name:
+                        field_errors = {field_name: [str(e)]}
+            except Exception:
+                field_errors = None
+            return validation_error_response(str(e), errors=field_errors)
+
+    @staticmethod
+    def process_query_parameter(param, query_params) -> Union[Any, JSONResponse, None]:
+        """
+        Process a Query parameter from the request.
+
+        Args:
+            param: The parameter object from function signature
+            query_params: The query parameters from the request
+
+        Returns:
+            Converted parameter value, None (for missing optional), or JSONResponse with error
+        """
+        query_info = param.default
+        param_name = param.name
+
+        # Determine typing for advanced cases
+        ann = param.annotation
+        origin = typing.get_origin(ann)
+        args = typing.get_args(ann)
+
+        # List[T] handling
+        if origin in (list, typing.List):
+            item_type = args[0] if args else str
+            values = []
+            # collect repeated params
+            if hasattr(query_params, "getlist"):
+                values = query_params.getlist(param_name)
+            # if not repeated, check for CSV in single value
+            if not values and param_name in query_params:
+                raw = query_params[param_name]
+                values = raw.split(",") if "," in raw else [raw]
+            # flatten CSV in any element
+            flat_values = []
+            for v in values:
+                if isinstance(v, str) and "," in v:
+                    flat_values.extend(v.split(","))
+                else:
+                    flat_values.append(v)
+            values = flat_values
+            if not values:
+                if query_info.default is not ...:
+                    return query_info.default
+                return validation_error_response(
+                    f"Missing required query parameter: {param_name}"
+                )
+            # Unwrap Optional for item type
+            base_item_type, item_is_opt = TypeUtils.unwrap_optional(item_type)
+            converted_list = []
+            for v in values:
+                if item_is_opt and (v == "" or v.lower() == "null"):
+                    converted_list.append(None)
+                    continue
+                converted_value = TypeConverter.convert_value(
+                    v, base_item_type, param_name, is_path_param=False
+                )
+                if isinstance(converted_value, JSONResponse):
+                    return converted_value
+                converted_list.append(converted_value)
+            return converted_list
+
+        # Optional[T] handling for single value
+        base_type, _is_opt = TypeUtils.unwrap_optional(ann)
+
+        if param_name in query_params:
+            value_str = query_params[param_name]
+            converted_value = TypeConverter.convert_value(
+                value_str, base_type, param_name, is_path_param=False
+            )
+            if isinstance(converted_value, JSONResponse):
+                return converted_value
+            return converted_value
+
+        elif query_info.default is not ...:
+            return query_info.default
+        else:
+            return validation_error_response(
+                f"Missing required query parameter: {param_name}"
+            )
+
+    @staticmethod
+    def process_explicit_path_parameter(param, path_params) -> Union[Any, JSONResponse]:
+        """
+        Process an explicit Path parameter (with Path() annotation).
+
+        Args:
+            param: The parameter object from function signature
+            path_params: The path parameters from the request
+
+        Returns:
+            Converted parameter value or JSONResponse with error
+        """
+        param_name = param.name
+        if param_name in path_params:
+            value_str = path_params[param_name]
+            # Support List[T] in path params via CSV
+            ann = param.annotation
+            origin = typing.get_origin(ann)
+            args = typing.get_args(ann)
+            if origin in (list, typing.List):
+                item_type = args[0] if args else str
+                parts = value_str.split(",") if value_str else []
+                # Unwrap Optional for item type
+                base_item_type, item_is_opt = TypeUtils.unwrap_optional(item_type)
+                converted_list = []
+                for v in parts:
+                    if item_is_opt and (v == "" or v.lower() == "null"):
+                        converted_list.append(None)
+                        continue
+                    converted_value = TypeConverter.convert_value(
+                        v, base_item_type, param_name, is_path_param=True
+                    )
+                    if isinstance(converted_value, JSONResponse):
+                        return converted_value
+                    converted_list.append(converted_value)
+                return converted_list
+            else:
+                converted_value = TypeConverter.convert_value(
+                    value_str, ann, param_name, is_path_param=True
+                )
+                # Return 404 if conversion failed
+                if isinstance(converted_value, JSONResponse):
+                    return converted_value
+                return converted_value
+        else:
+            return JSONResponse({"detail": "Not Found"}, status_code=404)
+
+    @staticmethod
+    def process_implicit_path_parameter(
+        param, path_params
+    ) -> Union[Any, JSONResponse, None]:
+        """
+        Process an implicit Path parameter (URL path variable without Path()).
+
+        Args:
+            param: The parameter object from function signature
+            path_params: The path parameters from the request
+
+        Returns:
+            Converted parameter value, None (not processed), or JSONResponse with error
+        """
+        param_name = param.name
+        value_str = path_params[param_name]
+        # Support List[T] via CSV
+        ann = param.annotation
+        origin = typing.get_origin(ann)
+        args = typing.get_args(ann)
+        if origin in (list, typing.List):
+            item_type = args[0] if args else str
+            parts = value_str.split(",") if value_str else []
+            # Unwrap Optional for item type
+            base_item_type, item_is_opt = TypeUtils.unwrap_optional(item_type)
+            converted_list = []
+            for v in parts:
+                if item_is_opt and (v == "" or v.lower() == "null"):
+                    converted_list.append(None)
+                    continue
+                converted_value = TypeConverter.convert_value(
+                    v, base_item_type, param_name, is_path_param=True
+                )
+                if isinstance(converted_value, JSONResponse):
+                    return converted_value
+                converted_list.append(converted_value)
+            return converted_list
+        else:
+            converted_value = TypeConverter.convert_value(
+                value_str, ann, param_name, is_path_param=True
+            )
+            # Return 404 if conversion failed
+            if isinstance(converted_value, JSONResponse):
+                return converted_value
+            return converted_value
+
+    @classmethod
+    async def process_parameter(
+        cls,
+        param,
+        request,
+        path_params,
+        query_params,
+        _raw_body,
+        is_explicit_dependency,
+        is_implicit_dependency,
+    ) -> Union[Any, JSONResponse, None]:
+        """
+        Process a single parameter based on its type and annotations.
+
+        Args:
+            param: The parameter object from function signature
+            request: The Starlette request object
+            path_params: Path parameters from the request
+            query_params: Query parameters from the request
+            _raw_body: Cached raw body data
+            is_explicit_dependency: Whether this is an explicit dependency
+            is_implicit_dependency: Whether this is an implicit dependency
+
+        Returns:
+            Parameter value, JSONResponse (error), or None (not processed)
+        """
+        # Process Body parameters (JSON request body)
+        if isinstance(param.default, Body):
+            model_class = param.annotation
+            result = await cls.process_body_parameter(
+                param, model_class, _raw_body, request
+            )
+            return result
+
+        # Process Query parameters (URL query string)
+        elif isinstance(param.default, Query):
+            result = cls.process_query_parameter(param, query_params)
+            return result
+
+        # Process explicit Path parameters (with Path() annotation)
+        elif isinstance(param.default, Path):
+            result = cls.process_explicit_path_parameter(param, path_params)
+            return result
+
+        # Process implicit Path parameters (URL path variables without Path())
+        elif (
+            param.default is inspect.Parameter.empty
+            and param.name in path_params
+            and not is_explicit_dependency
+            and not is_implicit_dependency
+        ):
+            result = cls.process_implicit_path_parameter(param, path_params)
+            return result
+
+        # Parameter not processed by this processor
+        return _NotProcessed()