plain.sessions

Database-backed sessions for managing user state across requests.

Overview
Basic usage
Settings
Session expiration
Session management
Admin interface
FAQs
Installation

Overview

Sessions allow you to store and retrieve arbitrary data on a per-visitor basis, using a session key stored in a cookie. You can use sessions as a dictionary-like object that automatically handles persistence to the database.

Basic usage

In views that inherit from SessionView, you can use self.session like a standard Python dictionary:

from plain.sessions.views import SessionView


class MyView(SessionView):
    def get(self):
        # Store values in the session
        self.session["username"] = "jane"
        self.session["cart_items"] = [1, 2, 3]

        # Retrieve values from the session
        username = self.session.get("username")
        cart_items = self.session.get("cart_items", [])

        # Check if a key exists
        if "username" in self.session:
            # User has a session
            pass

        # Delete values from the session
        del self.session["cart_items"]

Outside of views, you can use get_request_session():

from plain.sessions import get_request_session

session = get_request_session(request)
session["key"] = "value"

The session data is automatically saved when you set or delete values. Sessions are stored in the database using the Session model.

Settings

Setting	Default	Env var
`SESSION_COOKIE_NAME`	`"sessionid"`	-
`SESSION_COOKIE_AGE`	`1209600` (2 weeks)	-
`SESSION_COOKIE_DOMAIN`	`None`	-
`SESSION_COOKIE_SECURE`	`True`	-
`SESSION_COOKIE_PATH`	`"/"`	-
`SESSION_COOKIE_HTTPONLY`	`True`	-
`SESSION_COOKIE_SAMESITE`	`"Lax"`	-
`SESSION_SAVE_EVERY_REQUEST`	`False`	-
`SESSION_EXPIRE_AT_BROWSER_CLOSE`	`False`	-

See default_settings.py for more details.

Session expiration

Sessions expire SESSION_COOKIE_AGE seconds after they are last saved (not last accessed).

By default (SESSION_SAVE_EVERY_REQUEST = False), sessions are only saved when modified. For authenticated users, this means the expiration timer resets on login/logout but not when just browsing pages. Users will be logged out after SESSION_COOKIE_AGE even if actively using the site.

To extend sessions on every page access, set SESSION_SAVE_EVERY_REQUEST = True. This creates a sliding window where users stay logged in as long as they visit within SESSION_COOKIE_AGE, but increases database writes.

Session management

The SessionStore class provides additional methods for managing sessions.

Flushing sessions

To completely remove the current session data and regenerate the session key:

# In a view with SessionView
self.session.flush()

# Outside a view
from plain.sessions import get_request_session

session = get_request_session(request)
session.flush()

Cycling session keys

To create a new session key while retaining the current session data (useful for security purposes):

# In a view with SessionView
self.session.cycle_key()

# Outside a view
from plain.sessions import get_request_session

session = get_request_session(request)
session.cycle_key()

Checking if session is empty

# In a view with SessionView
if self.session.is_empty():
    # No session data exists
    pass

# Outside a view
from plain.sessions import get_request_session

session = get_request_session(request)
if session.is_empty():
    # No session data exists
    pass

Admin interface

You can view and manage sessions in the admin panel under the "Sessions" section. The admin interface allows you to:

Search sessions by session key
View session creation and expiration times
Delete expired or unwanted sessions

The SessionAdmin viewset provides the interface for managing sessions in the admin panel.

FAQs

How do I clear expired sessions?

You can use the built-in ClearExpired chore to delete expired sessions from the database:

plain chores run plain.sessions.chores.ClearExpired

You can schedule this chore to run periodically using plain.worker or your preferred task scheduler.

How do I access the underlying Session model instance?

You can access the database model instance through the model_instance property:

from plain.sessions import get_request_session

session = get_request_session(request)
session_instance = session.model_instance  # Returns the Session model or None

Why is my session not being saved?

Sessions are only saved when modified (when you set or delete a value). If you need the session to be saved on every request, set SESSION_SAVE_EVERY_REQUEST = True in your settings.

Installation

Install the plain.sessions package from PyPI:

uv add plain.sessions

Add plain.sessions to your INSTALLED_PACKAGES and include the SessionMiddleware in your middleware:

INSTALLED_PACKAGES = [
    # ...
    "plain.sessions",
]

MIDDLEWARE = [
    # ...
    "plain.sessions.middleware.SessionMiddleware",
    # ...
]

Sync the database to create the session table:

plain postgres sync

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

plain_sessions-0.46.1.tar.gz (18.5 kB view details)

Uploaded Aug 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

plain_sessions-0.46.1-py3-none-any.whl (23.4 kB view details)

Uploaded Aug 12, 2026 Python 3

File details

Details for the file plain_sessions-0.46.1.tar.gz.

File metadata

Download URL: plain_sessions-0.46.1.tar.gz
Upload date: Aug 12, 2026
Size: 18.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for plain_sessions-0.46.1.tar.gz
Algorithm	Hash digest
SHA256	`d0b5fe46f62aea9b15b08e786e87cce43126367001ad55cd3dcfbb485e4d0917`
MD5	`73ca397c3f0cd5bf517872bf150c48d3`
BLAKE2b-256	`e4fa5e92055ed87ba03a93f976dfcb2337e908428efcd868105281a0a67213d5`

See more details on using hashes here.

File details

Details for the file plain_sessions-0.46.1-py3-none-any.whl.

File metadata

Download URL: plain_sessions-0.46.1-py3-none-any.whl
Upload date: Aug 12, 2026
Size: 23.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for plain_sessions-0.46.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`8acc9eea693491eaebecb31fb08da69707d71e3af427542cca71fd3f54f167ac`
MD5	`56c97278efa9cbfca267de0be9029866`
BLAKE2b-256	`44c2427e50e7c8cb62ad01f37ce7fa8104ea1ecdeaa757a56abc30f6bde63649`