Session variables are persistent variables that continue to exist between requests. They can be used to maintain session state information for the lifetime of the client's visit to the site and beyond. PSE uses client cookies to track a session variable. The life of the cookie is the duration of the browsing session by default. You can change this to be any duration you want by editing the CookieExpires setting in the pse.conf file.
Unlike other frameworks, session management in PSE is automatic. You have to neither explicitly initialize nor save sessions to use the session variables. When there is a servlet error, sessions are rolled back to the original state as though the page was never run. You can explicity force the saving of a session at any time to bypass this, however.
Session variables are accessed as a dictionary of key/value pairs. Any value that is picklable by Python can be stored in a session variable, although it is highly recommended that you only store standard, builtin Python types. User defined class code can change since the object was originally stored, resulting in unpredictable and/or undesirable behavor of the stored objects. However, PSE does not place any restrictions on this, leaving you to make the best judgement for your application.
You can access the standard session dictionary using the pse.plugins.session.new() function as in the following example:
from pse.plugins import session my_session = session.new()Listing 1: Accessing the session dictionary.
In this example, the my_session variable is now a persistent dictionary that can store key/value pairs for the duration of the session. Note that although the function being called is new, you're not actually creating a new session. You're just getting a reference to the standard session dictionary.
You can separate sessions into different namespaces by providing a session dictionary name parameter to the new function, as in the following example:
named_session = session.new('spam')
Listing 2: Accessing a named session dictionary.
In this case, the session dictionary named "spam" will be accessed, which is a different dictionary in the same session. Using this mechanism you can avoid key conflicts in different parts of the application by using differently named dictionaries. It is possible to delete a named session dictionary by using the delete function, as in the following example:
session.delete('spam')
Listing 3: Deleteing a named session dictionary.
Is not possible to delete the standard session, although you can delete all the entries by using the standard clear method for dictionary objects.
All changes made to session variables will be automatically saved at the finish of the servlet, which means you don't have to explicitly tell PSE to save the session for the changes to persist. In the case that the servlet fails because of an uncaught exception, the session will not be saved. This is desirable in most situations, however you can bypass this behavior by calling the save function to force commital of any changes made to the session to that point:
session.save()Listing 4: Explicitly saving all session changes.
For more information about sessions, please see the PSE User's Manual.
Here is a simple example of how sessions can be used.
<html>
<head>
<title>PSE Session Example</title>
</head>
<body>
<? if name: ?>
Hello, <?=name ?>!
<? :else: ?>
I don't know who you are.
<? :if ?>
</body>
</html>
Listing 5: session_test.pt
from pse.plugins import session
# get the session dictionary
s = session.new()
# first, check to see if there is name in the GET/POST variables
if pse.form.has_key('name'):
# yes, assign it to the name variable and store in the session
name = s['name'] = pse.form['name']
else:
# name not in the form variables, so see if it's in the session
if s.has_key('name'):
# yes, assign to name
name = s['name']
else:
# no, name is not set
name = None
Listing 6: session_test.py
The first time you call session_test.pt, you'll see the message, "I don't know who you are." Calling session_test.pt?name=Nick results in "Hello, Nick!" Further calls to session_test.pt will also return "Hello, Nick!" thanks to the session variable being used.