Muffin-Session
##############
**Muffin-Session** — Cookie-based HTTP sessions for the Muffin_ framework.
.. image:: https://github.com/klen/muffin-session/workflows/tests/badge.svg
:target: https://github.com/klen/muffin-session/actions
:alt: Test Status
.. image:: https://img.shields.io/pypi/v/muffin-session
:target: https://pypi.org/project/muffin-session/
:alt: PyPI Version
.. image:: https://img.shields.io/pypi/pyversions/muffin-session
:target: https://pypi.org/project/muffin-session/
:alt: Supported Python Versions
.. contents::
:local:
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:
.. code-block:: bash
pip install muffin-session
Install with Fernet encryption support:
.. code-block:: bash
pip install muffin-session[fernet]
Usage
=====
Manual integration
------------------
.. code-block:: python
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
---------------------
.. code-block:: python
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:
.. code-block:: python
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
=======
.. code-block:: python
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
.. _klen: https://github.com/klen
.. _Muffin: https://github.com/klen/muffin
.. _MIT license: http://opensource.org/licenses/MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/klen/muffin-session",
"name": "muffin-session",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "asyncio, trio, asgi, muffin, web, cookie, sessions, session",
"author": "Kirill Klenov",
"author_email": "horneds@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e2/de/71a615bd29e7fcbc02d4d0b5165a63080c4e4a08cc8f4cfdf3e7e9e80b2a/muffin_session-2.6.0.tar.gz",
"platform": null,
"description": "Muffin-Session\n##############\n\n**Muffin-Session** \u2014 Cookie-based HTTP sessions for the Muffin_ framework.\n\n.. image:: https://github.com/klen/muffin-session/workflows/tests/badge.svg\n :target: https://github.com/klen/muffin-session/actions\n :alt: Test Status\n\n.. image:: https://img.shields.io/pypi/v/muffin-session\n :target: https://pypi.org/project/muffin-session/\n :alt: PyPI Version\n\n.. image:: https://img.shields.io/pypi/pyversions/muffin-session\n :target: https://pypi.org/project/muffin-session/\n :alt: Supported Python Versions\n\n.. contents::\n :local:\n\nOverview\n========\n\n**Muffin-Session** provides a simple and flexible way to manage secure session data via cookies.\nIt integrates seamlessly into Muffin apps with support for JWT, Fernet, and plain base64-encoded sessions.\n\nFeatures\n--------\n\n- \ud83c\udf6a Cookie-based session management\n- \ud83d\udd10 Supports multiple session backends:\n - Base64 (default)\n - **JWT**-signed sessions\n - **Fernet**-encrypted sessions\n- \ud83e\udde0 User loader & login utilities\n- \ud83e\udde9 Optional auto-managed middleware integration\n\nRequirements\n============\n\n- Python \u2265 3.10\n- Muffin \u2265 1.0\n- Optional: `cryptography` for Fernet sessions\n\nInstallation\n============\n\nInstall via pip:\n\n.. code-block:: bash\n\n pip install muffin-session\n\nInstall with Fernet encryption support:\n\n.. code-block:: bash\n\n pip install muffin-session[fernet]\n\nUsage\n=====\n\nManual integration\n------------------\n\n.. code-block:: python\n\n from muffin import Application, ResponseHTML\n from muffin_session import Plugin as Session\n\n app = Application('example')\n\n session = Session(app, secret_key='REALLY_SECRET_KEY')\n\n @app.route('/update')\n async def update(request):\n ses = session.load_from_request(request)\n ses['var'] = 'value'\n response = ResponseHTML('Session updated.')\n session.save_to_response(ses, response)\n return response\n\n @app.route('/load')\n async def load(request):\n ses = session.load_from_request(request)\n return ses.get('var')\n\n\nAuto-managed sessions\n---------------------\n\n.. code-block:: python\n\n from muffin import Application\n from muffin_session import Plugin as Session\n\n app = Application('example')\n\n session = Session()\n session = Session(app, secret_key='REALLY_SECRET_KEY', auto_manage=True)\n\n @app.route('/update')\n async def update(request):\n request.session['var'] = 'value'\n return 'Session updated.'\n\n @app.route('/load')\n async def load(request):\n return request.session.get('var')\n\nConfiguration\n=============\n\nYou can pass options via `session.setup(...)` or set them in your application config using the `SESSION_` prefix:\n\n.. code-block:: python\n\n SESSION_SECRET_KEY = 'REALLY_SECRET_KEY'\n SESSION_COOKIE_NAME = 'muffin_session'\n\nAvailable Options\n-----------------\n\n=========================== =========================== ========================================================\nOption Default Description\n--------------------------- --------------------------- --------------------------------------------------------\n**session_type** ``\"jwt\"`` Backend type: ``\"base64\"``, ``\"jwt\"``, or ``\"fernet\"``\n**secret_key** ``\"InsecureSecret\"`` Secret used to sign or encrypt sessions\n**auto_manage** ``False`` If enabled, session is auto-loaded into ``request.session``\n**cookie_name** ``\"session\"`` Name of the session cookie\n**cookie_params** see below Cookie options: path, max-age, samesite, secure\n**default_user_checker** ``lambda x: True`` Function used to verify authenticated user\n**login_url** ``\"/login\"`` Redirect URL or callable for unauthenticated users\n=========================== =========================== ========================================================\n\nExample\n=======\n\n.. code-block:: python\n\n from muffin import Application\n from muffin_session import Plugin as Session\n\n app = Application('example')\n session = Session(app, secret_key='REALLY_SECRET_KEY', auto_manage=True)\n\n @session.user_loader\n async def load_user(user_id):\n return await db.get_user_by_id(user_id)\n\n @app.route('/session')\n async def get_session(request):\n return dict(request.session)\n\n @app.route('/admin')\n @session.user_pass(lambda user: user.is_admin)\n async def admin(request):\n return 'Top secret admin page.'\n\n @app.route('/login')\n async def login(request):\n user = await authenticate(request)\n session.login(request, user.id)\n return 'Logged in.'\n\n @app.route('/logout')\n async def logout(request):\n session.logout(request)\n return 'Logged out.'\n\n @app.route('/clear')\n async def clear(request):\n request.session.clear()\n return 'Session cleared.'\n\nBug Tracker\n===========\n\nFound a bug or want to propose a feature?\nPlease use the issue tracker at: https://github.com/klen/muffin-session/issues\n\nContributing\n============\n\nWant to contribute? PRs are welcome!\nDevelopment happens at: https://github.com/klen/muffin-session\n\nLicense\n=======\n\nThis project is licensed under the MIT license. See `MIT license`_ for details.\n\nAuthor\n======\n\n- Kirill Klenov (`klen`_) \u2014 https://github.com/klen\n\n.. _klen: https://github.com/klen\n.. _Muffin: https://github.com/klen/muffin\n.. _MIT license: http://opensource.org/licenses/MIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Signed Cookie-Based HTTP sessions for the Muffin framework",
"version": "2.6.0",
"project_urls": {
"Homepage": "https://github.com/klen/muffin-session",
"Repository": "https://github.com/klen/muffin-session"
},
"split_keywords": [
"asyncio",
" trio",
" asgi",
" muffin",
" web",
" cookie",
" sessions",
" session"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9c6dc649662e8c0655d370de91e7233b8b2d7d4128512172f206f1c0970e66e5",
"md5": "ba8290c7f1f18eeced901b8143edfcc7",
"sha256": "558c180f0f27a6a3deaf5defba553c2856bac90f6d1d0d04ada03f12d7096935"
},
"downloads": -1,
"filename": "muffin_session-2.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba8290c7f1f18eeced901b8143edfcc7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 5582,
"upload_time": "2025-07-16T11:50:20",
"upload_time_iso_8601": "2025-07-16T11:50:20.617033Z",
"url": "https://files.pythonhosted.org/packages/9c/6d/c649662e8c0655d370de91e7233b8b2d7d4128512172f206f1c0970e66e5/muffin_session-2.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e2de71a615bd29e7fcbc02d4d0b5165a63080c4e4a08cc8f4cfdf3e7e9e80b2a",
"md5": "a5442624f995470e697678ac8c5121ef",
"sha256": "0e615e7e779a0b5649206f1e4d46db1aa303cfa28b02dfe03eed72a4d5e48f1b"
},
"downloads": -1,
"filename": "muffin_session-2.6.0.tar.gz",
"has_sig": false,
"md5_digest": "a5442624f995470e697678ac8c5121ef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 5384,
"upload_time": "2025-07-16T11:50:21",
"upload_time_iso_8601": "2025-07-16T11:50:21.486190Z",
"url": "https://files.pythonhosted.org/packages/e2/de/71a615bd29e7fcbc02d4d0b5165a63080c4e4a08cc8f4cfdf3e7e9e80b2a/muffin_session-2.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 11:50:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "klen",
"github_project": "muffin-session",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "muffin-session"
}
JSON
