The session context, usually written as ctx, is the primary conduit of information through the application. As each request is received by the Albatross application, a session context is created on the system that is appropriate to the application and the browser session that sent the request. This is then handed to the handler for the state the application is currently in. When a new session arrives or a request has no current session (eg, it has timed out), the application creates a new session context using the state specified in the application's constructor. Albatross quietly saves the state at the end of each request.
It's a reasonably complex class although most of the visible functionality is obvious; any real complexity is hidden behind the scenes by the Albatross application framework. We'll describe most of the class's functionality here.
The precise contents of the session context depend on the application type that the application has nominated to use. XXX Should we pick one or talk about several?
Ctx.locals is a Python object that contains variables which hold data for the current session. It holds special significance because it is tied in closely with the Albatross tags used in the templating engine. For example, if there was a value set using:
ctx.locals.item_count = 15
This value could be displayed using the templating engine using a tag:
Values can be saved across sessions using the ctx.add_session_vars method. If the application did the following:
ctx.locals.italy = 2 ctx.locals.france = 0 ctx.add_session_vars('italy', 'france')
the values of france and italy would be saved and restored across requests until the session was removed.
Storing values in ctx.locals indiscriminately can lead the size of the session ballooning and slowing the application down. Judicious use of session-local variables (ie, variables not having a add_session_vars applied to them) and use of the del_session_var method can keep your application running smartly.