Overview

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

Requirements

• Python ≥ 3.11

• Muffin 3

• Optional: cryptography for Fernet sessions

Installation

Install via pip:

pip install muffin-session

Install with Fernet encryption support:

pip install muffin-session[fernet]

Usage

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 {'var': ses.get('var')}

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)

@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'
SESSION_COOKIE_PARAMS = {'path': '/', 'samesite': 'lax', 'secure': True}

API

user_loader(func)

Decorator registering the function used to load a user by the ID stored in the session. It receives session["id"] and may be a coroutine. Returns the user object (or None).

load_from_request(request)

Return the session for the request, creating it from the session cookie (or empty). The result is cached in request["session"], so repeated calls return the same object.

create_from_token(token=None)

Build a session object from a raw cookie value using the configured session_type.

save_to_response(obj, response, **changes)

Store **changes into the session and write its Set-Cookie header to response. obj may be a Session or a Request (the session is loaded from it). A non-Response value is converted with asgi_tools.response.parse_response. Returns the response.

async load_user(request)

Return the user for the current session by calling the registered user loader with session["id"], or None when the session has no id. The result is cached in request["user"]; in views covered by user_pass it is available as request.user.

async check_user(request, checker=None, location=None, **response_params)

Raise a redirect (or an error) unless the loaded user passes checker. checker defaults to default_user_checker and must be a synchronous predicate returning a truthy value for allowed users. It is called with the user loaded for the session, or with None for anonymous requests, so custom checkers have to accept None: lambda user: bool(user and user.is_admin). default_user_checker is lambda x: x, i.e. “any loaded user”. location may be a URL string, a callable returning a URL (sync or async), or a ResponseError instance to raise as is. Other keyword arguments are forwarded to redirect_type. Returns the user when the check passes.

user_pass(checker=None, location=None, **rkwargs)

Route decorator wrapping check_user. Example: @session.user_pass(lambda user: user.is_admin). Without a checker it only requires a logged-in user.

login(request, ident, *, response=None)

Put ident into the session as id. The cookie is written only when response is given, in which case the response is returned.

logout(request, *, response=None)

Remove id from the session. As with login, pass response= to write the cookie.

request.session (auto_manage=True)

The session dict loaded by the middleware. Mutations are saved automatically when the view returns a Response.

ResponseHTMLRedirect

Alternative redirect_type rendering an HTML redirect (see Available Options).

Example

from muffin import Application, ResponseHTML
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: bool(user and 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