Skip to content

Reference

__init__(self, app, secret_key, cookie_name, max_age=1209600, same_site='lax', https_only=False, domain=None, backend_type=None, backend_client=None, custom_session_backend=None) special ¤

Session Middleware

Parameters:

Name Type Description Default
app Callable[[MutableMapping[str, Any], Callable[[], Awaitable[MutableMapping[str, Any]]], Callable[[MutableMapping[str, Any]], Awaitable[NoneType]]], Awaitable[NoneType]]

The ASGIApp

required
secret_key str

The secret key to use.

required
cookie_name str

The name of the cookie used to store the session id.

required
max_age int

The Max-Age of the cookie (Default to 14 days).

1209600
same_site str

The SameSite attribute of the cookie (Defaults to lax).

'lax'
https_only bool

Whether to make the cookie https only (Defaults to False).

False
domain Optional[str]

The domain associated to the cookie (Default to None).

None
backend_type Optional[starlette_session.backends.BackendType]

The type of predefined backend to use (Default to None, if None we'll use a regular cookie backend).

None
backend_client Optional[Any]

The client to use in the predefined backend. See examples for examples with predefined backends (Default to None).

None
custom_session_backend Optional[starlette_session.interfaces.ISessionBackend]

A custom backend that implement ISessionBackend.

None

Exceptions:

Type Description
UnknownPredefinedBackend

The predefined backend type is unkown.

Source code in starlette_session/__init__.py
def __init__(
    self,
    app: ASGIApp,
    secret_key: str,
    cookie_name: str,
    max_age: int = 14 * 24 * 60 * 60,  # 14 days, in seconds
    same_site: str = "lax",
    https_only: bool = False,
    domain: Optional[str] = None,
    backend_type: Optional[BackendType] = None,
    backend_client: Optional[Any] = None,
    custom_session_backend: Optional[ISessionBackend] = None,
) -> None:
    """ Session Middleware

        Args:
            app: The ASGIApp
            secret_key: The secret key to use.
            cookie_name: The name of the cookie used to store the session id.
            max_age: The Max-Age of the cookie (Default to 14 days).
            same_site: The SameSite attribute of the cookie (Defaults to lax).
            https_only: Whether to make the cookie https only (Defaults to False).
            domain: The domain associated to the cookie (Default to None).
            backend_type: The type of predefined backend to use (Default to None,
                if None we'll use a regular cookie backend).
            backend_client: The client to use in the predefined backend. See examples for examples
                with predefined backends (Default to None).
            custom_session_backend: A custom backend that implement ISessionBackend.

        Raises:
            UnknownPredefinedBackend: The predefined backend type is unkown.
    """
    self.app = app

    self.backend_type = backend_type or BackendType.cookie
    self.session_backend = (
        custom_session_backend
        if custom_session_backend
        else self._get_predefined_session_backend(backend_client)
    )
    self.signer = itsdangerous.TimestampSigner(str(secret_key))
    self.cookie_name = cookie_name
    self.max_age = max_age
    self.domain = domain

    self._cookie_session_id_field = "_cssid"

    self.security_flags = f"httponly; samesite={same_site}"
    if https_only:  # Secure flag can be used with HTTPS only
        self.security_flags += "; secure"