SessionInterface

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 :meth:open_session and :meth:save_session, the others have useful defaults which you don't need to change.

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

class Session(dict, SessionMixin):
    pass

If :meth:open_session returns None Flask will call into :meth: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 :class: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 :attr:flask.Flask.session_interface::

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

Multiple requests with the same session may be sent and handled concurrently. When implementing a new session interface, consider whether reads or writes to the backing store must be synchronized. There is no guarantee on the order in which the session for each request is opened or saved, it will occur in the order that requests begin and end processing.

Attributes

Attribute	Type	Description
null_session_class	= NullSession	:meth:`make_null_session` will look here for the class that should be created when a null session is requested. Likewise the :meth:`is_null_session` method will perform a typecheck against this type.
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.

Methods

`make_null_session()`

@classmethod
def make_null_session(
    app: [Flask](../app/flask.md?sid=flask_app_flask)
) - > [NullSession](nullsession.md?sid=flask_sessions_nullsession)

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 :attr:null_session_class by default.

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.

Returns

Type	Description
`[NullSession](nullsession.md?sid=flask_sessions_nullsession)`	An instance of the null session class.

`is_null_session()`

@classmethod
def is_null_session(
    obj: object
) - > bool

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 :attr:null_session_class by default.

Parameters

Name	Type	Description
obj	`object`	The object to check.

Returns

Type	Description
`bool`	True if the object is a null session, False otherwise.

`get_cookie_name()`

@classmethod
def get_cookie_name(
    app: [Flask](../app/flask.md?sid=flask_app_flask)
) - > str

The name of the session cookie. Usesapp.config["SESSION_COOKIE_NAME"].

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.

Returns

Type	Description
`str`	The name of the session cookie.

`get_cookie_domain()`

@classmethod
def get_cookie_domain(
    app: [Flask](../app/flask.md?sid=flask_app_flask)
) - > str | None

The value of the Domain parameter on the session cookie. If not set, browsers will only send the cookie to the exact domain it was set from. Otherwise, they will send it to any subdomain of the given value as well. Uses the :data:SESSION_COOKIE_DOMAIN config.

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.

Returns

Type	Description
`str	None`

`get_cookie_path()`

@classmethod
def get_cookie_path(
    app: [Flask](../app/flask.md?sid=flask_app_flask)
) - > str

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.

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.

Returns

Type	Description
`str`	The path for which the session cookie is valid.

`get_cookie_httponly()`

@classmethod
def get_cookie_httponly(
    app: [Flask](../app/flask.md?sid=flask_app_flask)
) - > bool

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

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.

Returns

Type	Description
`bool`	True if the session cookie should be HTTP-only, False otherwise.

`get_cookie_secure()`

@classmethod
def get_cookie_secure(
    app: [Flask](../app/flask.md?sid=flask_app_flask)
) - > bool

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

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.

Returns

Type	Description
`bool`	True if the session cookie should be secure (sent only over HTTPS), False otherwise.

`get_cookie_samesite()`

@classmethod
def get_cookie_samesite(
    app: [Flask](../app/flask.md?sid=flask_app_flask)
) - > str | None

Return 'Strict' or 'Lax' if the cookie should use the SameSite attribute. This currently just returns the value of the :data:SESSION_COOKIE_SAMESITE setting.

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.

Returns

Type	Description
`str	None`

`get_cookie_partitioned()`

@classmethod
def get_cookie_partitioned(
    app: [Flask](../app/flask.md?sid=flask_app_flask)
) - > bool

Returns True if the cookie should be partitioned. By default, uses the value of :data:SESSION_COOKIE_PARTITIONED.

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.

Returns

Type	Description
`bool`	True if the session cookie should be partitioned, False otherwise.

`get_expiration_time()`

@classmethod
def get_expiration_time(
    app: [Flask](../app/flask.md?sid=flask_app_flask),
    session: [SessionMixin](sessionmixin.md?sid=flask_sessions_sessionmixin)
) - > datetime | None

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.

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.
session	`[SessionMixin](sessionmixin.md?sid=flask_sessions_sessionmixin)`	The session object.

Returns

Type	Description
`datetime	None`

`should_set_cookie()`

@classmethod
def should_set_cookie(
    app: [Flask](../app/flask.md?sid=flask_app_flask),
    session: [SessionMixin](sessionmixin.md?sid=flask_sessions_sessionmixin)
) - > bool

Used by session backends to determine if a Set-Cookie header should be set for this session cookie for this response. If the session has been modified, the cookie is set. If the session is permanent and the SESSION_REFRESH_EACH_REQUEST config is true, the cookie is always set. This check is usually skipped if the session was deleted.

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.
session	`[SessionMixin](sessionmixin.md?sid=flask_sessions_sessionmixin)`	The session object.

Returns

Type	Description
`bool`	True if a Set-Cookie header should be sent for the session, False otherwise.

`open_session()`

@classmethod
def open_session(
    app: [Flask](../app/flask.md?sid=flask_app_flask),
    request: [Request](../wrappers/request.md?sid=flask_wrappers_request)
) - > SessionMixin | None

This is called at the beginning of each request, after pushing the request context, before matching the URL. This must return an object which implements a dictionary-like interface as well as the :class:SessionMixin interface. This will return None to indicate that loading failed in some way that is not immediately an error. The request context will fall back to using :meth:make_null_session in this case.

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.
request	`[Request](../wrappers/request.md?sid=flask_wrappers_request)`	The incoming request object.

Returns

Type	Description
`SessionMixin	None`

`save_session()`

@classmethod
def save_session(
    app: [Flask](../app/flask.md?sid=flask_app_flask),
    session: [SessionMixin](sessionmixin.md?sid=flask_sessions_sessionmixin),
    response: [Response](../wrappers/response.md?sid=flask_wrappers_response)
) - > None

This is called at the end of each request, after generating a response, before removing the request context. It is skipped if :meth:is_null_session returns True.

Parameters

Name	Type	Description
app	`[Flask](../app/flask.md?sid=flask_app_flask)`	The Flask application instance.
session	`[SessionMixin](sessionmixin.md?sid=flask_sessions_sessionmixin)`	The session object to save.
response	`[Response](../wrappers/response.md?sid=flask_wrappers_response)`	The response object to which the session cookie might be added.

Returns

Type	Description
`None`	This method does not return any value.

Attributes​

Methods​

make_null_session()​

Parameters​

Returns​

is_null_session()​

Parameters​

Returns​

get_cookie_name()​

Parameters​

Returns​

get_cookie_domain()​

Parameters​

Returns​

get_cookie_path()​

Parameters​

Returns​

get_cookie_httponly()​

Parameters​

Returns​

get_cookie_secure()​

Parameters​

Returns​

get_cookie_samesite()​

Parameters​

Returns​

get_cookie_partitioned()​

Parameters​

Returns​

get_expiration_time()​

Parameters​

Returns​

should_set_cookie()​

Parameters​

Returns​

open_session()​

Parameters​

Returns​

save_session()​

Parameters​

Returns​

Attributes

Methods

`make_null_session()`

Parameters

Returns

`is_null_session()`

Parameters

Returns

`get_cookie_name()`

Parameters

Returns

`get_cookie_domain()`

Parameters

Returns

`get_cookie_path()`

Parameters

Returns

`get_cookie_httponly()`

Parameters

Returns

`get_cookie_secure()`

Parameters

Returns

`get_cookie_samesite()`

Parameters

Returns

`get_cookie_partitioned()`

Parameters

Returns

`get_expiration_time()`

Parameters

Returns

`should_set_cookie()`

Parameters

Returns

`open_session()`

Parameters

Returns

`save_session()`

Parameters

Returns