Guides
Step-by-step recipes for the things you'll do most often as you build a real Lauren application.
The full lifecycle of an injectable — @injectable, scopes, function-based providers, lifecycle hooks, Protocols, multi-bindings.
use_value, use_class, use_factory, use_existing, Token, and Inject — when @injectable isn't enough.
• Implicit Parameter Extraction
Path params, query params, and JSON bodies auto-detected from type annotations — no Path[…]/Query[…]/Json[…] boilerplate unless you need it.
Build domain extractors like CurrentUser, TenantId, or RequestSpan and use them as parameter annotations.
• Pipes
Post-extraction transforms: validate, coerce, enrich, or replace extracted values before they reach your handler. Function-based, class-based, chainable, and DI-aware.
UploadFile for single and multi-file multipart uploads, mixed forms with Form[T], optional files, Unicode filenames.
Authentication and authorization classes, route metadata, composition with class-level guards.
The onion model, request-id propagation, response post-processing, error handling.
AOP-style wrappers that run after routing and guards. Full ExecutionContext access: transform results, add headers, implement caching, catch errors, and read route metadata.
Catch domain errors at the right scope. Class-form (DI-injected) vs function-form. Global vs per-controller vs per-route.
First-class WebSocket gateways: @ws_controller, @on_message, typed Pydantic frames, BroadcastGroup rooms, in-process testing.
One-way streaming with EventStream and ServerSentEvent: keep-alive heartbeats, Last-Event-ID resumability, AI text-streaming patterns.
StreamingResponse[T] for outbound content-negotiated streams and Stream[T] for inbound typed iterators. SSE / NDJSON / JSON Lines, discriminated unions, bidirectional pipelines.
SignalBus for typed pub/sub: RequestComplete, StartupComplete, background-task signals. MRO dispatch, error isolation, metrics/tracing patterns.
Engine.IO v4 / Socket.IO v5 adapter — @socketio_controller, @on_socketio_event, SocketIOConnection, automatic ACKs, DI injection.
Break circular import cycles between feature modules using ForwardRef("ClassName") in @module(imports=[...]) — resolved lazily at startup.
• OpenAPI Security from Guards
Annotate guard classes with @openapi_security({"SchemeName": []}) and Lauren populates the security field on every protected operation automatically — OR / AND semantics, OAuth2 scopes, explicit overrides.
Run behind a reverse proxy with root_path, and serve static assets with StaticFilesModule.for_root("/static", directory="./public") — ETag caching, path traversal protection, multiple mounts.
Fire-and-forget work after the response is sent. BackgroundTasks extractor, TaskHandle, sync/async callables, BackgroundTaskFailed signals, graceful-shutdown drain participation.
Every handler may be def or async def. Sync handlers are automatically offloaded to a thread pool — no blocking the event loop.
Using @dataclass, Pydantic BaseModel, SQLAlchemy DeclarativeBase, and SQLModel with the DI container.