Sessions

Add session support to a WSGI application. For full client-side session storage see secure_cookie.cookie.

Session Store

To have the most control over the session, use a session store directly in your application dispatch. SessionStore.new() creates a new Session with a unique id, and SessionStore.get() gets an existing session by that id. Store the id as a cookie.

from secure_cookie.session import FilesystemSessionStore
from werkzeug.wrappers import Request, Response

session_store = FilesystemSessionStore()

@Request.application
def application(request):
    sid = request.cookies.get("session_id")

    if sid is None:
        request.session = session_store.new()
    else:
        request.session = session_store.get(sid)

    response = Response(do_stuff(request))

    if request.session.should_save:
        session_store.save(request.session)
        response.set_cookie("session_id", request.session.sid)

    return response

Cleanup

This module does not implement a way to check if a session is expired. That should be done by a scheduled job independent of the running application, and is storage-specific. For example, to prune unused filesystem sessions one could check the modified time of the files. If sessions are stored in the database, the new() method could add an expiration timestamp.

Middleware

For simple applications, SessionMiddleware is provided. This makes the current session available in the WSGI environment as the secure_cookie.session key. This is convenient, but not as flexible as using the store directly.

from secure_cookie.session import FilesystemSessionStore
from secure_cookie.session import SessionMiddleware

session_store = FilesystemSessionStore()
app = SessionMiddleware(app, session_store)

API

class secure_cookie.session.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.

property should_save

True if the session should be saved.

class secure_cookie.session.SessionStore(session_class=<class 'secure_cookie.session.Session'>)

Base class for all session stores.

Parameters

session_class – The session class to use.

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 secure_cookie.session.FilesystemSessionStore(path=None, filename_template='secure_cookie_%s.session', session_class=<class 'secure_cookie.session.Session'>, renew_missing=False, mode=420)

Simple example session store that saves sessions on the filesystem.

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.

• renew_missing – Set to True if you want the store to give the user a new sid if the session was not yet saved.

Changed in version 0.1.0: filename_template defaults to secure_cookie_%s.session instead of werkzeug_%s.sess.

delete(session)

Delete a session.

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.

list()

List all sessions in the store.

save(session)

Save a session.

class secure_cookie.session.SessionMiddleware(app, store, cookie_name='session_id', cookie_age=None, cookie_expires=None, cookie_path='/', cookie_domain=None, cookie_secure=None, cookie_httponly=False, cookie_samesite='Lax', environ_key='secure_cookie.session')

A middleware that puts the session object of a store 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.

Changed in version 0.1.0: environ_key defaults to secure_cookie.session instead of werkzeug.session.