Sessions

This module contains some helper classes that help one to add session support to a python WSGI application. For full client-side session storage see securecookie which implements a secure, client-side session storage.

Application Integration

from werkzeug.contrib.sessions import SessionMiddleware, \
     FilesystemSessionStore

app = SessionMiddleware(app, FilesystemSessionStore())

The current session will then appear in the WSGI environment as werkzeug.session. However it’s recommended to not use the middleware but the stores directly in the application. However for very simple scripts a middleware for sessions could be sufficient.

This module does not implement methods or ways to check if a session is expired. That should be done by a cronjob and storage specific. For example to prune unused filesystem sessions one could check the modified time of the files. It sessions are stored in the database the new() method should add an expiration timestamp for the session.

For better flexibility it’s recommended to not use the middleware but the store and session object directly in the application dispatching:

session_store = FilesystemSessionStore()

def application(environ, start_response):
    request = Request(environ)
    sid = request.cookies.get('cookie_name')
    if sid is None:
        request.session = session_store.new()
    else:
        request.session = session_store.get(sid)
    response = get_the_response_object(request)
    if request.session.should_save:
        session_store.save(request.session)
        response.set_cookie('cookie_name', request.session.sid)
    return response(environ, start_response)

Reference

class werkzeug.contrib.sessions.Session(data, sid, new=False)

Subclass of a dict that keeps track of direct object changes. Changes in mutable structures are not tracked, for those you have to set modified to True by hand.

sid

The session ID as string.

new

True is the cookie was newly created, otherwise False

modified

Whenever an item on the cookie is set, this attribute is set to True. However this does not track modifications inside mutable objects in the session:

>>> c = Session({}, sid='deadbeefbabe2c00ffee')
>>> c["foo"] = [1, 2, 3]
>>> c.modified
True
>>> c.modified = False
>>> c["foo"].append(4)
>>> c.modified
False

In that situation it has to be set to modified by hand so that should_save can pick it up.

should_save

True if the session should be saved.

Changed in version 0.6: By default the session is now only saved if the session is modified, not if it is new like it was before.

class werkzeug.contrib.sessions.SessionStore(session_class=None)

Baseclass for all session stores. The Werkzeug contrib module does not implement any useful stores besides the filesystem store, application developers are encouraged to create their own stores.

Parameters:session_class – The session class to use. Defaults to Session.

delete(session)

Delete a session.

generate_key(salt=None)

Simple function that generates a new session key.

get(sid)

Get a session for this sid or a new session object. This method has to check if the session key is valid and create a new session if that wasn’t the case.

is_valid_key(key)

Check if a key has the correct format.

new()

Generate a new session.

save(session)

Save a session.

save_if_modified(session)

Save if a session class wants an update.

class werkzeug.contrib.sessions.FilesystemSessionStore(path=None, filename_template='werkzeug_%s.sess', session_class=None, renew_missing=False, mode=420)

Simple example session store that saves sessions on the filesystem. This store works best on POSIX systems and Windows Vista / Windows Server 2008 and newer.

Changed in version 0.6: renew_missing was added. Previously this was considered True, now the default changed to False and it can be explicitly deactivated.

Parameters:

• path – the path to the folder used for storing the sessions. If not provided the default temporary directory is used.
• filename_template – a string template used to give the session a filename. %s is replaced with the session id.
• session_class – The session class to use. Defaults to Session.
• renew_missing – set to True if you want the store to give the user a new sid if the session was not yet saved.

list()

Lists all sessions in the store.

New in version 0.6.

class werkzeug.contrib.sessions.SessionMiddleware(app, store, cookie_name='session_id', cookie_age=None, cookie_expires=None, cookie_path='/', cookie_domain=None, cookie_secure=None, cookie_httponly=False, environ_key='werkzeug.session')

A simple middleware that puts the session object of a store provided into the WSGI environ. It automatically sets cookies and restores sessions.

However a middleware is not the preferred solution because it won’t be as fast as sessions managed by the application itself and will put a key into the WSGI environment only relevant for the application which is against the concept of WSGI.

The cookie parameters are the same as for the dump_cookie() function just prefixed with cookie_. Additionally max_age is called cookie_age and not cookie_max_age because of backwards compatibility.