Aiohttp Session 2 12 1

aiohttp-session 2.12.1

Overview

aiohttp-session provides server-side session support for aiohttp.web applications. It gives every HTTP request access to a dict-like Session object that persists user-specific data across requests. The library supports multiple storage backends — from simple plaintext cookies (testing only) to Fernet-encrypted cookies, NaCl-encrypted cookies, Redis, and Memcached — letting you choose the right trade-off between security, performance, and infrastructure complexity.

The session is integrated as aiohttp middleware, automatically loading on request and saving on response. Session data is stored in an HTTP cookie named AIOHTTP_SESSION by default (configurable via cookie_name).

Changelog (2.12.0 → 2.12.1)

• Minor typing fix for aiohttp 3.10+ compatibility
• Dropped support for Python 3.7; now tested on Python 3.11–3.13

When to Use

• Building aiohttp.web applications that need per-user state across requests
• Implementing session-based authentication flows
• Storing shopping cart contents, user preferences, or form draft data
• Migrating from framework-provided sessions to a lightweight asyncio-compatible alternative
• Needing encrypted cookie sessions without server-side storage
• Requiring distributed session storage via Redis or Memcached for multi-instance deployments

Core Concepts

Session: A dict-like (MutableMapping) object representing user state valid for a period of continual activity. Retrieved via await get_session(request) — never instantiated directly.

Storage: The backend responsible for persisting and loading session data. All storages derive from AbstractStorage and implement load_session() and save_session(). Every storage uses an HTTP cookie to store at least the session key; some (cookie-based) store all data in the cookie itself.

Middleware: The session system works as aiohttp middleware, registered via setup(app, storage). It attaches the storage to each request and automatically saves changed sessions on response.

Session Lifecycle: On each request, the middleware loads the session from storage. If the handler modifies it (via __setitem__, del, or explicit session.changed()), the session is serialized and saved when the response is generated.

Installation / Setup

Install with pip:

pip install aiohttp-session

Optional extras for specific backends:

• aiohttp-session[secure] — Fernet-encrypted cookies (requires cryptography)
• aiohttp-session[aioredis] — Redis storage (requires redis>=4.3 with asyncio support)
• aiohttp-session[aiomcache] — Memcached storage (requires aiomcache)

Usage Examples

Basic Setup with Encrypted Cookies

import time
from aiohttp import web
from aiohttp_session import setup, get_session
from aiohttp_session.cookie_storage import EncryptedCookieStorage


async def handler(request):
    session = await get_session(request)
    last_visit = session.get('last_visit')
    session['last_visit'] = time.time()
    return web.Response(text=f'Last visited: {last_visit}')


def make_app():
    app = web.Application()
    # Generate a 32-byte key: Fernet.generate_key() or use os.urandom(32)
    secret = b'Thirty  two  length  bytes  key.'
    setup(app, EncryptedCookieStorage(secret))
    app.router.add_get('/', handler)
    return app


web.run_app(make_app())

Using Session Properties

from aiohttp_session import get_session

async def handler(request):
    session = await get_session(request)

    # Check if this is a brand new session
    if session.new:
        session['visit_count'] = 0
    else:
        session['visit_count'] = session.get('visit_count', 0) + 1

    # Session creation timestamp (UNIX epoch)
    print(f'Session created at: {session.created}')

    # Invalidate (clear all data and set clearing cookie)
    # session.invalidate()

    return web.Response(text=f'Visit #{session["visit_count"]}')

Calling changed() for Mutable Values

async def handler(request):
    session = await get_session(request)
    if 'items' not in session:
        session['items'] = []

    # Mutating a nested list — session doesn't auto-detect this
    session['items'].append('new-item')
    session.changed()  # Required! Tell the session it was modified

    # Direct assignment auto-tracks changes:
    session['count'] = len(session['items'])  # No .changed() needed

    return web.Response(text='OK')

Preventing Session Fixation with new_session()

from aiohttp_session import new_session

async def login(request):
    # Always use new_session() in login views to prevent session fixation
    session = await new_session(request)
    assert session.new is True  # Guaranteed fresh session

    # Now safely store authenticated user data
    session['user_id'] = 'authenticated-user-123'
    return web.Response(text='Logged in')

Custom Cookie Configuration

from aiohttp_session.cookie_storage import EncryptedCookieStorage

storage = EncryptedCookieStorage(
    secret_key=b'Thirty  two  length  bytes  key.',
    cookie_name='MY_APP_SESSION',   # Custom cookie name
    max_age=3600,                    # 1 hour expiry
    path='/app/',                    # Cookie path scope
    secure=True,                     # HTTPS only
    httponly=True,                   # No JavaScript access
    samesite='Lax',                 # CSRF protection
)

Advanced Topics

Session Object API: Properties, methods, and the changed()/invalidate() lifecycle → Session Reference

Storage Backends: Detailed guide to all five storage implementations — SimpleCookie, EncryptedCookie (Fernet), NaCl, Redis, and Memcached → Storage Backends

AbstractStorage and Custom Storages: Building custom session backends by extending AbstractStorage with load_session() and save_session() → Custom Storages

Middleware Internals and Third-Party Extensions: How the middleware works, request/response flow, and community extensions for MongoDB, DynamoDB, and Firestore → Middleware and Extensions