tachyon-api 0.5.7__tar.gz → 0.5.10__tar.gz

{tachyon_api-0.5.7 → tachyon_api-0.5.10}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.3
 Name: tachyon-api
-Version: 0.5.7
+Version: 0.5.10
 Summary: A lightweight, FastAPI-inspired web framework
 License: GPL-3.0-or-later
 Author: Juan Manuel Panozzo Zénere
 Author-email: jm.panozzozenere@gmail.com
-Requires-Python: >=3.10,<4.0
+Requires-Python: >=3.10,<3.14
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -14,7 +14,6 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: msgspec (>=0.19.0,<0.20.0)
 Requires-Dist: orjson (>=3.11.1,<4.0.0)
-Requires-Dist: ruff (>=0.12.7,<0.13.0)
 Requires-Dist: starlette (>=0.47.2,<0.48.0)
 Requires-Dist: typer (>=0.16.0,<0.17.0)
 Requires-Dist: uvicorn (>=0.35.0,<0.36.0)
@@ -59,7 +58,7 @@ def create_user(user: User):
 - 🔄 Middlewares (class + decorator)
 - 🧠 Cache decorator with TTL (in-memory, Redis, Memcached)
 - 🚀 High-performance JSON (msgspec + orjson)
-- 🧾 Unified error format (422/500)
+- 🧾 Unified error format (422/500) + global exception handler (500)
 - 🧰 Default JSON response (TachyonJSONResponse)
 - 🔒 End-to-end safety: request Body validation + typed response_model
 - 📘 Deep OpenAPI schemas: nested Structs, Optional/List (nullable/array), formats (uuid, date-time)
@@ -82,7 +81,7 @@ Tachyon API is built with TDD principles at its core. The test suite covers rout
 
 ## 🔄 Middleware Support
 
-- Built-in: CORSMiddleware, LoggerMiddleware
+- Built-in: CORSMiddleware and LoggerMiddleware
 - Use app.add_middleware(...) or @app.middleware()
 
 ## ⚡ Cache with TTL
@@ -92,10 +91,11 @@ Tachyon API is built with TDD principles at its core. The test suite covers rout
 
 ## 📚 Example Application
 
-The example demonstrates clean architecture, routers, middlewares, caching, and now end-to-end safety with OpenAPI:
+The example demonstrates clean architecture, routers, middlewares, caching, end-to-end safety, and global exception handling:
 
 - /orjson-demo: default JSON powered by orjson
 - /api/v1/users/e2e: Body + response_model, unified errors and deep OpenAPI schemas
+- /error-demo: triggers an unhandled exception to showcase the global handler (structured 500)
 
 Run the example:
 
@@ -117,6 +117,7 @@ Docs at /docs (Scalar), /swagger, /redoc.
 - Default response: TachyonJSONResponse serializes complex types (UUID/date/datetime, Struct) via orjson and centralized encoders.
 - 422 Validation: { success: false, error, code: VALIDATION_ERROR, [errors] }.
 - 500 Response model: { success: false, error: "Response validation error: ...", detail, code: RESPONSE_VALIDATION_ERROR }.
+- 500 Unhandled exceptions (global): { success: false, error: "Internal Server Error", code: INTERNAL_SERVER_ERROR }.
 
 ## 📝 Contributing
 

{tachyon_api-0.5.7 → tachyon_api-0.5.10}/README.md

@@ -37,7 +37,7 @@ def create_user(user: User):
 - 🔄 Middlewares (class + decorator)
 - 🧠 Cache decorator with TTL (in-memory, Redis, Memcached)
 - 🚀 High-performance JSON (msgspec + orjson)
-- 🧾 Unified error format (422/500)
+- 🧾 Unified error format (422/500) + global exception handler (500)
 - 🧰 Default JSON response (TachyonJSONResponse)
 - 🔒 End-to-end safety: request Body validation + typed response_model
 - 📘 Deep OpenAPI schemas: nested Structs, Optional/List (nullable/array), formats (uuid, date-time)
@@ -60,7 +60,7 @@ Tachyon API is built with TDD principles at its core. The test suite covers rout
 
 ## 🔄 Middleware Support
 
-- Built-in: CORSMiddleware, LoggerMiddleware
+- Built-in: CORSMiddleware and LoggerMiddleware
 - Use app.add_middleware(...) or @app.middleware()
 
 ## ⚡ Cache with TTL
@@ -70,10 +70,11 @@ Tachyon API is built with TDD principles at its core. The test suite covers rout
 
 ## 📚 Example Application
 
-The example demonstrates clean architecture, routers, middlewares, caching, and now end-to-end safety with OpenAPI:
+The example demonstrates clean architecture, routers, middlewares, caching, end-to-end safety, and global exception handling:
 
 - /orjson-demo: default JSON powered by orjson
 - /api/v1/users/e2e: Body + response_model, unified errors and deep OpenAPI schemas
+- /error-demo: triggers an unhandled exception to showcase the global handler (structured 500)
 
 Run the example:
 
@@ -95,6 +96,7 @@ Docs at /docs (Scalar), /swagger, /redoc.
 - Default response: TachyonJSONResponse serializes complex types (UUID/date/datetime, Struct) via orjson and centralized encoders.
 - 422 Validation: { success: false, error, code: VALIDATION_ERROR, [errors] }.
 - 500 Response model: { success: false, error: "Response validation error: ...", detail, code: RESPONSE_VALIDATION_ERROR }.
+- 500 Unhandled exceptions (global): { success: false, error: "Internal Server Error", code: INTERNAL_SERVER_ERROR }.
 
 ## 📝 Contributing
 

{tachyon_api-0.5.7 → tachyon_api-0.5.10}/pyproject.toml

@@ -1,18 +1,17 @@
 [tool.poetry]
 name = "tachyon-api"
-version = "0.5.7"
+version = "0.5.10"
 description = "A lightweight, FastAPI-inspired web framework"
 authors = ["Juan Manuel Panozzo Zénere <jm.panozzozenere@gmail.com>"]
 license = "GPL-3.0-or-later"
 readme = "README.md"
 
 [tool.poetry.dependencies]
-python = "^3.10"
+python = ">=3.10,<3.14"
 starlette = "^0.47.2"
 uvicorn = "^0.35.0"
 msgspec = "^0.19.0"
 typer = "^0.16.0"
-ruff = "^0.12.7"
 orjson = "^3.11.1"
 
 
@@ -20,6 +19,7 @@ orjson = "^3.11.1"
 pytest = "^8.4.1"
 pytest-asyncio = "^1.1.0"
 httpx = "^0.28.1"
+ruff = "^0.12.7"
 
 [build-system]
 requires = ["poetry-core"]

{tachyon_api-0.5.7 → tachyon_api-0.5.10}/tachyon_api/app.py

@@ -23,7 +23,6 @@ from .openapi import (
     OpenAPIGenerator,
     OpenAPIConfig,
     create_openapi_config,
-    _generate_schema_for_struct,
 )
 from .params import Body, Query, Path
 from .middlewares.core import (
@@ -35,10 +34,14 @@ from .responses import (
     validation_error_response,
     response_validation_error_response,
 )
-# New: optional cache configuration support
+
+from .utils import TypeConverter, TypeUtils
+
+from .responses import internal_server_error_response
+
 try:
     from .cache import set_cache_config
-except Exception:  # pragma: no cover - defensive import guard
+except ImportError:
     set_cache_config = None  # type: ignore
 
 
@@ -96,65 +99,6 @@ class Tachyon:
                 partial(self._create_decorator, http_method=method),
             )
 
-    @staticmethod
-    def _convert_value(
-        value_str: str,
-        target_type: Type,
-        param_name: str,
-        is_path_param: bool = False,  # noqa
-    ) -> Union[Any, JSONResponse]:
-        """
-        Convert a string value to the target type with appropriate error handling.
-
-        This method handles type conversion for query and path parameters,
-        including special handling for boolean values and proper error responses.
-
-        Args:
-            value_str: The string value to convert
-            target_type: The target Python type to convert to
-            param_name: Name of the parameter (for error messages)
-            is_path_param: Whether this is a path parameter (affects error response)
-
-        Returns:
-            The converted value, or a JSONResponse with appropriate error code
-
-        Note:
-            - Boolean conversion accepts: "true", "1", "t", "yes" (case-insensitive)
-            - Path parameter errors return 404, query parameter errors return 422
-        """
-        # Unwrap Optional/Union[T, None]
-        origin = typing.get_origin(target_type)
-        args = typing.get_args(target_type)
-        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:
-                target_type = non_none[0]
-
-        try:
-            if target_type is bool:
-                return value_str.lower() in ("true", "1", "t", "yes")
-            elif target_type is not str:
-                return target_type(value_str)
-            else:
-                return value_str
-        except (ValueError, TypeError):
-            if is_path_param:
-                return JSONResponse({"detail": "Not Found"}, status_code=404)
-            else:
-                type_name = "integer" if target_type is int else getattr(target_type, "__name__", str(target_type))
-                return validation_error_response(f"Invalid value for {type_name} conversion")
-
-    @staticmethod
-    def _unwrap_optional(python_type: Type) -> tuple[Type, bool]:
-        """Return (inner_type, is_optional) for Optional[T] or (python_type, False)."""
-        origin = typing.get_origin(python_type)
-        args = typing.get_args(python_type)
-        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:
-                return non_none[0], True
-        return python_type, False
-
     def _resolve_dependency(self, cls: Type) -> Any:
         """
         Resolve a dependency and its sub-dependencies recursively.
@@ -257,137 +201,190 @@ class Tachyon:
             This handler analyzes the endpoint function signature and automatically
             injects the appropriate values based on parameter annotations and defaults.
             """
-            kwargs_to_inject = {}
-            sig = inspect.signature(endpoint_func)
-            query_params = request.query_params
-            path_params = request.path_params
-            _raw_body = None
-
-            # Process each parameter in the endpoint function signature
-            for param in sig.parameters.values():
-                # Determine if this parameter is a dependency
-                is_explicit_dependency = isinstance(param.default, Depends)
-                is_implicit_dependency = (
-                    param.default is inspect.Parameter.empty
-                    and param.annotation in _registry
-                )
-
-                # Process dependencies (explicit and implicit)
-                if is_explicit_dependency or is_implicit_dependency:
-                    target_class = param.annotation
-                    kwargs_to_inject[param.name] = self._resolve_dependency(
-                        target_class
+            try:
+                kwargs_to_inject = {}
+                sig = inspect.signature(endpoint_func)
+                query_params = request.query_params
+                path_params = request.path_params
+                _raw_body = None
+
+                # Process each parameter in the endpoint function signature
+                for param in sig.parameters.values():
+                    # Determine if this parameter is a dependency
+                    is_explicit_dependency = isinstance(param.default, Depends)
+                    is_implicit_dependency = (
+                        param.default is inspect.Parameter.empty
+                        and param.annotation in _registry
                     )
 
-                # Process Body parameters (JSON request body)
-                elif isinstance(param.default, Body):
-                    model_class = param.annotation
-                    if not issubclass(model_class, Struct):
-                        raise TypeError(
-                            "Body type must be an instance of Tachyon_api.models.Struct"
+                    # Process dependencies (explicit and implicit)
+                    if is_explicit_dependency or is_implicit_dependency:
+                        target_class = param.annotation
+                        kwargs_to_inject[param.name] = self._resolve_dependency(
+                            target_class
                         )
 
-                    decoder = msgspec.json.Decoder(model_class)
-                    try:
-                        if _raw_body is None:
-                            _raw_body = await request.body()
-                        validated_data = decoder.decode(_raw_body)
-                        kwargs_to_inject[param.name] = validated_data
-                    except msgspec.ValidationError as e:
-                        # Attempt to build field errors map using e.path
-                        field_errors = None
+                    # Process Body parameters (JSON request body)
+                    elif isinstance(param.default, Body):
+                        model_class = param.annotation
+                        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:
-                            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:
+                            if _raw_body is None:
+                                _raw_body = await request.body()
+                            validated_data = decoder.decode(_raw_body)
+                            kwargs_to_inject[param.name] = validated_data
+                        except msgspec.ValidationError as e:
+                            # Attempt to build field errors map using e.path
                             field_errors = None
-                        return validation_error_response(str(e), errors=field_errors)
-
-                # Process Query parameters (URL query string)
-                elif isinstance(param.default, Query):
-                    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 ...:
-                                kwargs_to_inject[param_name] = query_info.default
-                                continue
+                            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(
-                                f"Missing required query parameter: {param_name}"
+                                str(e), errors=field_errors
                             )
-                        # Unwrap Optional for item type
-                        base_item_type, item_is_opt = self._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 = self._convert_value(
-                                v, base_item_type, param_name, is_path_param=False
+
+                    # Process Query parameters (URL query string)
+                    elif isinstance(param.default, Query):
+                        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 ...:
+                                    kwargs_to_inject[param_name] = query_info.default
+                                    continue
+                                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)
+                            kwargs_to_inject[param_name] = converted_list
+                            continue
+
+                        # 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
-                            converted_list.append(converted_value)
-                        kwargs_to_inject[param_name] = converted_list
-                        continue
+                            kwargs_to_inject[param_name] = converted_value
 
-                    # Optional[T] handling for single value
-                    base_type, _is_opt = self._unwrap_optional(ann)
+                        elif query_info.default is not ...:
+                            kwargs_to_inject[param.name] = query_info.default
+                        else:
+                            return validation_error_response(
+                                f"Missing required query parameter: {param_name}"
+                            )
 
-                    if param_name in query_params:
-                        value_str = query_params[param_name]
-                        converted_value = self._convert_value(
-                            value_str, base_type, param_name, is_path_param=False
-                        )
-                        if isinstance(converted_value, JSONResponse):
-                            return converted_value
-                        kwargs_to_inject[param_name] = converted_value
-
-                    elif query_info.default is not ...:
-                        kwargs_to_inject[param.name] = query_info.default
-                    else:
-                        return validation_error_response(
-                            f"Missing required query parameter: {param_name}"
-                        )
+                    # Process explicit Path parameters (with Path() annotation)
+                    elif isinstance(param.default, Path):
+                        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)
+                                kwargs_to_inject[param_name] = 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
+                                kwargs_to_inject[param_name] = converted_value
+                        else:
+                            return JSONResponse(
+                                {"detail": "Not Found"}, status_code=404
+                            )
 
-                # Process explicit Path parameters (with Path() annotation)
-                elif isinstance(param.default, Path):
-                    param_name = param.name
-                    if param_name in path_params:
+                    # 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
+                    ):
+                        param_name = param.name
                         value_str = path_params[param_name]
-                        # Support List[T] in path params via CSV
+                        # Support List[T] via CSV
                         ann = param.annotation
                         origin = typing.get_origin(ann)
                         args = typing.get_args(ann)
@@ -395,13 +392,15 @@ class Tachyon:
                             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 = self._unwrap_optional(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 = self._convert_value(
+                                converted_value = TypeConverter.convert_value(
                                     v, base_item_type, param_name, is_path_param=True
                                 )
                                 if isinstance(converted_value, JSONResponse):
@@ -409,82 +408,44 @@ class Tachyon:
                                 converted_list.append(converted_value)
                             kwargs_to_inject[param_name] = converted_list
                         else:
-                            converted_value = self._convert_value(
+                            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
                             kwargs_to_inject[param_name] = converted_value
-                    else:
-                        return JSONResponse({"detail": "Not Found"}, status_code=404)
-
-                # 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
-                ):
-                    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 = self._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 = self._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)
-                        kwargs_to_inject[param_name] = converted_list
-                    else:
-                        converted_value = self._convert_value(
-                            value_str, ann, param_name, is_path_param=True
-                        )
-                        # Return 404 if conversion failed
-                        if isinstance(converted_value, JSONResponse):
-                            return converted_value
-                        kwargs_to_inject[param_name] = converted_value
-
-            # Call the endpoint function with injected parameters
-            if asyncio.iscoroutinefunction(endpoint_func):
-                payload = await endpoint_func(**kwargs_to_inject)
-            else:
-                payload = endpoint_func(**kwargs_to_inject)
-
-            # If the endpoint already returned a Response object, return it directly
-            if isinstance(payload, Response):
-                return payload
-
-            # Validate/convert response against response_model if provided
-            if response_model is not None:
-                try:
-                    payload = msgspec.convert(payload, response_model)
-                except Exception as e:
-                    return response_validation_error_response(str(e))
-
-            # Convert Struct objects to dictionaries for JSON serialization
-            if isinstance(payload, Struct):
-                payload = msgspec.to_builtins(payload)
-            elif isinstance(payload, dict):
-                # Convert any Struct values in the dictionary
-                for key, value in payload.items():
-                    if isinstance(value, Struct):
-                        payload[key] = msgspec.to_builtins(value)
-
-            return TachyonJSONResponse(payload)
+
+                # Call the endpoint function with injected parameters
+                if asyncio.iscoroutinefunction(endpoint_func):
+                    payload = await endpoint_func(**kwargs_to_inject)
+                else:
+                    payload = endpoint_func(**kwargs_to_inject)
+
+                # If the endpoint already returned a Response object, return it directly
+                if isinstance(payload, Response):
+                    return payload
+
+                # Validate/convert response against response_model if provided
+                if response_model is not None:
+                    try:
+                        payload = msgspec.convert(payload, response_model)
+                    except Exception as e:
+                        return response_validation_error_response(str(e))
+
+                # Convert Struct objects to dictionaries for JSON serialization
+                if isinstance(payload, Struct):
+                    payload = msgspec.to_builtins(payload)
+                elif isinstance(payload, dict):
+                    # Convert any Struct values in the dictionary
+                    for key, value in payload.items():
+                        if isinstance(value, Struct):
+                            payload[key] = msgspec.to_builtins(value)
+
+                return TachyonJSONResponse(payload)
+            except Exception:
+                # Fallback: prevent unhandled exceptions from leaking to the client
+                return internal_server_error_response()
 
         # Register the route with Starlette
         route = Route(path, endpoint=handler, methods=[method])
@@ -564,7 +525,9 @@ class Tachyon:
                     "description": "Validation Error",
                     "content": {
                         "application/json": {
-                            "schema": {"$ref": "#/components/schemas/ValidationErrorResponse"}
+                            "schema": {
+                                "$ref": "#/components/schemas/ValidationErrorResponse"
+                            }
                         }
                     },
                 },
@@ -572,7 +535,9 @@ class Tachyon:
                     "description": "Response Validation Error",
                     "content": {
                         "application/json": {
-                            "schema": {"$ref": "#/components/schemas/ResponseValidationError"}
+                            "schema": {
+                                "$ref": "#/components/schemas/ResponseValidationError"
+                            }
                         }
                     },
                 },
@@ -583,6 +548,7 @@ class Tachyon:
         response_model = kwargs.get("response_model")
         if response_model is not None and issubclass(response_model, Struct):
             from .openapi import build_components_for_struct
+
             comps = build_components_for_struct(response_model)
             for name, schema in comps.items():
                 self.openapi_generator.add_schema(name, schema)
@@ -639,6 +605,7 @@ class Tachyon:
                 model_class = param.annotation
                 if issubclass(model_class, Struct):
                     from .openapi import build_components_for_struct
+
                     comps = build_components_for_struct(model_class)
                     for name, schema in comps.items():
                         self.openapi_generator.add_schema(name, schema)

{tachyon_api-0.5.7 → tachyon_api-0.5.10}/tachyon_api/cache.py

@@ -11,12 +11,12 @@ Design notes:
 - Unless predicate allows opt-out per-call
 - TTL can be provided per-decorator or falls back to global default
 """
+
 from __future__ import annotations
 
 import time
 import asyncio
 import hashlib
-import inspect
 from dataclasses import dataclass
 from functools import wraps
 from typing import Any, Callable, Optional, Tuple
@@ -28,7 +28,9 @@ class BaseCacheBackend:
     def get(self, key: str) -> Any:  # pragma: no cover - interface
         raise NotImplementedError
 
-    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:  # pragma: no cover - interface
+    def set(
+        self, key: str, value: Any, ttl: Optional[float] = None
+    ) -> None:  # pragma: no cover - interface
         raise NotImplementedError
 
     def delete(self, key: str) -> None:  # pragma: no cover - interface
@@ -86,7 +88,9 @@ _cache_config: Optional[CacheConfig] = None
 def _default_key_builder(func: Callable, args: tuple, kwargs: dict) -> str:
     parts = [getattr(func, "__module__", ""), getattr(func, "__qualname__", ""), "|"]
     # Stable kwargs order
-    items = [repr(a) for a in args] + [f"{k}={repr(v)}" for k, v in sorted(kwargs.items())]
+    items = [repr(a) for a in args] + [
+        f"{k}={repr(v)}" for k, v in sorted(kwargs.items())
+    ]
     raw_key = ":".join(parts + items)
     return hashlib.sha256(raw_key.encode("utf-8")).hexdigest()
 
@@ -146,9 +150,14 @@ def cache(
         cfg = get_cache_config()
         be = backend or cfg.backend
         ttl_value = cfg.default_ttl if TTL is None else TTL
-        kb = key_builder or cfg.key_builder or (lambda f, a, kw: _default_key_builder(f, a, kw))
+        kb = (
+            key_builder
+            or cfg.key_builder
+            or (lambda f, a, kw: _default_key_builder(f, a, kw))
+        )
 
         if asyncio.iscoroutinefunction(func):
+
             @wraps(func)
             async def async_wrapper(*args, **kwargs):
                 if not cfg.enabled or (unless and unless(args, kwargs)):
@@ -167,6 +176,7 @@ def cache(
 
             return async_wrapper
         else:
+
             @wraps(func)
             def wrapper(*args, **kwargs):
                 if not cfg.enabled or (unless and unless(args, kwargs)):
@@ -258,4 +268,3 @@ class MemcachedCacheBackend(BaseCacheBackend):
             self.client.flush_all()
         except Exception:
             pass
-

{tachyon_api-0.5.7 → tachyon_api-0.5.10}/tachyon_api/middlewares/__init__.py

@@ -2,4 +2,3 @@ from .cors import CORSMiddleware
 from .logger import LoggerMiddleware
 
 __all__ = ["CORSMiddleware", "LoggerMiddleware"]
-

{tachyon_api-0.5.7 → tachyon_api-0.5.10}/tachyon_api/middlewares/cors.py

@@ -70,7 +70,8 @@ class CORSMiddleware:
         method = scope.get("method", "").upper()
         is_preflight = (
             method == "OPTIONS"
-            and self._get_header(req_headers, "access-control-request-method") is not None
+            and self._get_header(req_headers, "access-control-request-method")
+            is not None
         )
 
         # Build common CORS headers
@@ -89,7 +90,9 @@ class CORSMiddleware:
 
             # Credentials
             if self.allow_credentials:
-                self._append_header(headers_out, "access-control-allow-credentials", "true")
+                self._append_header(
+                    headers_out, "access-control-allow-credentials", "true"
+                )
 
             return headers_out
 
@@ -98,28 +101,42 @@ class CORSMiddleware:
             resp_headers = build_cors_headers()
             if resp_headers:
                 # Methods
-                allow_methods = ", ".join(self.allow_methods) if "*" not in self.allow_methods else "*"
-                self._append_header(resp_headers, "access-control-allow-methods", allow_methods)
+                allow_methods = (
+                    ", ".join(self.allow_methods)
+                    if "*" not in self.allow_methods
+                    else "*"
+                )
+                self._append_header(
+                    resp_headers, "access-control-allow-methods", allow_methods
+                )
 
                 # Requested headers or wildcard
-                req_acrh = self._get_header(req_headers, "access-control-request-headers")
+                req_acrh = self._get_header(
+                    req_headers, "access-control-request-headers"
+                )
                 if "*" in self.allow_headers:
                     allow_headers = req_acrh or "*"
                 else:
                     allow_headers = ", ".join(self.allow_headers)
                 if allow_headers:
-                    self._append_header(resp_headers, "access-control-allow-headers", allow_headers)
+                    self._append_header(
+                        resp_headers, "access-control-allow-headers", allow_headers
+                    )
 
                 # Max-Age
                 if self.max_age:
-                    self._append_header(resp_headers, "access-control-max-age", str(self.max_age))
+                    self._append_header(
+                        resp_headers, "access-control-max-age", str(self.max_age)
+                    )
 
                 # Respond directly
-                await send({
-                    "type": "http.response.start",
-                    "status": 200,
-                    "headers": resp_headers,
-                })
+                await send(
+                    {
+                        "type": "http.response.start",
+                        "status": 200,
+                        "headers": resp_headers,
+                    }
+                )
                 await send({"type": "http.response.body", "body": b""})
                 return
             # If origin not allowed, continue the chain (app will respond accordingly)

{tachyon_api-0.5.7 → tachyon_api-0.5.10}/tachyon_api/middlewares/logger.py

@@ -79,7 +79,9 @@ class LoggerMiddleware:
             receive_to_use = receive_passthrough
             if body_chunks and not more_body:
                 try:
-                    request_body_preview = b"".join(body_chunks)[:2048].decode("utf-8", "replace")
+                    request_body_preview = b"".join(body_chunks)[:2048].decode(
+                        "utf-8", "replace"
+                    )
                 except Exception:
                     request_body_preview = "<non-text body>"
         else:
@@ -113,7 +115,9 @@ class LoggerMiddleware:
         finally:
             duration = time.time() - start
             status = status_code_holder["status"] or 0
-            self.logger.log(self.level, f"<-- {method} {path} {status} ({duration:.4f}s)")
+            self.logger.log(
+                self.level, f"<-- {method} {path} {status} ({duration:.4f}s)"
+            )
             if self.include_headers and response_headers_holder:
                 res_headers = _normalized_headers(response_headers_holder)
                 self.logger.log(self.level, f"    res headers: {res_headers}")

{tachyon_api-0.5.7 → tachyon_api-0.5.10}/tachyon_api/openapi.py

@@ -3,6 +3,7 @@ from dataclasses import dataclass, field
 import datetime
 import uuid
 import typing
+import json
 
 from .models import Struct
 
@@ -97,7 +98,9 @@ def _generate_struct_schema(
     return schema
 
 
-def build_components_for_struct(struct_class: Type[Struct]) -> Dict[str, Dict[str, Any]]:
+def build_components_for_struct(
+    struct_class: Type[Struct],
+) -> Dict[str, Dict[str, Any]]:
     """
     Build components schemas for the given Struct and all nested Structs.
 
@@ -260,13 +263,8 @@ class OpenAPIGenerator:
         """Generate HTML for Swagger UI"""
         swagger_ui_parameters = self.config.swagger_ui_parameters or {}
 
-        # Convert parameters to JSON string, handling Python booleans correctly
-        params_json = (
-            str(swagger_ui_parameters)
-            .replace("'", '"')
-            .replace("True", "true")
-            .replace("False", "false")
-        )
+        # Serialize parameters to JSON safely
+        params_json = json.dumps(swagger_ui_parameters)
 
         html = f"""<!DOCTYPE html>
 <html>
@@ -287,7 +285,7 @@ class OpenAPIGenerator:
             SwaggerUIBundle.presets.standalone
         ],
         layout: "BaseLayout",
-        ...{{}}
+        ...{params_json}
     }})
     </script>
 </body>

{tachyon_api-0.5.7 → tachyon_api-0.5.10}/tachyon_api/responses.py

@@ -6,7 +6,6 @@ with Starlette responses.
 """
 
 from starlette.responses import JSONResponse, HTMLResponse  # noqa
-import orjson
 from .models import encode_json
 
 
@@ -63,7 +62,27 @@ def response_validation_error_response(error="Response validation error"):
     if not msg.lower().startswith("response validation error"):
         msg = f"Response validation error: {msg}"
     return TachyonJSONResponse(
-        {"success": False, "error": msg, "detail": msg, "code": "RESPONSE_VALIDATION_ERROR"},
+        {
+            "success": False,
+            "error": msg,
+            "detail": msg,
+            "code": "RESPONSE_VALIDATION_ERROR",
+        },
+        status_code=500,
+    )
+
+
+def internal_server_error_response():
+    """Create a 500 internal server error response for unhandled exceptions.
+
+    This intentionally avoids leaking internal exception details in the payload.
+    """
+    return TachyonJSONResponse(
+        {
+            "success": False,
+            "error": "Internal Server Error",
+            "code": "INTERNAL_SERVER_ERROR",
+        },
         status_code=500,
     )
 

tachyon_api-0.5.10/tachyon_api/utils/__init__.py

@@ -0,0 +1,14 @@
+"""
+Tachyon API - Utilities Module
+
+This package contains utility functions and classes that provide common functionality
+across the Tachyon framework, including type conversion, validation, and helper functions.
+"""
+
+from .type_utils import TypeUtils
+from .type_converter import TypeConverter
+
+__all__ = [
+    "TypeUtils",
+    "TypeConverter",
+]

tachyon_api-0.5.10/tachyon_api/utils/type_converter.py

@@ -0,0 +1,113 @@
+"""
+Tachyon API - Type Converter
+
+This module provides functionality for converting string values to appropriate Python types
+with proper error handling. Used primarily for converting URL parameters and query strings
+to typed values expected by endpoint functions.
+"""
+
+from typing import Type, Union, Any
+from starlette.responses import JSONResponse
+
+from ..responses import validation_error_response
+from .type_utils import TypeUtils
+
+
+class TypeConverter:
+    """
+    Handles conversion of string values to target Python types.
+
+    This class provides methods to convert string representations of values
+    (typically from URL parameters or query strings) to their appropriate
+    Python types with comprehensive error handling.
+    """
+
+    @staticmethod
+    def convert_value(
+        value_str: str,
+        target_type: Type,
+        param_name: str,
+        is_path_param: bool = False,
+    ) -> Union[Any, JSONResponse]:
+        """
+        Convert a string value to the target type with appropriate error handling.
+
+        This method handles type conversion for query and path parameters,
+        including special handling for boolean values and proper error responses.
+
+        Args:
+            value_str: The string value to convert
+            target_type: The target Python type to convert to
+            param_name: Name of the parameter (for error messages)
+            is_path_param: Whether this is a path parameter (affects error response)
+
+        Returns:
+            The converted value, or a JSONResponse with appropriate error code
+
+        Note:
+            - Boolean conversion accepts: "true", "1", "t", "yes" (case-insensitive)
+            - Path parameter errors return 404, query parameter errors return 422
+
+        Examples:
+            >>> TypeConverter.convert_value("123", int, "limit")
+            123
+            >>> TypeConverter.convert_value("true", bool, "active")
+            True
+            >>> TypeConverter.convert_value("invalid", int, "limit")
+            JSONResponse({"success": False, "error": "Invalid value for integer conversion", ...})
+        """
+        # Unwrap Optional/Union[T, None]
+        target_type, _ = TypeUtils.unwrap_optional(target_type)
+
+        try:
+            if target_type is bool:
+                return value_str.lower() in ("true", "1", "t", "yes")
+            elif target_type is not str:
+                return target_type(value_str)
+            else:
+                return value_str
+        except (ValueError, TypeError):
+            if is_path_param:
+                return JSONResponse({"detail": "Not Found"}, status_code=404)
+            else:
+                type_name = TypeUtils.get_type_name(target_type)
+                return validation_error_response(
+                    f"Invalid value for {type_name} conversion"
+                )
+
+    @staticmethod
+    def convert_list_values(
+        values: list[str], item_type: Type, param_name: str, is_path_param: bool = False
+    ) -> Union[list[Any], JSONResponse]:
+        """
+        Convert a list of string values to the target item type.
+
+        Args:
+            values: List of string values to convert
+            item_type: Target type for each item
+            param_name: Parameter name for error messages
+            is_path_param: Whether this is a path parameter
+
+        Returns:
+            List of converted values or error response
+        """
+        base_item_type, item_is_optional = TypeUtils.unwrap_optional(item_type)
+        converted_list = []
+
+        for value_str in values:
+            # Handle null/empty values for optional items
+            if item_is_optional and (value_str == "" or value_str.lower() == "null"):
+                converted_list.append(None)
+                continue
+
+            converted_value = TypeConverter.convert_value(
+                value_str, base_item_type, param_name, is_path_param
+            )
+
+            # If conversion failed, return the error response
+            if isinstance(converted_value, JSONResponse):
+                return converted_value
+
+            converted_list.append(converted_value)
+
+        return converted_list

tachyon_api-0.5.10/tachyon_api/utils/type_utils.py

@@ -0,0 +1,111 @@
+"""
+Tachyon API - Type Utilities
+
+This module provides utility functions for working with Python types,
+particularly for handling Optional types, Union types, and generic types
+used throughout the Tachyon framework.
+"""
+
+import typing
+from typing import Type, Tuple, Union
+
+
+class TypeUtils:
+    """
+    Utility class for type inspection and manipulation.
+
+    Provides static methods to analyze Python type annotations,
+    particularly useful for handling Optional[T], Union types,
+    and generic types in parameter processing.
+    """
+
+    @staticmethod
+    def unwrap_optional(python_type: Type) -> Tuple[Type, bool]:
+        """
+        Unwrap Optional[T] types to get the inner type and optionality flag.
+
+        This method analyzes a type annotation and determines if it represents
+        an Optional type (Union[T, None]). It returns the inner type and a
+        boolean indicating whether the type is optional.
+
+        Args:
+            python_type: The type annotation to analyze
+
+        Returns:
+            Tuple containing:
+            - inner_type: The unwrapped type (T from Optional[T])
+            - is_optional: Boolean indicating if the type was Optional
+
+        Examples:
+            >>> TypeUtils.unwrap_optional(Optional[str])
+            (str, True)
+            >>> TypeUtils.unwrap_optional(str)
+            (str, False)
+            >>> TypeUtils.unwrap_optional(Union[int, None])
+            (int, True)
+        """
+        origin = typing.get_origin(python_type)
+        args = typing.get_args(python_type)
+
+        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:
+                return non_none[0], True
+
+        return python_type, False
+
+    @staticmethod
+    def is_list_type(python_type: Type) -> Tuple[bool, Type]:
+        """
+        Check if a type is a List type and extract the item type.
+
+        Args:
+            python_type: The type annotation to check
+
+        Returns:
+            Tuple containing:
+            - is_list: Boolean indicating if the type is a List
+            - item_type: The type of list items (str if not a list or no args)
+
+        Examples:
+            >>> TypeUtils.is_list_type(List[str])
+            (True, str)
+            >>> TypeUtils.is_list_type(str)
+            (False, str)
+        """
+        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
+            return True, item_type
+
+        return False, str
+
+    @staticmethod
+    def get_type_name(python_type: Type) -> str:
+        """
+        Get a human-readable name for a type.
+
+        Args:
+            python_type: The type to get the name for
+
+        Returns:
+            Human-readable type name
+
+        Examples:
+            >>> TypeUtils.get_type_name(int)
+            'integer'
+            >>> TypeUtils.get_type_name(str)
+            'string'
+        """
+        if python_type is int:
+            return "integer"
+        elif python_type is str:
+            return "string"
+        elif python_type is bool:
+            return "boolean"
+        elif python_type is float:
+            return "number"
+        else:
+            return getattr(python_type, "__name__", str(python_type))