Flask Session Interface API
SessionInterface is the low-level abstraction of Session, allowing you to replace Flask's default Cookie storage with external storage such as Redis, databases, etc.
Custom implementations only need to inheritSessionInterfaceand implement two methods.
SessionInterface Abstract Base Class
| Attributes/Methods | Description |
|---|---|
| null_session_class | The class used when Session is unavailable. Defaults to NullSession |
| pickle_based | bool, whether Session is based on pickle serialization. Default is False |
| open_session(app, request) | Read Session data from the request. Return a SessionMixin instance or None |
| save_session(app, session, response) | Save Session data to the response |
| make_null_session(app) | Create an empty Session (automatically called when open_session returns None) |
| is_null_session(obj) | Determine whether it is a NullSession instance |
Cookie options method
The following methods are used to obtain attributes of the Session Cookie and can be overridden:
| Methods | Description |
|---|---|
| get_cookie_name(app) | Get the Cookie name. Default reads the SESSION_COOKIE_NAME config |
| get_cookie_domain(app) | Get Cookie Domain. Default reads SESSION_COOKIE_DOMAIN configuration |
| get_cookie_path(app) | Get Cookie Path. Default reads SESSION_COOKIE_PATH or APPLICATION_ROOT |
| get_cookie_httponly(app) | Get HttpOnly flag. Default reads SESSION_COOKIE_HTTPONLY |
| get_cookie_secure(app) | Get the Secure flag. Default reads SESSION_COOKIE_SECURE |
| get_cookie_samesite(app) | Get SameSite value. Default reads SESSION_COOKIE_SAMESITE |
| get_cookie_partitioned(app) | Get Partitioned flag. Default reads SESSION_COOKIE_PARTITIONED (v3.1+) |
| get_expiration_time(app, session) | Get the Session expiration time. Permanent Session returns now + lifetime |
| should_set_cookie(app, session) | Determine whether a Cookie needs to be set. Returns True when the Session is modified or permanent + SESSION_REFRESH_EACH_REQUEST |
Built-in Implementations
| Class | Description |
|---|---|
| SecureCookieSessionInterface | Default implementation. Use itsdangerous signed Cookie to store Session data. key_derivation="hmac", digest_method=sha1 |
| SecureCookieSession | Session class based on CallbackDict. Detects modifications to top-level keys and automatically sets modified=True |
| NullSession | A placeholder Session used when SECRET_KEY is not set. Reading works normally, modifying raises an error. |
| SessionMixin | Mixin for Session classes. Provides permanent, new, modified, accessed properties |
Replace the default Session implementation
Example
from flask import Flask
from flask.sessions import SessionInterface, SessionMixin
# Custom Session class
class MySession(dict, SessionMixin):
pass
# Custom Session interface
class MySessionInterface(SessionInterface):
def open_session(self, app, request):
# Load Session from request
user_id = request.headers.get("X-User-ID")
if user_id:
return MySession(user_id=user_id)
return MySession()
def save_session(self, app, session, response):
# Save Session to response
if "user_id" in session:
response.headers["X-Session-ID"] = session["user_id"]
app = Flask(__name__)
# Replace the default Session implementation
app.session_interface = MySessionInterface()
from flask.sessions import SessionInterface, SessionMixin
# Custom Session class
class MySession(dict, SessionMixin):
pass
# Custom Session interface
class MySessionInterface(SessionInterface):
def open_session(self, app, request):
# Load Session from request
user_id = request.headers.get("X-User-ID")
if user_id:
return MySession(user_id=user_id)
return MySession()
def save_session(self, app, session, response):
# Save Session to response
if "user_id" in session:
response.headers["X-Session-ID"] = session["user_id"]
app = Flask(__name__)
# Replace the default Session implementation
app.session_interface = MySessionInterface()