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

tachyon_api/__init__.py

@@ -13,12 +13,12 @@ the Free Software Foundation, either version 3 of the License.
 For more information, see the documentation and examples.
 """
 
-from .app import Tachyon
-from .models import Struct
-from .params import Query, Body, Path
-from .di import injectable, Depends
-from .router import Router
-from .cache import (
+from .core.app import Tachyon
+from .schemas.models import Struct
+from .schemas.parameters import Query, Body, Path
+from .dependencies.injection import injectable, Depends
+from .routing.router import Router
+from .features.cache import (
     cache,
     CacheConfig,
     create_cache_config,

tachyon_api/core/__init__.py

@@ -0,0 +1,7 @@
+"""
+Core Tachyon API components.
+"""
+
+from .app import Tachyon
+
+__all__ = ["Tachyon"]

tachyon_api/core/app.py

@@ -0,0 +1,355 @@
+"""
+Tachyon Web Framework - Main Application Module
+
+This module contains the core Tachyon class that provides a lightweight,
+FastAPI-inspired web framework with built-in dependency injection,
+parameter validation, and automatic type conversion.
+"""
+
+import inspect
+from functools import partial
+from typing import Any, Type, Callable
+
+from starlette.applications import Starlette
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from ..dependencies.injection import Depends, _registry
+from ..openapi.schema import (
+    OpenAPIGenerator,
+    OpenAPIConfig,
+    create_openapi_config,
+)
+from ..middlewares import create_decorated_middleware_class
+
+from ..dependencies.resolver import DependencyResolver
+from ..processing.parameters import ParameterProcessor, _NotProcessed
+from ..processing.responses import ResponseProcessor
+from ..openapi.builder import OpenAPIBuilder
+from ..routing.routes import TachyonRouter
+
+try:
+    from ..features.cache import set_cache_config
+except ImportError:
+    set_cache_config = None  # type: ignore
+
+
+class Tachyon:
+    """
+    Main Tachyon application class.
+
+    Provides a web framework with automatic parameter validation, dependency injection,
+    and type conversion. Built on top of Starlette for ASGI compatibility.
+
+    Attributes:
+        _router: Internal Starlette application instance
+        routes: List of registered routes for introspection
+        _instances_cache: Cache for dependency injection singleton instances
+        openapi_config: Configuration for OpenAPI documentation
+        openapi_generator: Generator for OpenAPI schema and documentation
+    """
+
+    def __init__(self, openapi_config: OpenAPIConfig = None, cache_config=None):
+        """
+        Initialize a new Tachyon application instance.
+
+        Args:
+            openapi_config: Optional OpenAPI configuration. If not provided,
+                          uses default configuration similar to FastAPI.
+            cache_config: Optional cache configuration (tachyon_api.cache.CacheConfig).
+                          If provided, it will be set as the active cache configuration.
+        """
+        # Create dependency resolver and router
+        self._dependency_resolver = DependencyResolver()
+        self._tachyon_router = TachyonRouter(self._dependency_resolver)
+
+        # Create Starlette app with our routes
+        self._router = Starlette(routes=self._tachyon_router.get_starlette_routes())
+        self.routes = []
+
+        # Initialize OpenAPI configuration and generator
+        self.openapi_config = openapi_config or create_openapi_config()
+        self.openapi_generator = OpenAPIGenerator(self.openapi_config)
+        self._openapi_builder = OpenAPIBuilder(
+            self.openapi_config, self.openapi_generator
+        )
+        self._docs_setup = False
+
+        # Apply cache configuration if provided
+        self.cache_config = cache_config
+        if cache_config is not None and set_cache_config is not None:
+            try:
+                set_cache_config(cache_config)
+            except Exception:
+                # Do not break app initialization if cache setup fails
+                pass
+
+        # Dynamically create HTTP method decorators (get, post, put, delete, etc.)
+        http_methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"]
+
+        for method in http_methods:
+            setattr(
+                self,
+                method.lower(),
+                partial(self._create_decorator, http_method=method),
+            )
+
+    def _resolve_dependency(self, cls: Type) -> Any:
+        """
+        Resolve a dependency using the dependency resolver.
+
+        This is a convenience method that delegates to the DependencyResolver instance.
+
+        Args:
+            cls: The class type to resolve and instantiate
+
+        Returns:
+            An instance of the requested class with all dependencies resolved
+        """
+        return self._dependency_resolver.resolve_dependency(cls)
+
+    def _add_route(self, path: str, endpoint_func: Callable, method: str, **kwargs):
+        """
+        Register a route with the application.
+
+        This method now uses the Starlette-native TachyonRouter for better
+        compatibility with future Starlette/Rust versions.
+
+        Args:
+            path: URL path pattern (e.g., "/users/{user_id}")
+            endpoint_func: The endpoint function to handle requests
+            method: HTTP method (GET, POST, PUT, DELETE, etc.)
+            **kwargs: Additional route metadata
+        """
+        # Add route to our Tachyon router
+        route = self._tachyon_router.add_route(
+            path=path, endpoint=endpoint_func, methods=[method], **kwargs
+        )
+
+        # Store route info for backward compatibility and OpenAPI generation
+        self.routes.append(route.get_endpoint_info())
+
+        # Generate OpenAPI documentation for this route
+        include_in_schema = kwargs.get("include_in_schema", True)
+        if include_in_schema:
+            self._openapi_builder.generate_openapi_for_route(
+                path, method, endpoint_func, **kwargs
+            )
+
+    def _create_decorator(self, path: str, *, http_method: str, **kwargs):
+        """
+        Create a decorator for the specified HTTP method.
+
+        This factory method creates method-specific decorators (e.g., @app.get, @app.post)
+        that register endpoint functions with the application.
+
+        Args:
+            path: URL path pattern (supports path parameters with {param} syntax)
+            http_method: HTTP method name (GET, POST, PUT, DELETE, etc.)
+
+        Returns:
+            A decorator function that registers the endpoint
+        """
+
+        def decorator(endpoint_func: Callable):
+            self._add_route(path, endpoint_func, http_method, **kwargs)
+            return endpoint_func
+
+        return decorator
+
+    def _add_route(self, path: str, endpoint_func: Callable, method: str, **kwargs):
+        """
+        Register a route with the application and create an async handler.
+
+        This is the core method that handles parameter injection, validation, and
+        type conversion. It creates an async handler that processes requests and
+        automatically injects dependencies, path parameters, query parameters, and
+        request body data into the endpoint function.
+
+        Args:
+            path: URL path pattern (e.g., "/users/{user_id}")
+            endpoint_func: The endpoint function to handle requests
+            method: HTTP method (GET, POST, PUT, DELETE, etc.)
+
+        Note:
+            The created handler processes parameters in the following order:
+            1. Dependencies (explicit with Depends() or implicit via @injectable)
+            2. Body parameters (JSON request body validated against Struct models)
+            3. Query parameters (URL query string with type conversion)
+            4. Path parameters (both explicit with Path() and implicit from URL)
+        """
+
+        response_model = kwargs.get("response_model")
+
+        async def handler(request):
+            """
+            Async request handler that processes parameters and calls the endpoint.
+
+            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
+                    )
+                    continue
+
+                # Process other parameter types using ParameterProcessor
+                result = await ParameterProcessor.process_parameter(
+                    param,
+                    request,
+                    path_params,
+                    query_params,
+                    _raw_body,
+                    is_explicit_dependency,
+                    is_implicit_dependency,
+                )
+
+                # If parameter was processed and returned a value/error, handle it
+                if not isinstance(result, _NotProcessed):
+                    if isinstance(result, JSONResponse):
+                        return result  # Error response
+                    kwargs_to_inject[param.name] = result
+
+            # Process the response using ResponseProcessor
+            return await ResponseProcessor.process_response(
+                endpoint_func, kwargs_to_inject, response_model
+            )
+
+        # Register the route with Starlette
+        route = Route(path, endpoint=handler, methods=[method])
+        self._router.routes.append(route)
+        self.routes.append(
+            {"path": path, "method": method, "func": endpoint_func, **kwargs}
+        )
+
+        # Generate OpenAPI documentation for this route
+        include_in_schema = kwargs.get("include_in_schema", True)
+        if include_in_schema:
+            self._openapi_builder.generate_openapi_for_route(
+                path, method, endpoint_func, **kwargs
+            )
+
+    def _setup_docs(self):
+        """
+        Setup OpenAPI documentation endpoints.
+
+        This method registers the routes for serving OpenAPI JSON schema,
+        Swagger UI, and ReDoc documentation interfaces.
+        """
+        if self._docs_setup:
+            return
+
+        self._docs_setup = True
+        self._openapi_builder.setup_docs(self)
+
+    async def __call__(self, scope, receive, send):
+        """
+        ASGI application entry point.
+
+        Delegates request handling to the internal Starlette application.
+        This makes Tachyon compatible with ASGI servers like Uvicorn.
+        """
+        # Setup documentation endpoints on first request
+        if not self._docs_setup:
+            self._setup_docs()
+        await self._router(scope, receive, send)
+
+    def include_router(self, router, **kwargs):
+        """
+        Include a Router instance in the application.
+
+        This method registers all routes from the router with the main application,
+        applying the router's prefix, tags, and dependencies.
+
+        Args:
+            router: The Router instance to include
+            **kwargs: Additional options (currently reserved for future use)
+        """
+        from ..routing.router import Router
+
+        if not isinstance(router, Router):
+            raise TypeError("Expected Router instance")
+
+        # Register all routes from the router
+        for route_info in router.routes:
+            # Get the full path with prefix
+            full_path = router.get_full_path(route_info["path"])
+
+            # Create a copy of route info with the full path
+            route_kwargs = route_info.copy()
+            route_kwargs.pop("path", None)
+            route_kwargs.pop("method", None)
+            route_kwargs.pop("func", None)
+
+            # Register the route with the main app
+            self._add_route(
+                full_path, route_info["func"], route_info["method"], **route_kwargs
+            )
+
+    def add_middleware(self, middleware_class, **options):
+        """
+        Add a middleware to the Starlette application.
+
+        This method directly uses Starlette's native middleware API for maximum
+        compatibility with future Starlette/Rust versions.
+
+        Args:
+            middleware_class: The middleware class.
+            **options: Options to be passed to the middleware constructor.
+        """
+        # Use Starlette's native middleware API directly
+        self._router.add_middleware(middleware_class, **options)
+
+    def middleware(self, middleware_type="http"):
+        """
+        Decorator for adding a middleware to the application.
+        Similar to route decorators (@app.get, etc.)
+
+        Args:
+            middleware_type: Type of middleware ('http' by default)
+
+        Returns:
+            A decorator that registers the decorated function as middleware.
+        """
+
+        def decorator(middleware_func):
+            # Create a middleware class from the decorated function
+            DecoratedMiddleware = create_decorated_middleware_class(
+                middleware_func, middleware_type
+            )
+            # Register the middleware using Starlette's native API
+            self.add_middleware(DecoratedMiddleware)
+            return middleware_func
+
+        return decorator
+
+    @property
+    def middleware_stack(self):
+        """
+        Get the current middleware stack for introspection.
+
+        This property provides access to Starlette's middleware stack for
+        debugging and testing purposes.
+
+        Returns:
+            List of middleware classes configured on the Starlette app
+        """
+        return getattr(self._router, "user_middleware", [])

tachyon_api/dependencies/__init__.py

@@ -0,0 +1,8 @@
+"""
+Tachyon API dependency injection system.
+"""
+
+from .injection import injectable, Depends, _registry
+from .resolver import DependencyResolver
+
+__all__ = ["injectable", "Depends", "_registry", "DependencyResolver"]

tachyon_api/dependencies/resolver.py

@@ -0,0 +1,78 @@
+"""
+Dependency Injection System for Tachyon API
+
+This module handles the resolution and injection of dependencies for the Tachyon framework.
+It provides both explicit and implicit dependency injection capabilities.
+"""
+
+from typing import Any, Type, Dict
+import inspect
+
+from .injection import _registry
+
+
+class DependencyResolver:
+    """
+    Handles dependency resolution and injection for the Tachyon framework.
+
+    This class implements a singleton pattern for dependency caching and supports
+    both @injectable decorated classes and simple classes for dependency injection.
+    """
+
+    def __init__(self):
+        """Initialize the dependency resolver with an empty cache."""
+        self._instances_cache: Dict[Type, Any] = {}
+
+    def resolve_dependency(self, cls: Type) -> Any:
+        """
+        Resolve a dependency and its sub-dependencies recursively.
+
+        This method implements dependency injection with singleton pattern,
+        automatically resolving constructor dependencies and caching instances.
+
+        Args:
+            cls: The class type to resolve and instantiate
+
+        Returns:
+            An instance of the requested class with all dependencies resolved
+
+        Raises:
+            TypeError: If the class cannot be instantiated or is not marked as injectable
+
+        Note:
+            - Uses singleton pattern - instances are cached and reused
+            - Supports both @injectable decorated classes and simple classes
+            - Recursively resolves constructor dependencies
+        """
+        # Return cached instance if available (singleton pattern)
+        if cls in self._instances_cache:
+            return self._instances_cache[cls]
+
+        # For non-injectable classes, try to create without arguments
+        if cls not in _registry:
+            try:
+                # Works for classes without __init__ or with no-arg __init__
+                return cls()
+            except TypeError:
+                raise TypeError(
+                    f"Cannot resolve dependency '{cls.__name__}'. "
+                    f"Did you forget to mark it with @injectable?"
+                )
+
+        # For injectable classes, resolve constructor dependencies
+        sig = inspect.signature(cls)
+        dependencies = {}
+
+        # Recursively resolve each constructor parameter
+        for param in sig.parameters.values():
+            if param.name != "self":
+                dependencies[param.name] = self.resolve_dependency(param.annotation)
+
+        # Create instance with resolved dependencies and cache it
+        instance = cls(**dependencies)
+        self._instances_cache[cls] = instance
+        return instance
+
+    def clear_cache(self):
+        """Clear the dependency cache. Useful for testing."""
+        self._instances_cache.clear()

tachyon_api/features/__init__.py

@@ -0,0 +1,30 @@
+"""
+Tachyon API features and extensions.
+"""
+
+try:
+    from .cache import (
+        cache,
+        CacheConfig,
+        create_cache_config,
+        set_cache_config,
+        get_cache_config,
+        InMemoryCacheBackend,
+        BaseCacheBackend,
+        RedisCacheBackend,
+        MemcachedCacheBackend,
+    )
+
+    __all__ = [
+        "cache",
+        "CacheConfig",
+        "create_cache_config",
+        "set_cache_config",
+        "get_cache_config",
+        "InMemoryCacheBackend",
+        "BaseCacheBackend",
+        "RedisCacheBackend",
+        "MemcachedCacheBackend",
+    ]
+except ImportError:
+    __all__ = []

tachyon_api/middlewares/__init__.py

@@ -1,4 +1,16 @@
+"""
+Tachyon API middleware system.
+"""
+
+from .manager import StarletteMiddlewareManager, MiddlewareManager
+from .core import create_decorated_middleware_class
 from .cors import CORSMiddleware
 from .logger import LoggerMiddleware
 
-__all__ = ["CORSMiddleware", "LoggerMiddleware"]
+__all__ = [
+    "StarletteMiddlewareManager",
+    "MiddlewareManager",
+    "create_decorated_middleware_class",
+    "CORSMiddleware",
+    "LoggerMiddleware",
+]

tachyon_api/middlewares/manager.py

@@ -0,0 +1,70 @@
+"""
+Starlette-Native Middleware Management for Tachyon API
+
+This module provides middleware management that closely follows Starlette's patterns
+while maintaining backward compatibility with existing Tachyon functionality.
+"""
+
+from typing import Type
+from starlette.applications import Starlette
+
+from .core import create_decorated_middleware_class
+
+
+class StarletteMiddlewareManager:
+    """
+    Starlette-native middleware manager that follows Starlette's patterns.
+
+    This manager provides a thin wrapper around Starlette's middleware system
+    while maintaining compatibility with Tachyon's decorator-based middleware.
+    """
+
+    def __init__(self, router: Starlette):
+        """
+        Initialize the middleware manager.
+
+        Args:
+            router: The Starlette application instance to apply middlewares to
+        """
+        self._router = router
+
+    def add_middleware(self, middleware_class: Type, **options):
+        """
+        Add a middleware to the Starlette application.
+
+        This method directly uses Starlette's middleware API for maximum compatibility
+        with future Starlette/Rust versions.
+
+        Args:
+            middleware_class: The middleware class.
+            **options: Options to be passed to the middleware constructor.
+        """
+        # Use Starlette's native middleware API
+        self._router.add_middleware(middleware_class, **options)
+
+    def middleware(self, middleware_type: str = "http"):
+        """
+        Decorator for adding a middleware to the application.
+        Similar to route decorators (@app.get, etc.)
+
+        Args:
+            middleware_type: Type of middleware ('http' by default)
+
+        Returns:
+            A decorator that registers the decorated function as middleware.
+        """
+
+        def decorator(middleware_func):
+            # Create a middleware class from the decorated function
+            DecoratedMiddleware = create_decorated_middleware_class(
+                middleware_func, middleware_type
+            )
+            # Register the middleware using Starlette's native API
+            self.add_middleware(DecoratedMiddleware)
+            return middleware_func
+
+        return decorator
+
+
+# Backward compatibility alias
+MiddlewareManager = StarletteMiddlewareManager

tachyon_api/openapi/__init__.py

@@ -0,0 +1,27 @@
+"""
+Tachyon API OpenAPI documentation system.
+"""
+
+from .builder import OpenAPIBuilder
+from .schema import (
+    OpenAPIGenerator,
+    OpenAPIConfig,
+    create_openapi_config,
+    build_components_for_struct,
+    Info,
+    Contact,
+    License,
+    Server,
+)
+
+__all__ = [
+    "OpenAPIBuilder",
+    "OpenAPIGenerator",
+    "OpenAPIConfig",
+    "create_openapi_config",
+    "build_components_for_struct",
+    "Info",
+    "Contact",
+    "License",
+    "Server",
+]