1.11.12.1 Manager Objects

The SessionManager object is aliased as web.session.manager and should be used as web.session.manager.

class SessionManager( driver, [expire=86400], [cookie], [autoCreate=0], [_seed], [_cleanupProbability], [**driverParams])

Used to return a session manager object.

Manager Parameters:

driver and **driverParams

If driver is a string, any extra parameters passed to the web.session.manager() function are passed onto the web.session.driver() function to create a driver. Alternatively driver can be a Driver object as returned by web.session.driver() and no **driverParams need to be specified.

expire

The number of seconds a newly created session should be valid for. If not specified the default is 86400 seconds which is 24 hours.

cookie

A dictionary specifying any parameters which you would like the session cookie to have. The defaults used are specified in web.session.cookieDefaults.

In particular you may wish to modify the following parameters:

path: The path of the domain specified by domain for which the cookie is valid. If not specified the default is '/' which means the whole website. XXX is this correct?
domain: The domain for which the cookie is valid. If not specified the default is '' which means any domain. XXX is this correct?
comment: An optional comment for your cookie to explain what it does or who set it
max-age: The length of time in seconds the cookie should be valid for. If set to 0 the cookie will expire immediately. If not present the cookie will take the expire time of the session. If set to None the cookie will last until the web browser is closed.

By default the max-age of the cookie is set to be the same as the expire time set by the expire parameter.

autoCreate

If set to True the necessary tables will be created (removing any existing tables) if any of the tables are missing. This is designed for easy testing of the module.

_seed

When generating session IDs it is important a hacker cannot guess what the next session ID will be otherwise they could make a cookie so that the application thinks they are someone else. You can specify a _seed which is simply a string to make the generation of session IDs even more random. The default is 'PythonWeb'.

_cleanupProbability

Every so often expired sessions and their corresponding data need to be removed from the session store. There is a probability specified by _cleanupProbability that this cleanup will occur when a manager object is created. If _cleanupProbability is 1 cleanup is done every time a manager is created. If _cleanupProbability is 0 no automatic cleanup is done and cleanup is left to the administrator. The default is 0.05 which means old session information is removed roughly every 20 times a manager object is created.

All session manager objects have the read only member variables which you should not set:

sessionID: The session ID for the current session. This is a unique 32 character string set after a session is created or loaded. It is None before that time.

expire: The expire length in seconds (the minimum length of the session)

_seed: The default seed used to generate the session ID

cookie: A dictionary containing the cookie parameters.

error: If an error occurred loading a session, for example the session ID did not exist or had expired, the error is available through this attribute. If no error occurred the value is None.

_cleanupProbability: The probability of checking for, and removing expired sessions

response_headers: A list of cookie headers in the WSGI format (type, value)

sent_headers: A list of the cookie headers printed after sendCookieHeaders() has been called. Useful for debugging

completeSessionEnvironment( ): Returns True if the environment is correctly setup, False otherwise. In the case of the database driver this method simply checks that all the necessary tables exist.

createSessionEnvironment( ): Creates the necessary environment. In the case of the database driver this method creates all the required tables. If any of the tables already exist a SessionError is raised.

removeSessionEnvironment( [ignoreErrors=False]): Removes the environment. In the case of the database driver this method drops all the tables. If any of the tables are not present a SessionError is raised unless ignoreErrors is True.

load( [sessionID=None]): Attempt to load the session with the session ID sessionID. If sessionID is not specified the session ID is obtained from a cookie using os.environ. If your environment doesn't support loading of a cookie in this way seesionID should be specified. If the session exists and is valid it is loaded and the method returns True otherwise it returns False and you should create a new session using create(). The reason the session could not be loaded is set to the error attribute.

create( [sendCookieHeaders=True], [expire]): Generate a new session ID and start a new session with it. If after 100 attempts no new session ID has been created because the IDs generated already exist, a SessionError is raised. self._seed is specified it is used to make the generation of session ID more random.
If sendCookieHeaders is True a Set-Cookie HTTP header is immediately printed. If False a WSGI (type, info) header is appended to response_headers so the application can handle the header itself. If expire is the number of seconds the session should be valid for. If not specified the value of the expire attribute is used. Returns the new session ID.

store( app): Return a session store object for manipulating values in the application's store. app is the application name as a string made up of the characters a-z, A-Z, 0-9 and -_.. The application name must be between 1 and 255 characters in length. The application names do not have to be the same as application names used by the web.auth module, although these are the most appropriate choices. If you are not using multiple applications you should still give your application a name, perhaps 'default' for example.

destroy( [sessionID], [sendCookieHeaders=True], [ignoreWarning=False]): Remove all session information for the session. If sessionID is specified all session information for sessionID is removed. If sendCookieHeaders is True a Set-Cookie HTTP header is immediately printed. If False a WSGI (type, info) header is appended to response_headers so the application can handle the header itself. If ignoreWarning is not set to True a SessionWarning is raised explaining why destroying sessions is not a good idea.
Warning: Destroying sessions is strongly not recommended since any other application currently using the session store may crash as the session information will have been removed. If you wish to remove all data from the session store it would be better to use the store object's empty() method, emptying the store but leaving the session intact. If you must remove a session use setExpire(time.time()) to make the session expire immediately or send a cookie built with _deleteCookieString(). Any applications using the session will still be able to access the information if they have already loaded the session but will not be able to load the session again.

cookieSessionID( [environ=None], [noSessionID='']): Obtain a session ID from the HTTP_COOKIE environmental variable. The default environ dictionary is os.environ. If you wish to provide your own environment dictionary (for example you are using a WSGI application) you can specify environ. If the session ID cannot be loaded noSessionID is returned which by default is an empty string.

cleanup( [min], [max], [ignoreWarning=False]): Remove and information related to sessions which have expired between the times min and max. All times are in seconds since the epoch (00:00:00 UTC, January 1, 1970). If min is not specified it is assumed to be 0 (the beginning of the epoch), if max is not specified it is assumed to be the current time. If you specify a value max greater than the current time returned bt time.time() a SessionWarning is raised. To ignore the warning set ignoreWarning to True.
Warning: You should not set a value of max greater than the current time unless you understand the risk since doing so will remove sessions which haven't yet expired. If an application is using the session store and its session is cleaned up, that application may crash.

setExpire( expireTime, [sessionID]): The method is used to change the time an existing session will expire or to set a new expiry date if it has already expired. expireTime is the time you want the session to expire in seconds since the epoch (00:00:00 UTC, January 1, 1970). expireTime is NOT the extra number of seconds to allow the session to exist for. If sessionID is specified the expire time of the session with ID sessionID is updated, otherwise the current session expire time is modified.

valid( [sessionID]): If sessionID is specified the validity of the session with ID sessionID is checked. Otherwise the current session is checked. Returns True if the session is valid, False if the session has expired. A SessionError is raised if the session does not exist. Whether or not a session exists can be checked with the exists() method.

exists( [sessionID]): If sessionID is specified the session with ID sessionID is checked. Otherwise the current session is checked. Returns True if the session is exists, False if the session does not exist. No comment is made on whether or not the session is still valid, instead this can be checked with the valid() method.

sendCookieHeaders( ): Uses Python's print statement to send any headers in the response_headers attribute to the standard output, appending the exact strings printed to the send_headers attribute for debugging purposes. Used by the create() and destroy() methods to send cookie headers so could be over-ridden in derived classes to change cookie handling behaviour.

setCookie( [sendCookieHeaders=False], [_cookieString=None]): Get a cookie string from _setCookieString() to set a new cookie, parse the string into a WSGI (type, info) pair and append it to the response_headers attribute. If sendCookieHeaders is True, sendCookieHeaders() is called to send the cookie header. _cookieString can be used to specify the cookie to set, if None the cookie string is automatically generated.

_setCookieString( [maxAge]): Returns an HTTP header to set a cookie using the default cookie values set in the class constructor. max-age is the length of time in seconds the cookie should last.

deleteCookie( [sendCookieHeaders=False]): Get a cookie string from _deleteCookieString() to set the expire time of the cookie to one second, parse it into a WSGI (type, info) pair and append it to the response_headers attribute. If sendCookieHeaders is True, sendCookieHeaders() is called to send the cookie header.

_deleteCookieString( ): Returns an HTTP header to set the expire time of the session cookie to 1 second, effectively forcing it to expire.