6. Session Interface¶

The session interface provides a simple way to replace the session implementation that Flask is using.

class flask.sessions.SessionInterface[source]¶

The basic interface you have to implement in order to replace the default session interface which uses werkzeug’s securecookie implementation. The only methods you have to implement are open_session() and save_session(), the others have useful defaults which you don’t need to change.

The session object returned by the open_session() method has to provide a dictionary like interface plus the properties and methods from the SessionMixin. We recommend just subclassing a dict and adding that mixin:

class Session(dict, SessionMixin):
    pass

If open_session() returns None Flask will call into make_null_session() to create a session that acts as replacement if the session support cannot work because some requirement is not fulfilled. The default NullSession class that is created will complain that the secret key was not set.

To replace the session interface on an application all you have to do is to assign flask.Flask.session_interface:

app = Flask(__name__)
app.session_interface = MySessionInterface()

New in version 0.8.

get_cookie_domain(app)[source]¶

Helpful helper method that returns the cookie domain that should be used for the session cookie if session cookies are used.

get_cookie_httponly(app)[source]¶

Returns True if the session cookie should be httponly. This currently just returns the value of the SESSION_COOKIE_HTTPONLY config var.

get_cookie_path(app)[source]¶

Returns the path for which the cookie should be valid. The default implementation uses the value from the SESSION_COOKIE_PATH config var if it’s set, and falls back to APPLICATION_ROOT or uses / if it’s None.

get_cookie_secure(app)[source]¶

Returns True if the cookie should be secure. This currently just returns the value of the SESSION_COOKIE_SECURE setting.

get_expiration_time(app, session)[source]¶

A helper method that returns an expiration date for the session or None if the session is linked to the browser session. The default implementation returns now + the permanent session lifetime configured on the application.

is_null_session(obj)[source]¶

Checks if a given object is a null session. Null sessions are not asked to be saved.

This checks if the object is an instance of null_session_class by default.

make_null_session(app)[source]¶

Creates a null session which acts as a replacement object if the real session support could not be loaded due to a configuration error. This mainly aids the user experience because the job of the null session is to still support lookup without complaining but modifications are answered with a helpful error message of what failed.

This creates an instance of null_session_class by default.

null_session_class¶

make_null_session() will look here for the class that should be created when a null session is requested. Likewise the is_null_session() method will perform a typecheck against this type.

alias of NullSession

open_session(app, request)[source]¶

This method has to be implemented and must either return None in case the loading failed because of a configuration error or an instance of a session object which implements a dictionary like interface + the methods and attributes on SessionMixin.

pickle_based = False¶

A flag that indicates if the session interface is pickle based. This can be used by flask extensions to make a decision in regards to how to deal with the session object.

New in version 0.10.

save_session(app, session, response)[source]¶

This is called for actual sessions returned by open_session() at the end of the request. This is still called during a request context so if you absolutely need access to the request you can do that.

should_set_cookie(app, session)[source]¶

Indicates whether a cookie should be set now or not. This is used by session backends to figure out if they should emit a set-cookie header or not. The default behavior is controlled by the SESSION_REFRESH_EACH_REQUEST config variable. If it’s set to False then a cookie is only set if the session is modified, if set to True it’s always set if the session is permanent.

This check is usually skipped if sessions get deleted.

New in version 0.11.

class flask.sessions.SecureCookieSessionInterface[source]¶

The default session interface that stores sessions in signed cookies through the itsdangerous module.

static digest_method()¶

the hash function to use for the signature. The default is sha1

key_derivation = 'hmac'¶

the name of the itsdangerous supported key derivation. The default is hmac.

salt = 'cookie-session'¶

the salt that should be applied on top of the secret key for the signing of cookie based sessions.

serializer = <flask.sessions.TaggedJSONSerializer object>¶

A python serializer for the payload. The default is a compact JSON derived serializer with support for some extra Python types such as datetime objects or tuples.

session_class¶

alias of SecureCookieSession

class flask.sessions.SecureCookieSession(initial=None)[source]¶

Base class for sessions based on signed cookies.

class flask.sessions.NullSession(initial=None)[source]¶

Class used to generate nicer error messages if sessions are not available. Will still allow read-only access to the empty session but fail on setting.

class flask.sessions.SessionMixin[source]¶

Expands a basic dictionary with an accessors that are expected by Flask extensions and users for the session.

modified = True¶

for some backends this will always be True, but some backends will default this to false and detect changes in the dictionary for as long as changes do not happen on mutable structures in the session. The default mixin implementation just hardcodes True in.

new = False¶

some session backends can tell you if a session is new, but that is not necessarily guaranteed. Use with caution. The default mixin implementation just hardcodes False in.

permanent¶

this reflects the '_permanent' key in the dict.

flask.sessions.session_json_serializer = <flask.sessions.TaggedJSONSerializer object>¶

A customized JSON serializer that supports a few extra types that we take for granted when serializing (tuples, markup objects, datetime).

This object provides dumping and loading methods similar to simplejson but it also tags certain builtin Python objects that commonly appear in sessions. Currently the following extended values are supported in the JSON it dumps:

• Markup objects
• UUID objects
• datetime objects
• tuples