Muffin-Session

Muffin-Session — Cookie-based HTTP sessions for the Muffin framework.

Overview

Muffin-Session provides a simple and flexible way to manage secure session data via cookies. It integrates seamlessly into Muffin apps with support for JWT, Fernet, and plain base64-encoded sessions.

Features

🍪 Cookie-based session management
🔐 Supports multiple session backends: - Base64 (default) - JWT-signed sessions - Fernet-encrypted sessions
🧠 User loader & login utilities
🧩 Optional auto-managed middleware integration

Requirements

Python ≥ 3.10
Muffin ≥ 1.0
Optional: cryptography for Fernet sessions

Installation

Install via pip:

pip install muffin-session

Install with Fernet encryption support:

pip install muffin-session[fernet]

Usage

Manual integration

from muffin import Application, ResponseHTML
from muffin_session import Plugin as Session

app = Application('example')

session = Session(app, secret_key='REALLY_SECRET_KEY')

@app.route('/update')
async def update(request):
    ses = session.load_from_request(request)
    ses['var'] = 'value'
    response = ResponseHTML('Session updated.')
    session.save_to_response(ses, response)
    return response

@app.route('/load')
async def load(request):
    ses = session.load_from_request(request)
    return ses.get('var')

Auto-managed sessions

from muffin import Application
from muffin_session import Plugin as Session

app = Application('example')

session = Session()
session = Session(app, secret_key='REALLY_SECRET_KEY', auto_manage=True)

@app.route('/update')
async def update(request):
    request.session['var'] = 'value'
    return 'Session updated.'

@app.route('/load')
async def load(request):
    return request.session.get('var')

Configuration

You can pass options via session.setup(…) or set them in your application config using the SESSION_ prefix:

SESSION_SECRET_KEY = 'REALLY_SECRET_KEY'
SESSION_COOKIE_NAME = 'muffin_session'

Available Options

Option	Default	Description
session_type	"jwt"	Backend type: "base64", "jwt", or "fernet"
secret_key	"InsecureSecret"	Secret used to sign or encrypt sessions
auto_manage	False	If enabled, session is auto-loaded into request.session
cookie_name	"session"	Name of the session cookie
cookie_params	see below	Cookie options: path, max-age, samesite, secure
default_user_checker	lambda x: True	Function used to verify authenticated user
login_url	"/login"	Redirect URL or callable for unauthenticated users

Example

from muffin import Application
from muffin_session import Plugin as Session

app = Application('example')
session = Session(app, secret_key='REALLY_SECRET_KEY', auto_manage=True)

@session.user_loader
async def load_user(user_id):
    return await db.get_user_by_id(user_id)

@app.route('/session')
async def get_session(request):
    return dict(request.session)

@app.route('/admin')
@session.user_pass(lambda user: user.is_admin)
async def admin(request):
    return 'Top secret admin page.'

@app.route('/login')
async def login(request):
    user = await authenticate(request)
    session.login(request, user.id)
    return 'Logged in.'

@app.route('/logout')
async def logout(request):
    session.logout(request)
    return 'Logged out.'

@app.route('/clear')
async def clear(request):
    request.session.clear()
    return 'Session cleared.'

Bug Tracker

Found a bug or want to propose a feature? Please use the issue tracker at: https://github.com/klen/muffin-session/issues

Contributing

Want to contribute? PRs are welcome! Development happens at: https://github.com/klen/muffin-session

License

This project is licensed under the MIT license. See MIT license for details.

Author

Kirill Klenov (klen) — https://github.com/klen

Metadata

Release files for muffin-session 2.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for muffin-session 2.6.0
File	Size	Uploaded
muffin_session-2.6.0.tar.gz	5.4 kB	Jul 16, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for muffin-session 2.6.0
File	Interpreter	ABI	Platform	Reset
muffin_session-2.6.0-py3-none-any.whl 5.6 kB Jul 16, 2025	Python 3	none	any	Details

Total release size: 11.0 kB

Release files / muffin_session-2.6.0.tar.gz

Download URL	muffin_session-2.6.0.tar.gz
Size	5.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`0e615e7e779a0b5649206f1e4d46db1aa303cfa28b02dfe03eed72a4d5e48f1b`
BLAKE2b-256 checksum How to use checksums	`e2de71a615bd29e7fcbc02d4d0b5165a63080c4e4a08cc8f4cfdf3e7e9e80b2a`
Upload date	Jul 16, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.1.3 CPython/3.12.3 Linux/6.11.0-1018-azure`

Release files / muffin_session-2.6.0-py3-none-any.whl

Download URL	muffin_session-2.6.0-py3-none-any.whl
Size	5.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`558c180f0f27a6a3deaf5defba553c2856bac90f6d1d0d04ada03f12d7096935`
BLAKE2b-256 checksum How to use checksums	`9c6dc649662e8c0655d370de91e7233b8b2d7d4128512172f206f1c0970e66e5`
Upload date	Jul 16, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.1.3 CPython/3.12.3 Linux/6.11.0-1018-azure`