If you have the
Flask.secret_key set you can use sessions in Flask applications. A session basically makes it possible to remember information from one request to another. The way Flask does this is by using a signed cookie. So the user can look at the session contents, but not modify it unless they know the secret key, so make sure to set that to something complex and unguessable.
To access the current session you can use the
The session object works pretty much like an ordinary dict, with the difference that it keeps track on modifications.
This is a proxy. See Notes On Proxies for more information.
The following attributes are interesting:
True if the session is new,
True if the session object detected a modification. Be advised that modifications on mutable structures are not picked up automatically, in that situation you have to explicitly set the attribute to
True yourself. Here an example:
# this change is not picked up because a mutable object (here # a list) is changed. session['objects'].append(42) # so mark it as modified yourself session.modified = True
If set to
True the session lives for
permanent_session_lifetime seconds. The default is 31 days. If set to
False (which is the default) the session will be deleted when the user closes the browser.
New in version 0.8.
The session interface provides a simple way to replace the session implementation that Flask is using.
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
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
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
app = Flask(__name__) app.session_interface = MySessionInterface()
New in version 0.8.
Helpful helper method that returns the cookie domain that should be used for the session cookie if session cookies are used.
Returns True if the session cookie should be httponly. This currently just returns the value of the
SESSION_COOKIE_HTTPONLY config var.
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
Returns True if the cookie should be secure. This currently just returns the value of the
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.
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.
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.
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
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)
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.
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.
The default session interface that stores sessions in signed cookies through the
the hash function to use for the signature. The default is sha1
the name of the itsdangerous supported key derivation. The default is hmac.
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.
Base class for sessions based on signed cookies.
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.
Expands a basic dictionary with an accessors that are expected by Flask extensions and users for the session.
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
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
this reflects the
'_permanent' key in the dict.
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:
PERMANENT_SESSION_LIFETIME config key can also be an integer starting with Flask 0.8. Either catch this down yourself or use the
permanent_session_lifetime attribute on the app which converts the result to an integer automatically.