Stario

Reference

This reference documentation follows the journey of an HTTP request through the Stario framework - from the moment it arrives at your application to when the response is sent back to the client.

Understanding this flow will help you know where to look when building features, debugging issues, or customizing behavior.

Request Processing Pipeline

Section Topics
Routing Route matching · Path parameters · Dynamic routes
Endpoints CQRS pattern · Query, Command, DetachedCommand · Execution phases · Background execution
Dependencies Dependency resolution · Lifetimes (request, transient, singleton, lazy) · Concurrent resolution
Responses Response types · Streaming · Status codes · HTML rendering

Error Handling & Observability

Section Topics
Error Handling Handler vs. streaming exceptions · Status code constraints · Exception middleware
Logging Correlation IDs · Logging sinks · Background task logging

Content Generation

Section Topics
HTML HTML generation · Escaping · Rendering adapters · Security
Datastar Signal parsing · Datastar actions & attributes · Server-Sent Events

Miscellaneous Features

Section Topics
Middlewares Middleware stack order · GuardianMiddleware · Response lifecycle
Testing TestClient · Async handlers · Dependency overrides · Testing patterns
Toys toy_page · toy_inspector · Debugging requests

Request Flow Diagram

Request arrives
      ↓
Middleware (Request Phase)     # Authentication, logging, validation
      ↓
Routing                        # Match path, method, headers → find handler
      ↓
Endpoint Handler               # Your function executes:
  1. Dependency Injection      #   1. Resolve dependencies defined in handler parameters
  2. Handler Execution         #   2. Run your domain logic
  3. Response Processing       #   3. Convert output to HTTP response
      ↓
Response Handling              # Final tweaks, error recovery / exceptions
      ↓
Middleware (Response Phase)    # Compression, headers, logging
      ↓
Response sent to client

Terminology

Key terms used throughout this documentation:

Term Definition Example
Request ID (also: correlation ID) Unique UUIDv4 generated for each request, appears in all logs to trace a request end-to-end abc123de-4567-89f0-1234-567890ab
Route A URL path + HTTP method pairing /users (GET), /users (POST)
Endpoint / Handler Python async (or sync) function that processes a request async def get_user(...), def list_users(...)
Dependency A value or service automatically injected to your handler by the framework db: Database, logger: Logger
Sink Output destination for logs (console, file, database, external service) RichConsoleSink, JSONSink
Query Read-only operation that returns data without side effects /users (GET), /posts/{id} (GET)
Command Write operation that changes state and returns results immediately /users (POST), /users/{id} (DELETE)
Detached Command Write operation that runs in background and returns 204 immediately /import (POST), /send-emails (POST)
Signal Reactive value in Datastar that can be read/modified on client or server {"counter": 42, "message": "hello"}

Looking for practical solutions or explanation?

This reference focuses on how things work with minimal explanation of the why. For comprehensive reasoning about design decisions and patterns, see the Explanation section. For practical solutions to common problems, see the How-Tos section.