1.11.14.2 Manager Objects

manager( driver, [expire=86400], [path], [domain], [comment], [maxAge], [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.
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.

Cookie 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
maxAge: The length of time in seconds the cookie should be valid for. If set to 0 the cookie will last until the web browser is closed. If not set it will take the value of the expire parameter.

class Manager

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

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 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.

genSessionID( [seed]): Obtain a new session ID based on md5. If after 100 attempts no new session ID has been created because the IDs generated already exist, a SessionError is raised. If seed is specified it is used to make the generation of session ID more random, otherwise the value seed is used.

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( [maxAge], [sendCookieHeaders=False]): 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 maxAge is not specified the default specified in the class creation is used. A maxAge of 0 means the cookie expires when the browser is closed otherwise maxAge should be the length of time in seconds the cookie should remain valid for. If sendCookieHeaders is True, sendCookieHeaders() is called to send the cookie header.

setCookieString( [maxAge]): Returns an HTTP header to set a cookie using the default cookie values set in the class constructor. If maxAge is not specified the default specified in the class creation is used. A maxAge of 0 means the cookie expires when the browser is closed otherwise maxAge should be the length of time in seconds the cookie should remain valid for.

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.