Buckets:

download
raw
43.1 kB
""" Main Zenith class - the entry point for creating Zenith applications. Combines the power of: - FastAPI-style routing and dependency injection - Service-based architecture for business logic - Modern Python patterns and developer experience """ import logging from contextlib import asynccontextmanager from pathlib import Path from typing import Any from starlette.applications import Starlette from starlette.middleware import Middleware from uvicorn import run from zenith.core.application import Application from zenith.core.config import Config from zenith.core.routing import Router from zenith.http.client import HTTPClientMixin from zenith.mixins import DocsMixin, MiddlewareMixin, RoutingMixin, ServicesMixin class Zenith(MiddlewareMixin, RoutingMixin, DocsMixin, ServicesMixin, HTTPClientMixin): """ Main Zenith application class. The high-level API for creating Zenith applications with: - FastAPI-style decorators and dependency injection - Service-based architecture for business logic - Production-ready middleware and tooling - Automatic database optimizations and session management Middleware Stack (in execution order): 1. ExceptionHandlerMiddleware - Catches errors, returns JSON responses 2. RequestIDMiddleware - Adds X-Request-ID for tracing 3. DatabaseSessionMiddleware - Request-scoped DB connections 4. SecurityHeadersMiddleware - CSP, X-Frame-Options, etc. 5. ResponseCacheMiddleware - Caches GET responses (if enabled) 6. RateLimitMiddleware - Request throttling (if enabled) 7. RequestLoggingMiddleware - Structured request logs (if enabled) 8. CompressionMiddleware - Gzip/Brotli response compression Args: testing: Enable testing mode to disable rate limiting and strict CORS. Also enabled by ZENITH_TESTING environment variable. Example: app = Zenith() # For testing app = Zenith(testing=True) @app.get("/items/{id}") async def get_item(id: int, items: ItemService = Inject(ItemService)) -> dict: return await items.get_item(id) """ class _DatabaseSessionMiddleware: """Built-in database session middleware for automatic request-scoped connection reuse.""" def __init__(self, app, database): self.app = app self.database = database async def __call__(self, scope, receive, send): if scope["type"] != "http": await self.app(scope, receive, send) return # Automatically provide request-scoped database session async with self.database.request_scoped_session(scope) as session: # Also set in container context for ZenithModel seamless access from zenith.core.container import set_current_db_session set_current_db_session(session) try: await self.app(scope, receive, send) finally: # Clean up context set_current_db_session(None) def __init__( self, config: Config | None = None, middleware: list[Middleware] | None = None, debug: bool | None = None, enable_optimizations: bool = True, # New parameters for easier configuration title: str | None = None, version: str = "1.0.0", description: str | None = None, # Testing mode to disable problematic middleware for test suites testing: bool | None = None, # Production mode: enables security headers, rate limiting, compression # None = auto-detect from ZENITH_ENV, True/False = explicit override production: bool | None = None, ): # Apply performance optimizations if enabled if enable_optimizations: try: from zenith.optimizations import optimize_zenith self._optimizations = optimize_zenith() except ImportError: self._optimizations = [] else: self._optimizations = [] # Initialize configuration self.config = config or Config.from_env() # Handle explicit debug parameter if debug is not None: self.config.debug = debug # Set up logger self.logger = logging.getLogger("zenith.application") # Use unified environment detection from Config self.environment = self.config._environment # Import os for environment variable access # Configure based on environment (unless explicitly overridden) if self.environment == "production": self.testing = testing if testing is not None else False if debug is None: self.config.debug = False # Skip production validation in testing mode (for test suites) if not self.testing: self._validate_production_config() elif self.environment == "staging": self.testing = testing if testing is not None else False if debug is None: self.config.debug = False if not self.testing: self._validate_production_config() elif self.environment == "test": self.testing = ( testing if testing is not None else True ) # Default to True in test env if debug is None: self.config.debug = True else: # development if testing is not None: # Explicit testing parameter overrides everything self.testing = testing else: self.testing = False # Default to False in development if debug is None: self.config.debug = True if self.testing: self.logger.info( f"๐Ÿงช Testing mode enabled ({self.environment} environment)" ) else: self.logger.info(f"๐Ÿš€ Running in {self.environment} environment") if debug is not None: self.config._debug_explicitly_set = True else: self.config._debug_explicitly_set = False # Determine production mode (affects middleware defaults) # None = auto-detect, True/False = explicit override if production is not None: self.production = production else: # Auto-detect: production/staging environments enable production middleware self.production = self.environment in ("production", "staging") # Create core application (after environment is detected) self.app = Application(self.config) # Initialize routing with a single master router self.middleware = middleware if middleware is not None else [] self._app_router = Router() self._app_router._app = self.app # Link app to the master router for DI # Skip essential middleware if middleware was explicitly provided (for testing/custom configs) self._skip_essential_middleware = middleware is not None # Add essential middleware with state-of-the-art defaults # Skip if middleware was explicitly provided (for testing/benchmarking/custom configs) if not self._skip_essential_middleware: self._add_essential_middleware() # Auto-setup common features self._setup_contexts() self._setup_static_files() self._add_health_endpoints() # OpenAPI endpoints are now only added when explicitly configured via add_docs() # self._add_openapi_endpoints() # Starlette app (created on demand) self._starlette_app = None def _add_essential_middleware(self) -> None: """Add middleware based on environment. Minimal defaults for fast development, full stack for production. Use `production=True` or `ZENITH_ENV=production` to enable all middleware. """ from zenith.middleware import ExceptionHandlerMiddleware # === ALWAYS ENABLED (essential, minimal like FastAPI) === # 1. Exception handling only self.add_middleware(ExceptionHandlerMiddleware, debug=self.config.debug) # === PRODUCTION MODE (full middleware stack) === if self.production: from zenith.middleware import ( CompressionMiddleware, RateLimitMiddleware, RequestIDMiddleware, ResponseCacheMiddleware, SecurityHeadersMiddleware, ) # 2. Request ID tracking (useful for distributed tracing) self.add_middleware(RequestIDMiddleware) # 3. Database session reuse (15-25% DB performance improvement) self.add_middleware( self._DatabaseSessionMiddleware, database=self.app.database ) # 4. Security headers self.add_middleware(SecurityHeadersMiddleware) # 5. Response caching (skip in debug mode) if not self.config.debug: self.add_middleware(ResponseCacheMiddleware) # 6. Rate limiting (skip in testing mode) if not self.testing: from zenith.middleware.rate_limit import RateLimit self.add_middleware( RateLimitMiddleware, default_limits=[RateLimit(requests=100, window=60, per="ip")], ) # 7. Compression (most expensive, last) self.add_middleware(CompressionMiddleware) self.logger.info("Production middleware enabled") # === DEBUG MODE EXTRAS === if self.config.debug: from zenith.middleware import RequestLoggingMiddleware self.add_middleware(RequestLoggingMiddleware) def _setup_contexts(self) -> None: """Auto-register common contexts.""" # No default contexts in framework - users register their own pass def _setup_static_files(self) -> None: """Auto-configure static file serving with sensible defaults.""" from pathlib import Path # Common static file directories to check static_dirs = [ ("static", "/static"), # Most common ("assets", "/assets"), # Modern frontend ("public", "/public"), # Alternative ] for dir_name, url_path in static_dirs: static_path = Path(dir_name) if static_path.exists() and static_path.is_dir(): # Only mount if directory has files if any(static_path.iterdir()): self.mount_static(url_path, str(static_path)) self.logger.info( f"Auto-mounted static files: {url_path} -> {static_path}" ) def _looks_like_production(self) -> bool: """Detect if we're running in a production-like environment.""" import os indicators = [ # Cloud platforms os.getenv("KUBERNETES_SERVICE_HOST"), # Kubernetes os.getenv("DYNO"), # Heroku os.getenv("AWS_EXECUTION_ENV"), # AWS Lambda os.getenv("GOOGLE_CLOUD_PROJECT"), # Google Cloud os.getenv("WEBSITE_INSTANCE_ID"), # Azure os.getenv("FLY_APP_NAME"), # Fly.io os.getenv("RENDER"), # Render os.getenv("RAILWAY_ENVIRONMENT"), # Railway os.getenv("DETA_RUNTIME"), # Deta # Container environments Path("/.dockerenv").exists(), # Docker Path("/var/run/secrets/kubernetes.io").exists(), # K8s # CI/CD environments (should not default to dev in CI) os.getenv("CI"), # Generic CI os.getenv("GITHUB_ACTIONS"), # GitHub Actions os.getenv("GITLAB_CI"), # GitLab CI os.getenv("CIRCLECI"), # CircleCI ] # Check if any production indicator is present and return return any(indicators) def _validate_production_config(self) -> None: """Validate that production requirements are met.""" import os from zenith.exceptions import ConfigError # Require a proper secret key secret_key = os.getenv("SECRET_KEY") or self.config.secret_key # Check if using default secret key if secret_key in ("dev-secret-change-in-prod", "", None): raise ConfigError( f"SECRET_KEY must be set for {self.environment} environment.\n" "Generate a secure key with:\n" " zen keygen # Print to stdout\n" " zen keygen --output .env # Save to .env file" ) # Validate secret key strength if len(secret_key) < 32: raise ConfigError( f"SECRET_KEY must be at least 32 characters for {self.environment} environment.\n" f"Current length: {len(secret_key)}" ) def _add_health_endpoints(self) -> None: """Add health check endpoints.""" from starlette.requests import Request # Add built-in health endpoints @self._app_router.get("/health") async def health_check(request: Request): """Health check endpoint.""" from zenith.monitoring.health import health_endpoint return await health_endpoint(request) @self._app_router.get("/ready") async def readiness_check(request: Request): """Readiness check endpoint.""" from zenith.monitoring.health import readiness_endpoint return await readiness_endpoint(request) @self._app_router.get("/live") async def liveness_check(request: Request): """Liveness check endpoint.""" from zenith.monitoring.health import liveness_endpoint return await liveness_endpoint(request) def _add_openapi_endpoints( self, docs_url: str | None = None, redoc_url: str | None = None, openapi_url: str = "/openapi.json", ) -> None: """Add OpenAPI documentation endpoints.""" from starlette.responses import HTMLResponse, JSONResponse from zenith.openapi import generate_openapi_spec # Only register OpenAPI spec endpoint @self._app_router.get(openapi_url) async def openapi_spec(): """OpenAPI specification endpoint.""" # Get title/version/description from config if set by add_docs() api_title = getattr( self.config, "api_title", f"{self.__class__.__name__} API" ) api_version = getattr(self.config, "api_version", "1.0.0") api_description = getattr( self.config, "api_description", "API documentation generated by Zenith Framework", ) # Pass the single app router spec = generate_openapi_spec( [self._app_router], title=api_title, version=api_version, description=api_description, ) return JSONResponse(spec) # Only register Swagger UI if docs_url is provided if docs_url: @self._app_router.get(docs_url) async def swagger_ui(): """Swagger UI documentation.""" html_content = """ <!DOCTYPE html> <html> <head> <title>API Documentation</title> <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3.52.5/swagger-ui.css" /> <style> html { box-sizing: border-box; overflow: -moz-scrollbars-vertical; overflow-y: scroll; } *, *:before, *:after { box-sizing: inherit; } body { margin:0; background: #fafafa; } </style> </head> <body> <div id="swagger-ui"></div> <script src="https://unpkg.com/swagger-ui-dist@3.52.5/swagger-ui-bundle.js"></script> <script> SwaggerUIBundle({ url: '/openapi.json', dom_id: '#swagger-ui', presets: [ SwaggerUIBundle.presets.apis, SwaggerUIBundle.presets.standalone ], layout: "BaseLayout" }); </script> </body> </html> """ return HTMLResponse(html_content) # Only register ReDoc if redoc_url is provided if redoc_url: @self._app_router.get(redoc_url) async def redoc(): """ReDoc documentation.""" html_content = """ <!DOCTYPE html> <html> <head> <title>API Documentation</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.json'></redoc> <script src="https://cdn.jsdelivr.net/npm/redoc@2.0.0/bundles/redoc.standalone.js"></script> </body> </html> """ return HTMLResponse(html_content) # Add metrics endpoint (production only for security) if not self.config.debug: from starlette.responses import PlainTextResponse @self._app_router.get("/metrics") async def metrics_endpoint(): """Prometheus metrics endpoint.""" from zenith.monitoring.metrics import metrics_endpoint as get_metrics content = await get_metrics() return PlainTextResponse( content, media_type="text/plain; version=0.0.4" ) def on_event(self, event_type: str): """ Decorator for registering event handlers. Args: event_type: "startup" or "shutdown" Example: @app.on_event("startup") async def startup_handler(): self.logger.info("Starting up!") """ def decorator(func): if event_type == "startup": self.app.add_startup_hook(func) elif event_type == "shutdown": self.app.add_shutdown_hook(func) else: raise ValueError(f"Unknown event type: {event_type}") return func return decorator @asynccontextmanager async def lifespan(self, scope): """ASGI lifespan handler.""" # Startup await self.app.startup() yield # Shutdown await self.app.shutdown() def _build_starlette_app(self) -> Starlette: """Build the underlying Starlette application.""" if self._starlette_app is not None: return self._starlette_app # Build the single master router starlette_router = self._app_router.build_starlette_router() routes = starlette_router.routes # Collect mount routes and sort them by specificity mount_routes = [] spa_routes = [] # SPA routes (mounted at /) should go last # Add static mounts (for mount_static() method) - these should come before SPAs if hasattr(self, "_static_mounts"): mount_routes.extend(self._static_mounts) # Add mount routes (for spa() and mount() methods) if hasattr(self, "_mount_routes"): for route in self._mount_routes: # Put SPA routes (mounted at root) at the end if hasattr(route, "path") and route.path in ("/", ""): spa_routes.append(route) else: mount_routes.append(route) # Add routes in order: API routes, static mounts, then SPA catch-all routes.extend(mount_routes) routes.extend(spa_routes) # Create custom exception handlers for JSON responses from starlette.exceptions import HTTPException from starlette.requests import Request from zenith.web.responses import OptimizedJSONResponse async def not_found_handler( request: Request, exc: HTTPException ) -> OptimizedJSONResponse: """Return JSON for 404 errors.""" return OptimizedJSONResponse( content={ "error": "NotFound", "message": "The requested resource was not found", "status_code": 404, "path": str(request.url.path), }, status_code=404, ) async def method_not_allowed_handler( request: Request, exc: HTTPException ) -> OptimizedJSONResponse: """Return JSON for 405 errors.""" return OptimizedJSONResponse( content={ "error": "MethodNotAllowed", "message": f"Method {request.method} not allowed for this endpoint", "status_code": 405, "path": str(request.url.path), }, status_code=405, ) # Import exception handler for rate limiting from starlette.responses import JSONResponse from zenith.exceptions import RateLimitException def rate_limit_handler(request, exc): """Handle rate limit exceptions.""" # Start with default headers headers = { "Retry-After": "60", # Default retry after 60 seconds } # If the exception includes headers, use them if hasattr(exc, "headers") and exc.headers: headers.update(exc.headers) # Add standard rate limit headers if not present if "X-RateLimit-Limit" not in headers: # Try to extract from exception details if hasattr(exc, "limit"): headers["X-RateLimit-Limit"] = str(exc.limit) if "X-RateLimit-Remaining" not in headers: # Set to 0 since we hit the limit headers["X-RateLimit-Remaining"] = "0" if "X-RateLimit-Reset" not in headers: # Calculate reset time import time retry_after = int(headers.get("Retry-After", 60)) headers["X-RateLimit-Reset"] = str(int(time.time()) + retry_after) return JSONResponse( status_code=429, content={ "error": "rate_limit_exceeded", "message": str(exc), "detail": exc.detail if hasattr(exc, "detail") else "Too many requests", }, headers=headers, ) exception_handlers = { 404: not_found_handler, 405: method_not_allowed_handler, RateLimitException: rate_limit_handler, 429: rate_limit_handler, # Also handle standard 429 status codes } # Create Starlette app self._starlette_app = Starlette( routes=routes, middleware=self.middleware, lifespan=self.lifespan, debug=self.config.debug, exception_handlers=exception_handlers, ) # Apply OpenTelemetry instrumentation if tracing was enabled if hasattr(self, "_otel_instrumented") and self._otel_instrumented: try: from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor # Instrument the Starlette app (FastAPIInstrumentor works with Starlette) FastAPIInstrumentor.instrument_app(self._starlette_app) except ImportError: pass # Shouldn't happen since we check in add_tracing return self._starlette_app async def __call__(self, scope, receive, send): """ASGI interface.""" starlette_app = self._build_starlette_app() await starlette_app(scope, receive, send) def run( self, host: str | None = None, port: int | None = None, reload: bool = False, protocol: str = "auto", **kwargs, ) -> None: """ Run the application with automatic protocol selection. Args: host: Host to bind to (defaults to config.host) port: Port to bind to (defaults to config.port) reload: Enable auto-reload for development protocol: Protocol to use ("http", "http3", "auto") **kwargs: Additional server options """ # Smart protocol selection if protocol == "auto": # Use HTTP/3 for production (port 443) if available if port == 443 or self.config.port == 443: try: import aioquic # noqa: F401 protocol = "http3" self.logger.info("Auto-selected HTTP/3 for production") except ImportError: protocol = "http" self.logger.info("HTTP/3 not available, using HTTP/2") else: protocol = "http" if protocol == "http3": self.run_http3(host=host, port=port, **kwargs) else: # Standard HTTP/2 with uvicorn run( self, host=host or self.config.host, port=port or self.config.port, reload=reload, **kwargs, ) def run_http3( self, host: str | None = None, port: int | None = None, cert_path: str | None = None, key_path: str | None = None, enable_0rtt: bool = True, **kwargs, ) -> None: """ Run the application using HTTP/3 (QUIC protocol). HTTP/3 Benefits: - 30-50% faster connection establishment - Better performance on lossy networks - No head-of-line blocking - Connection migration support - Built-in encryption Args: host: Host to bind to (defaults to config.host) port: Port to bind to (defaults to 443 for HTTPS) cert_path: Path to SSL certificate key_path: Path to SSL private key enable_0rtt: Enable 0-RTT for faster reconnection **kwargs: Additional HTTP/3 server options Raises: RuntimeError: If HTTP/3 support is not available """ import asyncio try: from zenith.http3 import create_http3_server except ImportError as e: raise RuntimeError( "HTTP/3 support requires 'aioquic'. Install with: pip install zenithweb[http3]" ) from e # Use standard HTTPS port for HTTP/3 actual_port = port or 443 actual_host = host or self.config.host self.logger.info(f"Starting HTTP/3 server on {actual_host}:{actual_port}") # Create HTTP/3 server http3_server = create_http3_server( self, host=actual_host, port=actual_port, cert_path=cert_path, key_path=key_path, enable_0rtt=enable_0rtt, **kwargs, ) # Run the server try: asyncio.run(http3_server.serve()) except KeyboardInterrupt: self.logger.info("HTTP/3 server stopped by user") except Exception as e: self.logger.error(f"HTTP/3 server error: {e}") raise async def startup(self) -> None: """Start the application manually (for testing).""" await self.app.startup() async def shutdown(self) -> None: """Shutdown the application manually (for testing).""" await self.app.shutdown() def on_startup(self, func): """ Decorator to register startup hooks. Usage: @app.on_startup async def setup_database(): # Initialize database connection pass """ self.app.add_startup_hook(func) return func def on_shutdown(self, func): """ Decorator to register shutdown hooks. Usage: @app.on_shutdown async def cleanup(): # Close database connections pass """ self.app.add_shutdown_hook(func) return func # Service/DI Registration Methods def register_service(self, service_class: type, name: str | None = None) -> None: """ Register a service class with the DI container. Args: service_class: The service class to register name: Optional name for the service (defaults to class name) Usage: app.register_service(UserService) app.register_service(EmailService, "email") """ service_name = name or service_class.__name__ self.app.contexts.register(service_name, service_class) self.logger.info(f"โœ… Service registered: {service_name}") def register( self, dependency_type: type, implementation: Any = None, singleton: bool = True ) -> None: """ Register a dependency with the DI container. Args: dependency_type: The type/interface to register implementation: The implementation (defaults to the type itself) singleton: Whether to use singleton pattern Usage: app.register(Database, MyDatabase()) app.register(CacheInterface, RedisCache(), singleton=True) """ self.app.container.register( dependency_type, implementation or dependency_type, singleton ) self.logger.info(f"โœ… Dependency registered: {dependency_type.__name__}") @property def container(self): """Access the dependency injection container.""" return self.app.container @property def contexts(self): """Access the service registry.""" return self.app.contexts # ๐Ÿš€ One-liner convenience methods for better DX def add_auth( self, secret_key: str | None = None, algorithm: str = "HS256", expire_minutes: int = 30, ) -> "Zenith": """ Add JWT authentication in one line. Usage: app.add_auth() # Uses secret from config or env app.add_auth("my-secret-key") """ from zenith.middleware.auth import AuthenticationMiddleware # Use provided secret or fallback to config auth_secret = secret_key or self.config.secret_key if not auth_secret: raise ValueError( "Secret key required for authentication. Either pass secret_key parameter " "or set SECRET_KEY environment variable." ) # Configure global JWT manager for middleware from zenith.auth.jwt import configure_jwt jwt_manager = configure_jwt( secret_key=auth_secret, algorithm=algorithm, access_token_expire_minutes=expire_minutes, ) # Add auth middleware self.add_middleware(AuthenticationMiddleware) # Add login endpoint - DEMO ONLY - REPLACE WITH REAL AUTHENTICATION # Allow demo auth in debug mode OR development environment (for testing) if self.config.debug or self.environment == "development": # Only in dev mode - add a warning endpoint @self.post("/auth/login") async def dev_login_demo(credentials: dict): """ DEVELOPMENT DEMO LOGIN - NOT FOR PRODUCTION! This endpoint is for development testing only. In production, implement real user authentication. """ username = credentials.get("username") password = credentials.get("password") # In development only, warn about insecure demo login self.logger.warning( "โš ๏ธ Using DEMO authentication - NOT SECURE! " "Replace with real authentication before production!" ) if username == "demo" and password == "demo": # Only allow specific demo credentials token = jwt_manager.create_access_token( user_id=999, email="demo@example.com", role="demo" ) return { "access_token": token, "token_type": "bearer", "expires_in": expire_minutes * 60, "warning": "DEMO MODE - Not for production use!", } else: from starlette.exceptions import HTTPException raise HTTPException( status_code=401, detail="Invalid credentials (hint: use demo/demo in dev mode)", ) else: # Production mode - require real implementation @self.post("/auth/login") async def login_not_implemented(credentials: dict): """Authentication endpoint - must be implemented.""" from starlette.exceptions import HTTPException raise HTTPException( status_code=501, detail="Authentication not implemented. Please implement a real login handler.", ) self.logger.info("โœ… Authentication added - /auth/login endpoint available") return self def add_admin(self, route: str = "/admin") -> "Zenith": """ Add admin interface in one line. Usage: app.add_admin() # Mounts at /admin app.add_admin("/dashboard") # Custom route """ # Basic admin interface - can be enhanced with proper admin framework @self.get(f"{route}") async def admin_dashboard(): """Simple admin dashboard - customize as needed.""" return { "message": "Admin Dashboard", "routes": [ f"GET {route} - Dashboard", f"GET {route}/health - System health", f"GET {route}/stats - Application statistics", ], } @self.get(f"{route}/health") async def admin_health(): """Admin health check.""" try: db_healthy = await self.app.database.health_check() return { "status": "healthy" if db_healthy else "unhealthy", "database": "connected" if db_healthy else "disconnected", "version": "0.3.0", } except Exception as e: return {"status": "unhealthy", "error": str(e), "version": "0.3.0"} @self.get(f"{route}/stats") async def admin_stats(): """Basic application statistics.""" return { "routes_count": len(self._app_router.routes), "middleware_count": len(self.middleware), "debug_mode": self.config.debug, } self.logger.info(f"โœ… Admin interface added at {route}") return self def add_docs( self, title: str | None = None, version: str = "1.0.0", description: str | None = None, docs_url: str = "/docs", redoc_url: str = "/redoc", openapi_url: str = "/openapi.json", ) -> "Zenith": """ Add OpenAPI documentation endpoints. Args: title: API title for documentation version: API version description: API description docs_url: URL for Swagger UI documentation redoc_url: URL for ReDoc documentation openapi_url: URL for OpenAPI JSON spec Returns: Self for method chaining """ # Store API info in config for OpenAPI generation self.config.api_title = title or "Zenith API" self.config.api_version = version self.config.api_description = description or "API built with Zenith framework" # Add the OpenAPI endpoints self._add_openapi_endpoints( docs_url=docs_url, redoc_url=redoc_url, openapi_url=openapi_url ) self.logger.info( f"๐Ÿ“– OpenAPI documentation enabled at {docs_url} and {redoc_url}" ) return self def add_api( self, title: str | None = None, version: str = "1.0.0", description: str | None = None, docs_url: str = "/docs", redoc_url: str = "/redoc", ) -> "Zenith": """ Add API documentation in one line. Usage: app.add_api() # Default OpenAPI docs app.add_api("My API", "1.2.0", "API for my app") """ # Set API metadata api_title = title or "Zenith API" api_description = description or "API built with Zenith framework" # Add OpenAPI documentation self.add_docs( title=api_title, version=version, description=api_description, docs_url=docs_url, redoc_url=redoc_url, ) # Add API info endpoint @self.get("/api/info") async def api_info(): """API information endpoint.""" return { "title": api_title, "version": version, "description": api_description, "docs_url": docs_url, "redoc_url": redoc_url, } self.logger.info( f"โœ… API documentation added - {docs_url} and {redoc_url} available" ) return self def add_graphql( self, schema, path: str = "/graphql", graphiql: bool = True, debug: bool = False, ) -> "Zenith": """ Add GraphQL support with Strawberry GraphQL. Args: schema: Strawberry GraphQL schema instance path: URL path for GraphQL endpoint graphiql: Enable GraphiQL interactive interface debug: Enable GraphQL debug mode Returns: Self for method chaining Example: import strawberry from strawberry.fastapi import GraphQLRouter @strawberry.type class Query: @strawberry.field def hello(self) -> str: return "Hello World!" schema = strawberry.Schema(Query) app = Zenith() app.add_graphql(schema) """ try: from strawberry.fastapi import GraphQLRouter except ImportError as e: raise ImportError( "GraphQL support requires strawberry-graphql. Install with: pip install strawberry-graphql" ) from e # Create GraphQL router graphql_app = GraphQLRouter( schema, graphiql=graphiql, debug=debug, ) # Mount GraphQL app self.mount(path, graphql_app, name="graphql") self.logger.info( f"๐Ÿ”บ GraphQL endpoint added at {path}{' with GraphiQL' if graphiql else ''}" ) return self def add_tracing( self, service_name: str | None = None, service_version: str | None = None, exporter_endpoint: str | None = None, ) -> "Zenith": """ Add distributed tracing with OpenTelemetry. Args: service_name: Name of the service for tracing service_version: Version of the service exporter_endpoint: OTLP exporter endpoint (e.g., "http://localhost:4318") Returns: Self for method chaining Example: app = Zenith() app.add_tracing( service_name="my-api", service_version="1.0.0", exporter_endpoint="http://jaeger:4318" ) """ import importlib.util # Check for required dependencies required_packages = [ "opentelemetry", "opentelemetry.sdk.trace", "opentelemetry.exporter.otlp.proto.grpc.trace_exporter", "opentelemetry.instrumentation.fastapi", ] for package in required_packages: if importlib.util.find_spec(package) is None: raise ImportError( "Tracing support requires OpenTelemetry. Install with: pip install opentelemetry-distro opentelemetry-instrumentation-fastapi" ) # Import after verifying availability from opentelemetry import trace from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import ( OTLPSpanExporter, ) from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor # Configure tracing service_name = service_name or "zenith-app" service_version = service_version or "1.0.0" # Set up tracer provider trace.set_tracer_provider( TracerProvider( resource=trace.Resource.create( { "service.name": service_name, "service.version": service_version, } ) ) ) # Add OTLP exporter if endpoint provided if exporter_endpoint: otlp_exporter = OTLPSpanExporter( endpoint=exporter_endpoint, insecure=True, ) span_processor = BatchSpanProcessor(otlp_exporter) trace.get_tracer_provider().add_span_processor(span_processor) # Instrument FastAPI (will be applied when Starlette app is built) self._otel_instrumented = True self.logger.info( f"๐Ÿ” Distributed tracing enabled for {service_name} v{service_version}" f"{' (OTLP export enabled)' if exporter_endpoint else ''}" ) return self def __repr__(self) -> str: return f"Zenith(debug={self.config.debug})"
"""
Main Zenith class - the entry point for creating Zenith applications.
Combines the power of:
- FastAPI-style routing and dependency injection
- Service-based architecture for business logic
- Modern Python patterns and developer experience
"""
import logging
from contextlib import asynccontextmanager
from pathlib import Path
from typing import Any
from starlette.applications import Starlette
from starlette.middleware import Middleware
from uvicorn import run
from zenith.core.application import Application
from zenith.core.config import Config
from zenith.core.routing import Router
from zenith.http.client import HTTPClientMixin
from zenith.mixins import DocsMixin, MiddlewareMixin, RoutingMixin, ServicesMixin
class Zenith(MiddlewareMixin, RoutingMixin, DocsMixin, ServicesMixin, HTTPClientMixin):
"""
Main Zenith application class.
The high-level API for creating Zenith applications with:
- FastAPI-style decorators and dependency injection
- Service-based architecture for business logic
- Production-ready middleware and tooling
- Automatic database optimizations and session management
Middleware Stack (in execution order):
1. ExceptionHandlerMiddleware - Catches errors, returns JSON responses
2. RequestIDMiddleware - Adds X-Request-ID for tracing
3. DatabaseSessionMiddleware - Request-scoped DB connections
4. SecurityHeadersMiddleware - CSP, X-Frame-Options, etc.
5. ResponseCacheMiddleware - Caches GET responses (if enabled)
6. RateLimitMiddleware - Request throttling (if enabled)
7. RequestLoggingMiddleware - Structured request logs (if enabled)
8. CompressionMiddleware - Gzip/Brotli response compression
Args:
testing: Enable testing mode to disable rate limiting and strict CORS.
Also enabled by ZENITH_TESTING environment variable.
Example:
app = Zenith()
# For testing
app = Zenith(testing=True)
@app.get("/items/{id}")
async def get_item(id: int, items: ItemService = Inject(ItemService)) -> dict:
return await items.get_item(id)
"""
class _DatabaseSessionMiddleware:
"""Built-in database session middleware for automatic request-scoped connection reuse."""
def __init__(self, app, database):
self.app = app
self.database = database
async def __call__(self, scope, receive, send):
if scope["type"] != "http":
await self.app(scope, receive, send)
return
# Automatically provide request-scoped database session
async with self.database.request_scoped_session(scope) as session:
# Also set in container context for ZenithModel seamless access
from zenith.core.container import set_current_db_session
set_current_db_session(session)
try:
await self.app(scope, receive, send)
finally:
# Clean up context
set_current_db_session(None)
def __init__(
self,
config: Config | None = None,
middleware: list[Middleware] | None = None,
debug: bool | None = None,
enable_optimizations: bool = True,
# New parameters for easier configuration
title: str | None = None,
version: str = "1.0.0",
description: str | None = None,
# Testing mode to disable problematic middleware for test suites
testing: bool | None = None,
# Production mode: enables security headers, rate limiting, compression
# None = auto-detect from ZENITH_ENV, True/False = explicit override
production: bool | None = None,
):

Xet Storage Details

Size:
43.1 kB
ยท
Xet hash:
b790038a890bc6b04e463a67d91e3ffffcc22159564e58746b145c5d23a1cbab

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.