Typed State — Aquilia Documentation
Comprehensive guide and documentation for Typed State in the Aquilia framework. View API reference, examples, and implementation patterns.
Sessions / State Typed Session State The SessionState system provides type-safe, structured access to session dictionaries. By defining typed states with Field descriptors, you avoid raw string key access like session["key"]. SessionState Base Class Inheriting from SessionState enables typed field validation and default value seeding for session data dictionaries: from aquilia.sessions.state import SessionState, Field class MyState(SessionState): """Define typed fields that sync with session.data.""" # Field with a default value theme: str = Field(default="light") # Field with a factory (for mutable lists/dicts) cart_items: list = Field(default_factory=list) # Field with no default (returns None if missing from session data) user_name: str = Field() Field Descriptor The Field class acts as a Python descriptor governing access and mutations. It takes two configuration parameters: Parameter Type Description ))} How Synchronization Works Typed states wrap the session data dictionary directly. Instantiating a state pulls/pushes keys to the underlying dictionary, updating dirty markers: from aquilia.sessions import Session, SessionID from aquilia.sessions.state import SessionState, Field class CartState(SessionState): items: list = Field(default_factory=list) coupon: str = Field(default="") # 1. Create a session with existing data session = Session( id=SessionID(), data= ], "coupon": "SAVE20"}, ) # 2. Wrap the session data dictionary directly (no from_session classmethod exists) state = CartState(session.data) # 3. Read operations pull from session.data print(state.items) # [ ] print(state.coupon) # "SAVE20" # 4. Write operations push to session.data and mark the session dirty state.items.append( ) state.coupon = "SAVE30" print(session.data["items"]) # [ , ] print(session.data["coupon"]) # "SAVE30" print(session.is_dirty) # True (marked dirty automatically!) State Examples & Controller Binding CartState Integrate typed states into controllers using the bare @stateful decorator and a type-hinted state argument: from aquilia import Controller, Post from aquilia.sessions import stateful from aquilia.sessions.state import CartState class CartController(Controller): prefix = "/cart" # Use bare @stateful decorator. Do NOT pass CartState as argument. # The decorator inspects type-hints of the 'state' parameter. @Post("/add") @stateful async def add(self, ctx, state: CartState): product = await ctx.request.json() state.items.append(product) state.subtotal += product.get("price", 0.0) return ctx.json( ) UserPreferencesState from aquilia import Controller, Get, Post from aquilia.sessions import stateful from aquilia.sessions.state import UserPreferencesState class SettingsController(Controller): prefix = "/settings" @Get("/") @stateful async def get_prefs(self, ctx, state: UserPreferencesState): return ctx.json( ) @Post("/") @stateful async def update_prefs(self, ctx, state: UserPreferencesState): body = await ctx.request.json() if "theme" in body: state.theme = body["theme"] if "locale" in body: state.language = body["locale"] return ctx.json( ) )
Go to Homepage