Scopes — Aquilia Documentation
Comprehensive guide and documentation for Scopes in the Aquilia framework. View API reference, examples, and implementation patterns.
Dependency Injection / Scopes Service Scopes & Lifetimes Scopes define instance lifetimes and validation constraints. Aquilia enforces strict boundary checking to prevent memory leaks and concurrency race conditions. ServiceScope Enum Defined in aquilia/di/scopes.py as a string-based enum for simple manifest and decorator configurations: from aquilia.di.scopes import ServiceScope class ServiceScope(str, Enum): SINGLETON = "singleton" # Process-wide lifetime APP = "app" # Application container lifetime REQUEST = "request" # Isolated request lifetime TRANSIENT = "transient" # Uncached, new instance per resolution POOLED = "pooled" # Managed by asyncio.Queue instance pool EPHEMERAL = "ephemeral" # Request-scoped temporary lifetime Scope Lifetime Cached Use Case ))} Injection Validation To enforce structural safety, Aquilia checks scope compatibility at startup: Longer-lived scopes can always inject into shorter-lived scopes. Shorter-lived scopes CANNOT inject into longer-lived scopes (prevents memory leak state capture). Injection Compatibility Matrix Provider ↓ / Consumer → singleton app request transient ephemeral ))} ))} Scope Violation Example @service(scope="request") class RequestLogger: def __init__(self, req: Request): self.req = req @service(scope="singleton") class GlobalAnalytics: # ❌ ScopeViolationError raised at startup: # Singleton cannot depend on short-lived request scope! def __init__(self, logger: RequestLogger): self.logger = logger # Option A: Make the consumer request-scoped: @service(scope="request") class GlobalAnalytics: def __init__(self, logger: RequestLogger): self.logger = logger # Option B: Access lazily via the context container @service(scope="singleton") class GlobalAnalytics: def __init__(self): pass async def track(self, ctx_container, event: str): logger = await ctx_container.resolve_async(RequestLogger) logger.info(event) Providers Decorators )
Go to Homepage