tachyon-api 0.5.5__py3-none-any.whl

tachyon_api/openapi.py

@@ -0,0 +1,362 @@
+from typing import Dict, Any, Optional, List, Type
+from dataclasses import dataclass, field
+
+from .models import Struct
+
+# Type mapping from Python types to OpenAPI schema types
+TYPE_MAP = {int: "integer", str: "string", bool: "boolean", float: "number"}
+
+
+def _generate_schema_for_struct(struct_class: Type[Struct]) -> Dict[str, Any]:
+    """
+    Generate a JSON Schema dictionary from a tachyon_api.models.Struct.
+
+    Args:
+        struct_class: The Struct class to generate schema for
+
+    Returns:
+        Dictionary containing the OpenAPI schema for the struct
+    """
+    properties = {}
+    required = []
+
+    # Use msgspec's introspection tools
+    for field_name in struct_class.__struct_fields__:
+        field_type = struct_class.__annotations__.get(field_name)
+        properties[field_name] = {
+            "type": TYPE_MAP.get(field_type, "string"),
+            "title": field_name.replace("_", " ").title(),
+        }
+        # For now, assume all fields are required (can be enhanced later)
+        required.append(field_name)
+
+    return {"type": "object", "properties": properties, "required": required}
+
+
+@dataclass
+class Contact:
+    """Contact information for the API"""
+
+    name: Optional[str] = None
+    url: Optional[str] = None
+    email: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to OpenAPI contact object"""
+        result = {}
+        if self.name:
+            result["name"] = self.name
+        if self.url:
+            result["url"] = self.url
+        if self.email:
+            result["email"] = self.email
+        return result
+
+
+@dataclass
+class License:
+    """License information for the API"""
+
+    name: str
+    url: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to OpenAPI license object"""
+        result = {"name": self.name}
+        if self.url:
+            result["url"] = self.url
+        return result
+
+
+@dataclass
+class Info:
+    """General information about the API"""
+
+    title: str = "Tachyon API"
+    description: Optional[str] = "A fast API built with Tachyon"
+    version: str = "0.1.0"
+    terms_of_service: Optional[str] = None
+    contact: Optional[Contact] = None
+    license: Optional[License] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to OpenAPI info object"""
+        result: Dict[str, Any] = {"title": self.title, "version": self.version}
+        if self.description:
+            result["description"] = self.description
+        if self.terms_of_service:
+            result["termsOfService"] = self.terms_of_service
+        if self.contact:
+            result["contact"] = self.contact.to_dict()
+        if self.license:
+            result["license"] = self.license.to_dict()
+        return result
+
+
+@dataclass
+class Server:
+    """Server information"""
+
+    url: str
+    description: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to OpenAPI server object"""
+        result = {"url": self.url}
+        if self.description:
+            result["description"] = self.description
+        return result
+
+
+@dataclass
+class OpenAPIConfig:
+    """Configuration for OpenAPI/Swagger documentation"""
+
+    info: Info = field(default_factory=Info)
+    servers: List[Server] = field(default_factory=list)
+    openapi_version: str = "3.0.0"
+    docs_url: str = "/docs"
+    redoc_url: str = "/redoc"
+    openapi_url: str = "/openapi.json"
+    include_in_schema: bool = True
+    # Scalar configuration
+    scalar_js_url: str = "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
+    scalar_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png"
+    # Swagger UI configuration (legacy support)
+    swagger_ui_oauth2_redirect_url: Optional[str] = None
+    swagger_ui_init_oauth: Optional[Dict[str, Any]] = None
+    swagger_ui_parameters: Optional[Dict[str, Any]] = None
+    swagger_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png"
+    swagger_js_url: str = (
+        "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"
+    )
+    swagger_css_url: str = (
+        "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css"
+    )
+    redoc_js_url: str = (
+        "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"
+    )
+
+    def to_openapi_dict(self) -> Dict[str, Any]:
+        """Generate the complete OpenAPI dictionary"""
+        openapi_dict = {
+            "openapi": self.openapi_version,
+            "info": self.info.to_dict(),
+            "paths": {},
+            "components": {"schemas": {}},
+        }
+
+        if self.servers:
+            openapi_dict["servers"] = [server.to_dict() for server in self.servers]
+
+        return openapi_dict
+
+
+class OpenAPIGenerator:
+    """Generator for OpenAPI documentation"""
+
+    def __init__(self, config: Optional[OpenAPIConfig] = None):
+        """
+        Initialize the OpenAPI generator.
+
+        Args:
+            config: Optional OpenAPI configuration. Uses defaults if not provided.
+        """
+        self.config = config or OpenAPIConfig()
+        self._openapi_schema: Optional[Dict[str, Any]] = None
+
+    def get_openapi_schema(self) -> Dict[str, Any]:
+        """Get the complete OpenAPI schema"""
+        if self._openapi_schema is None:
+            self._openapi_schema = self.config.to_openapi_dict()
+        return self._openapi_schema
+
+    def get_swagger_ui_html(self, openapi_url: str, title: str) -> str:
+        """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")
+        )
+
+        html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <link type="text/css" rel="stylesheet" href="{self.config.swagger_css_url}">
+    <link rel="shortcut icon" href="{self.config.swagger_favicon_url}">
+    <title>{title}</title>
+</head>
+<body>
+    <div id="swagger-ui"></div>
+    <script src="{self.config.swagger_js_url}"></script>
+    <script>
+    const ui = SwaggerUIBundle({{
+        url: '{openapi_url}',
+        dom_id: '#swagger-ui',
+        presets: [
+            SwaggerUIBundle.presets.apis,
+            SwaggerUIBundle.presets.standalone
+        ],
+        layout: "BaseLayout",
+        ...{params_json}
+    }})
+    </script>
+</body>
+</html>"""
+        return html
+
+    def get_redoc_html(self, openapi_url: str, title: str) -> str:
+        """Generate HTML for ReDoc"""
+        html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <title>{title}</title>
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+    <style>
+    body {{
+        margin: 0;
+        padding: 0;
+    }}
+    </style>
+</head>
+<body>
+    <redoc spec-url='{openapi_url}'></redoc>
+    <script src="{self.config.redoc_js_url}"></script>
+</body>
+</html>"""
+        return html
+
+    def get_scalar_html(self, openapi_url: str, title: str) -> str:
+        """Generate HTML for Scalar API Reference"""
+        html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <title>{title}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="shortcut icon" href="{self.config.scalar_favicon_url}">
+    <style>
+        body {{
+            margin: 0;
+            padding: 0;
+        }}
+    </style>
+</head>
+<body>
+    <script
+        id="api-reference"
+        data-url="{openapi_url}"
+        src="{self.config.scalar_js_url}"></script>
+</body>
+</html>"""
+        return html
+
+    def add_path(self, path: str, method: str, operation_data: Dict[str, Any]) -> None:
+        """
+        Add a path operation to the OpenAPI schema.
+
+        Args:
+            path: The URL path (e.g., "/items/{item_id}")
+            method: HTTP method (e.g., "get", "post")
+            operation_data: OpenAPI operation object
+        """
+        if self._openapi_schema is None:
+            self._openapi_schema = self.config.to_openapi_dict()
+
+        if path not in self._openapi_schema["paths"]:
+            self._openapi_schema["paths"][path] = {}
+
+        self._openapi_schema["paths"][path][method.lower()] = operation_data
+
+    def add_schema(self, name: str, schema_data: Dict[str, Any]) -> None:
+        """
+        Add a component schema to the OpenAPI specification.
+
+        Args:
+            name: Schema name (e.g., "Item", "User")
+            schema_data: OpenAPI schema object
+        """
+        if self._openapi_schema is None:
+            self._openapi_schema = self.config.to_openapi_dict()
+
+        self._openapi_schema["components"]["schemas"][name] = schema_data
+
+
+def create_openapi_config(
+    title: str = "Tachyon API",
+    description: Optional[str] = "A fast API built with Tachyon",
+    version: str = "0.1.0",
+    openapi_version: str = "3.0.0",
+    docs_url: str = "/docs",
+    redoc_url: str = "/redoc",
+    openapi_url: str = "/openapi.json",
+    contact: Optional[Contact] = None,
+    license: Optional[License] = None,
+    servers: Optional[List[Server]] = None,
+    terms_of_service: Optional[str] = None,
+    # Scalar configuration
+    scalar_js_url: str = "https://cdn.jsdelivr.net/npm/@scalar/api-reference",
+    scalar_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
+    # Swagger UI configuration (legacy support)
+    swagger_ui_parameters: Optional[Dict[str, Any]] = None,
+    swagger_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
+    swagger_js_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
+    swagger_css_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
+    redoc_js_url: str = "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js",
+) -> OpenAPIConfig:
+    """
+    Create a customizable OpenAPI configuration similar to FastAPI.
+
+    Args:
+        title: API title
+        description: API description
+        version: API version
+        openapi_version: OpenAPI specification version
+        docs_url: URL for Scalar API Reference documentation (default)
+        redoc_url: URL for ReDoc documentation
+        openapi_url: URL for OpenAPI JSON schema
+        contact: Contact information
+        license: License information
+        servers: List of servers
+        terms_of_service: Terms of service URL
+        scalar_js_url: Scalar API Reference JavaScript URL
+        scalar_favicon_url: Favicon URL for Scalar
+        swagger_ui_parameters: Additional Swagger UI parameters
+        swagger_favicon_url: Favicon URL for Swagger UI
+        swagger_js_url: Swagger UI JavaScript URL
+        swagger_css_url: Swagger UI CSS URL
+        redoc_js_url: ReDoc JavaScript URL
+
+    Returns:
+        Configured OpenAPIConfig instance
+    """
+    info = Info(
+        title=title,
+        description=description,
+        version=version,
+        terms_of_service=terms_of_service,
+        contact=contact,
+        license=license,
+    )
+
+    return OpenAPIConfig(
+        info=info,
+        servers=servers or [],
+        openapi_version=openapi_version,
+        docs_url=docs_url,
+        redoc_url=redoc_url,
+        openapi_url=openapi_url,
+        scalar_js_url=scalar_js_url,
+        scalar_favicon_url=scalar_favicon_url,
+        swagger_ui_parameters=swagger_ui_parameters,
+        swagger_favicon_url=swagger_favicon_url,
+        swagger_js_url=swagger_js_url,
+        swagger_css_url=swagger_css_url,
+        redoc_js_url=redoc_js_url,
+    )

tachyon_api/params.py

@@ -0,0 +1,90 @@
+"""
+Tachyon Web Framework - Parameter Definition Module
+
+This module provides parameter marker classes for defining how endpoint function
+parameters should be resolved from HTTP requests (query strings, path variables,
+and request bodies).
+"""
+
+from typing import Any, Optional
+
+
+class Query:
+    """
+    Marker class for query string parameters.
+
+    Use this to define parameters that should be extracted from the URL query string
+    with optional default values and automatic type conversion.
+
+    Args:
+        default: Default value if parameter is not provided. Use ... for required parameters.
+        description: Optional description for OpenAPI documentation.
+
+    Example:
+        @app.get("/search")
+        def search(
+            q: str = Query(...),        # Required query parameter
+            limit: int = Query(10),     # Optional with default value
+            active: bool = Query(False) # Optional boolean parameter
+        ):
+            return {"query": q, "limit": limit, "active": active}
+
+    Note:
+        - Boolean parameters accept: "true", "1", "t", "yes" (case-insensitive) as True
+        - Type conversion is automatic based on parameter annotation
+        - Missing required parameters return 422 Unprocessable Entity
+        - Invalid type conversions return 422 Unprocessable Entity
+    """
+
+    def __init__(self, default: Any = ..., description: Optional[str] = None):
+        """
+        Initialize a Query parameter marker.
+
+        Args:
+            default: Default value for the parameter. Use ... (Ellipsis) for required parameters.
+            description: Optional description for API documentation.
+        """
+        self.default = default
+        self.description = description
+
+
+class Path:
+    """
+    Marker class for path parameters.
+
+    Use this to define parameters that should be extracted from the URL path.
+    Path parameters are always required.
+
+    Args:
+        description: Optional description for OpenAPI documentation.
+    """
+
+    def __init__(self, description: Optional[str] = None):
+        """
+        Initialize a Path parameter marker.
+
+        Args:
+            description: Optional description for API documentation.
+        """
+        self.description = description
+
+
+class Body:
+    """
+    Marker class for request body parameters.
+
+    Use this to define parameters that should be extracted and validated from
+    the JSON request body. The parameter type should be a Struct subclass.
+
+    Args:
+        description: Optional description for OpenAPI documentation.
+    """
+
+    def __init__(self, description: Optional[str] = None):
+        """
+        Initialize a Body parameter marker.
+
+        Args:
+            description: Optional description for API documentation.
+        """
+        self.description = description

tachyon_api/responses.py

@@ -0,0 +1,49 @@
+"""
+Simple response helpers for Tachyon API
+
+Provides convenient response helpers while keeping full compatibility
+with Starlette responses.
+"""
+
+from starlette.responses import JSONResponse, HTMLResponse  # noqa
+
+
+# Simple helper functions for common response patterns
+def success_response(data=None, message="Success", status_code=200):
+    """Create a success response with consistent structure"""
+    return JSONResponse(
+        {"success": True, "message": message, "data": data}, status_code=status_code
+    )
+
+
+def error_response(error, status_code=400, code=None):
+    """Create an error response with consistent structure"""
+    response_data = {"success": False, "error": error}
+    if code:
+        response_data["code"] = code
+
+    return JSONResponse(response_data, status_code=status_code)
+
+
+def not_found_response(error="Resource not found"):
+    """Create a 404 not found response"""
+    return error_response(error, status_code=404, code="NOT_FOUND")
+
+
+def conflict_response(error="Resource conflict"):
+    """Create a 409 conflict response"""
+    return error_response(error, status_code=409, code="CONFLICT")
+
+
+def validation_error_response(error="Validation failed", errors=None):
+    """Create a 422 validation error response"""
+    response_data = {"success": False, "error": error, "code": "VALIDATION_ERROR"}
+    if errors:
+        response_data["errors"] = errors
+
+    return JSONResponse(response_data, status_code=422)
+
+
+# Re-export Starlette responses for convenience
+# JSONResponse is already imported above
+# HTMLResponse is now also imported

tachyon_api/router.py

@@ -0,0 +1,129 @@
+"""
+Tachyon Router Module
+
+Provides route grouping functionality similar to FastAPI's APIRouter,
+allowing for better organization of routes with common prefixes, tags, and dependencies.
+"""
+
+from functools import partial
+from typing import List, Optional, Any, Callable, Dict
+
+from .di import Depends
+
+
+class Router:
+    """
+    Router class for grouping related routes with common configuration.
+
+    Similar to FastAPI's APIRouter, allows grouping routes with:
+    - Common prefixes
+    - Common tags
+    - Common dependencies
+    - Better organization of related endpoints
+
+    Note: Router stores route definitions but doesn't implement the actual routing logic.
+    The routing logic is handled by the main Tachyon app when the router is included.
+    """
+
+    def __init__(
+        self,
+        prefix: str = "",
+        tags: Optional[List[str]] = None,
+        dependencies: Optional[List[Depends]] = None,
+        responses: Optional[Dict[int, Dict[str, Any]]] = None,
+    ):
+        """
+        Initialize a new Router instance.
+
+        Args:
+            prefix: Common prefix for all routes in this router
+            tags: List of tags to apply to all routes
+            dependencies: List of dependencies to apply to all routes
+            responses: Common responses for OpenAPI documentation
+        """
+        # Normalize prefix - ensure it starts with / if not empty
+        if prefix and not prefix.startswith("/"):
+            prefix = "/" + prefix
+        elif prefix is None:
+            prefix = ""
+
+        self.prefix = prefix
+        self.tags = tags or []
+        self.dependencies = dependencies or []
+        self.responses = responses or {}
+        self.routes: List[Dict[str, Any]] = []
+
+        # Create HTTP method decorators using the same pattern as Tachyon
+        http_methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"]
+        for method in http_methods:
+            setattr(
+                self,
+                method.lower(),
+                partial(self._create_route_decorator, http_method=method),
+            )
+
+    def _create_route_decorator(self, path: str, *, http_method: str, **kwargs):
+        """
+        Create a decorator for the specified HTTP method.
+
+        This method is similar to Tachyon's _create_decorator but stores routes
+        instead of registering them immediately.
+
+        Args:
+            path: URL path pattern (will be prefixed with router prefix)
+            http_method: HTTP method name (GET, POST, PUT, DELETE, etc.)
+            **kwargs: Additional route options (summary, description, tags, etc.)
+
+        Returns:
+            A decorator function that stores the endpoint with the router
+        """
+
+        def decorator(endpoint_func: Callable):
+            # Combine router tags with route-specific tags
+            route_tags = list(self.tags)  # Start with router tags
+            if "tags" in kwargs:
+                if isinstance(kwargs["tags"], list):
+                    route_tags.extend(kwargs["tags"])
+                else:
+                    route_tags.append(kwargs["tags"])
+
+            # Update kwargs with combined tags
+            if route_tags:
+                kwargs["tags"] = route_tags
+
+            # Store the route information for later registration
+            route_info = {
+                "path": path,
+                "method": http_method,
+                "func": endpoint_func,
+                "dependencies": self.dependencies.copy(),
+                **kwargs,
+            }
+
+            self.routes.append(route_info)
+            return endpoint_func
+
+        return decorator
+
+    def get_full_path(self, path: str) -> str:
+        """
+        Get the full path by combining router prefix with route path.
+
+        Args:
+            path: The route path
+
+        Returns:
+            Full path with prefix applied
+        """
+        if not self.prefix:
+            return path
+
+        # Handle root path specially
+        if path == "/":
+            return self.prefix
+
+        # Combine prefix and path, avoiding double slashes
+        if path.startswith("/"):
+            return self.prefix + path
+        else:
+            return self.prefix + "/" + path

tachyon_api-0.5.5.dist-info/LICENSE

@@ -0,0 +1,17 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2025 Juan Manuel Panozzo Zénere
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.