1.10.1 Introduction

You add session handling to your application like this:

import web
import web.session

session = web.session.start(
    storage='file',
    app='test',
    dir='/home/james/session',
    expire=600
)

Every time a script calls the session.start() function a new session is begun unless one already exists. If a new session is created it will last for at least the time set by the expire parameter but may last longer. The default is 14400 seconds or 4 hours. You can set the expire length by setting the expire parameter of the function.

Each application which uses the seession module has its own name. This means that many applications can use the same session without risk of over-writing each others variables. This is useful if a user visits a site which uses the session module for multiple applications as all the applications can use the same cookie.

The session module is implemented in a way which makes it easy to write drivers for more ways of storing session information whilst the user still uses the same interface regardless of the storge driver they are using. In the example above we are using the file driver to store session information in files in the directory /home/james/session. We could have used a database driver in which case we would have passed a web.database cursor to the start() method by specifying the cursor parameter.

The full function specification of the start function is given below:

start( storage, app, [expire=14400,][sessionID=None,][cookie=cookieOptions][seed='Built with Python',][cleanup=1,][cursor=None,][table='Session',][dir=None,])

storage

Storage driver to use. Can be 'database' or 'file'

app

A srting containing the name of the application. Max length 255 characters.

expire

An integer specifying the minimum number of seconds a session should last

sessionID

The sessionID of the user if it is not to be obtained from a cookie

cookie

A dictionary of cookie options in the form:

{
    'path':'/',     # The path for which the cookie is valid.
    'domain':'',    # The domain for which the cookie is valid.
    'comment': "Built in Python using web.session from pythonweb.org",
    'secure':0,     # Use secure cookies.
    'max-age':None, # Max Age.
    'version':1     # Version is always 1
}

If max-age is set to None, it is set to the value of expires. Note: If you choose to use cookies you can set the expire time of the cookie independantly from that of the session. This means the cookie could expire well before the session and the information it contains are actually destroyed. Warning: No error checking is done on the values set in the cookie options.

seed

A string to use as a seed when generating session IDs

cleanup

Probablity of running the session cleanup code to remove expired sessions. 1 means the sessions are always cleaned up. 0 means they are never cleaned up. 0.01 means on average 1 in 100 times a the session.start() function is called, the sessions will be cleaned.

cursor

The web.database object to use to access the database. Only used when storage='database'.

table

A string to add to the front of the database table names so that you can have more than one session store in the same database. Only used when storage='database'.

dir

The directory in which to store sessions when using storage='file'. The directory must have the correct read and write permissions.

See About this document... for information on suggesting changes.