Myghty Documentation
Version: 1.2 Last Updated: 07/07/10 12:55:17
View: Paged  |  One Page
Table of Contents
Previous: Filtering and Flushing (and Escaping)   |   Next: Data Caching
Session
Basic Usage
Session Options
Session Methods
Session Members
Using the Session Object Standalone

Myghty now has its own session storage class. This class offers some advantages over the mod python session, including:

  • It is independent of mod_python, so it works with either version of Apache, other web connectors, and in CGI mode
  • The file-based version keeps each user's session in separate DBM files, so no synchronization issues are present between disparate sessions, session files are small, and old sessions can be cleaned up via an external file-deletion process.
  • The session object loads its data in immediately from the persistent store and unlocks, so that a page containing multiple session-enabled requests (i.e., such as a page with IFRAMEs or image delivery servlets) can allow access to all of its sub-elements with a minimum of waiting between the concurrent requests.
  • The package can also run directly with the mod_python request, independently of Myghty.
Basic Usage

The session is retrieved from the request object via the get_session() method, operated upon like a dictionary, and then can have its save() method called to write its data to persistent storage:

<%python scope="init">
    # get the session
    session = m.get_session()
    
    # add data
    session['key1'] = 'foo'
    
    # get data
    if session.has_key('user'):
        user = session['user']
    else:
        user = User()
        session['user'] = user
        
    # save new information
    session.save()
</%python>

The session handles generation of session IDs automatically as well as storing and retrieving them from cookies. Options exist to pass in custom session IDs, to not use cookies, to use "signed" session IDs, and to change the cookie-based session key (defaulting to myghty_session_id). It loads its data in fully when instantiated and then unlocks, so no programmatic locking or unlocking is necessary (but lock methods are available if you want the session to stay locked throughout a request).

back to section top
Session Options

Session options are specified as Myghty configuration parameters in the form session_XXXX, to identify them as options being sent to the Session object. When calling the m.get_session() method, parameters may be specified with or without the "session_" prefix; they are stripped off.

The get_session method can take any of the configuration parameters that are identified below as used directly by the Session object or by the underlying Namespace objects.

session_cookie_expires (boolean, datetime, timedelta)
default: True
used by: Session

The expiration time to use on the session cookie. Defaults to "True" which means, dont specify any expiration time (the cookie will expire when the browser is closed). A value of "False" means, never expire (specifies the maximum date that can be stored in a datetime object and uses that). The value can also be a datetime.timedelta() object which will be added to the current date and time, or a datetime.datetime() object.

session_data_dir (string)
default: None
used by: Session

The data directory where sessions will be stored. If this argument is not present, the regular data_dir parameter is used, with the path "./sessions" appended to it.

session_dbmmodule (dbm module)
default: anydbm
used by: DBMNamespace

When dbm is used as the session type, this parameter points to a module to use for DBM support, such as gdbm, dbhash, etc.

session_id (String)
default: None
used by: Session

Session id for this session. When using sessions with cookies, this parameter is not needed as the session automatically creates, writes and retrieves the value from the request. When using a URL-based method for the session, the id should be retreived from the id data member when the session is first created, and then used in writing new URLs.

session_invalidate_corrupt (boolean)
default: False
used by: Session

If there are any exceptions upon loading the session, the entire session will be invalidated and started clean. When object interfaces change in an application, old versions of those objects might still be present in existing session files, and exceptions will be raised when the session object tries to deserialize them into memory. Setting this to True allows those sessions to be cleaned out and started from scratch again.

This parameter should be used carefully since it can conceal real application errors in certain situations.
session_key (string)
default: myghty_session_id
used by: Session

The key that will be used as a cookie key to identify sessions. Changing this could allow several different applications to have different sessions underneath the same hostname.

session_log_file (file)
default: None
used by: Session

A file or buffer object where debugging information will be sent.

session_namespace_class (class)
default: None
used by: Session

A class that will be used to create the underlying NamespaceManager used by this Session, when a custom NamespaceManager implementation is being used. By default, the implementation is determined among the built-in NamespaceManagers by the session_type parameter.

session_type (string)
default: dbm
used by: Session

Type of storage used for the session, current types are "dbm" (also called "file"), and "memory". The storage uses the Container API that is also used by the cache system.

When using dbm files, each user's session is stored in its own dbm file, via the class myghty.container.DBMNamespaceManager class. To get the dbm filename used by a session, use session.namespace.file.path, or to retrieve a list of the actual files created by the particular dbm instance, use session.namespace.file.get_filenames().

session_secret (string)
default: None
used by: Session

Secret key to enable encrypted session ids. When non-None, the session ids are generated with an MD5-signature created against this value.

session_timeout (integer)
default: None
used by: Session

Time in seconds before the session times out. A timeout occurs when the session has not been loaded for more than timeout seconds.

session_use_cookies (boolean)
default: True
used by: Session

Whether or not to store and retrieve the session ID from the cookies present in the request. If False, the session ID must be present in the argument list to retrieve an existing session.

use_modpython_session (boolean)
default: None
used by: ApacheHandler

Instructs the get_session() method, or the global variable s if configured, to return an instance of the mod_python session object instead of the Myghty session object. If this is configured, only the session_timeout parameter is supported.

use_session (boolean)
default: None
used by: ApacheHandler,CGIHandler

Establishes the global variable s as a reference to the Session object. This means all requests will automatically have the session initialized and loaded. If an application has a lot of templates that dont have use for the session, this could add unnecessary overhead.

back to section top
Session Methods
delete()
deletes the persistent storage for this session, but the session remains valid. When save() is called, the new data will be written.
invalidate()
invalidates this session, creates a new session id, returns to the is_new state
load()
Loads the data from this session from persistent storage and updates the last modified time of the session. This method is called automatically upon session object construction and does not need to be called explicitly. If the session's persistant storage does not exist, it will be created. If the session has not been accessed since the timeout period, the invalidate() method will be called, and the session will return to the is_new state, as well as was_invalidated.
lock()
Locks this session against other accesses. This method is called automatically by the load() and save() methods. However, this method can be called to keep the session locked persistently until explicitly unlocked by the unlock() method.
unlock()
Unlocks this session against other accesses. This method is called automatically by the load() and save() methods. However, this method can be called to unlock a persistent lock set up by the lock() method.
save()
Saves the data for this session to persistent storage. This should be called whenever you know the session has been modified.
back to section top
Session Members
accessed
The last time this session was accessed.
created
The time this session was created.
id

The id for this session. When using cookies, this is retrieved and set within the cookie referenced by the key string. The id is automatically created when a new session is instantiated.

When regular cookies are used (the default), this value is the same value sent in the session cookie to the client. When signed cookies are enabled via the session_secret parameter, this id is MD5 signed against the secret to form the client cookie value.

is_new
True if this session was newly created. This can be because no previous session existed, or the session existed but was invalidated, usually due to a timeout.
key
The key used in cookies to set this session's id.
secret
timeout
The timeout span of this session.
was_invalidated
True if this session was invalidated upon opening, usually due to a timeout. is_new will always be True as well.
back to section top
Using the Session Object Standalone

The session object is actually functionally independent of the rest of Myghty, and is compatible with the mod python request object directly, as well as the request emulator used by CGIHandler. To instantiate it, simply use its constructor as follows:

from mod_python import apache
from myghty.session import Session

def handle(req):
    session = Session(req, data_dir='/path/to/session_dir', key='user_session_id')

The full constructor signature for the Session object is as follows:

Session(request, id = None, use_cookies = True, 
    invalidate_corrupt = False,
    type = None, data_dir = None, 
    key = 'myghty_session_id', timeout = None, 
    secret = None, log_file = None, **params)

Note that the parameters are the same as the configuration arguments with the prefix "session_" removed.

back to section top
Previous: Filtering and Flushing (and Escaping) | Next: Data Caching