from sqlite3 import connect
## Starsessions
Advanced sessions for Starlette and FastAPI frameworks
## Installation
Install `starsessions` package:
```bash
pip install starsessions
```
Use `redis` extra for [Redis support](#redis).
## Quick start
See the example application in [`examples/`](examples) directory of this repository.
## Usage
1. Add `starsessions.SessionMiddleware` to your application to enable session support,
2. Configure the session store and pass it to the middleware,
3. Load the session in your view/middleware by calling `load_session(connection)` utility.
```python
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.responses import JSONResponse
from starlette.routing import Route
from starsessions import CookieStore, load_session, SessionMiddleware
async def index_view(request):
await load_session(request)
session_data = request.session
return JSONResponse(session_data)
session_store = CookieStore(secret_key='TOP SECRET')
app = Starlette(
middleware=[
Middleware(SessionMiddleware, store=session_store, lifetime=3600 * 24 * 14),
],
routes=[
Route('/', index_view),
]
)
```
### Cookie security
By default, the middleware uses strict defaults.
The cookie lifetime is limited to the browser session and sent via HTTPS protocol only.
You can change these defaults by changing `cookie_https_only` and `lifetime` arguments:
```python
from starlette.middleware import Middleware
from starsessions import CookieStore, SessionMiddleware
session_store = CookieStore(secret_key='TOP SECRET')
middleware = [
Middleware(SessionMiddleware, store=session_store, cookie_https_only=False, lifetime=3600 * 24 * 14),
]
```
The example above will let session usage over insecure HTTP transport and the session lifetime will be set to 14 days.
### Loading session
The session data is not loaded by default. Call `load_session` to load data from the store.
```python
async def index_view(request):
await load_session(request)
request.session['key'] = 'value'
```
However, if you try to access an uninitialized session, `SessionNotLoaded` exception will be raised.
```python
async def index_view(request):
request.session['key'] = 'value' # raises SessionNotLoaded
```
You can automatically load a session by using `SessionAutoloadMiddleware` middleware.
### Session autoload
For performance reasons, the session is not autoloaded by default. Sometimes it is annoying to call `load_session` too
often.
We provide `SessionAutoloadMiddleware` class to reduce the boilerplate code by autoloading the session for you.
There are two options: always autoload or autoload for specific paths only.
Here are examples:
```python
from starlette.middleware import Middleware
from starsessions import CookieStore, SessionAutoloadMiddleware, SessionMiddleware
session_store = CookieStore(secret_key='TOP SECRET')
# Always autoload
middleware = [
Middleware(SessionMiddleware, store=session_store),
Middleware(SessionAutoloadMiddleware),
]
# Autoload session for selected paths
middleware = [
Middleware(SessionMiddleware, store=session_store),
Middleware(SessionAutoloadMiddleware, paths=['/admin', '/app']),
]
# regex patterns also supported
import re
admin_rx = re.compile('/admin*')
middleware = [
Middleware(SessionMiddleware, store=session_store),
Middleware(SessionAutoloadMiddleware, paths=[admin_rx]),
]
```
### Rolling sessions
The default behavior of `SessionMiddleware` is to expire the cookie after `lifetime` seconds after it was set.
For example, if you create a session with `lifetime=3600`, the session will be terminated exactly in 3600 seconds.
Sometimes this may not be what you need, so we provide an alternate expiration strategy - rolling sessions.
When rolling sessions are activated, the cookie expiration time will be extended by `lifetime` value on every response.
Let's see how it works for example. First, on the first response you create a new session with `lifetime=3600`,
then the user does another request, and the session gets extended by another 3600 seconds, and so on.
This approach is useful when you want to use short-timed sessions but don't want them to interrupt in the middle of
the user's operation. With the rolling strategy, a session cookie will expire only after some period of the user's
inactivity.
To enable the rolling strategy set `rolling=True`.
```python
from starlette.middleware import Middleware
from starsessions import SessionMiddleware
middleware = [
Middleware(SessionMiddleware, lifetime=300, rolling=True),
]
```
The snippet above demonstrates an example setup where the session will be dropped after 300 seconds (5 minutes) of
inactivity, but will be automatically extended by another 5 minutes while the user is online.
### Cookie path
You can pass `cookie_path` argument to bind the session cookies to specific URLs. For example, to activate a session
cookie
only for the admin area, use `cookie_path="/admin"` middleware argument.
```python
from starlette.middleware import Middleware
from starsessions import SessionMiddleware
middleware = [
Middleware(SessionMiddleware, cookie_path='/admin'),
]
```
All other URLs not matching the value of `cookie_path` will not receive cookies thus session will be unavailable.
### Cookie domain
You can also specify which hosts can receive a cookie by passing `cookie_domain` argument to the middleware.
```python
from starlette.middleware import Middleware
from starsessions import SessionMiddleware
middleware = [
Middleware(SessionMiddleware, cookie_domain='example.com'),
]
```
> Note, this makes session cookies available for subdomains too.
> For example, when you set `cookie_domain=example.com` then session cookie will be available on subdomains
> like `app.example.com`.
### Session-only cookies
If you want the session cookie to be automatically removed from the browser when the tab closes set `lifetime` to `0`.
> Note, this depends on browser implementation!
```python
from starlette.middleware import Middleware
from starsessions import SessionMiddleware
middleware = [
Middleware(SessionMiddleware, lifetime=0),
]
```
## Built-in stores
### Memory
Class: `starsessions.InMemoryStore`
Simply stores data in memory. The data is cleared after the server restart. Mostly for use with unit tests.
### CookieStore
Class: `starsessions.CookieStore`
Stores session data in a signed cookie on the client.
### Redis
Class: `starsessions.stores.redis.RedisStore`
Stores session data in a Redis server. The store accepts either a connection URL or an instance of `Redis`.
> Requires [redis-py](https://github.com/redis/redis-py),
> use `pip install starsessions[redis]`
> Note, redis-py requires explicit disconnect of connection. The library does not handle it for you at the moment.
> The recommended solution is to pass a Redis instance to the store and call `.close()` on application shutdown.
> For example, you can close the connection using lifespan handler.
> See more https://redis-py.readthedocs.io/en/latest/examples/asyncio_examples.html
```python
from redis.asyncio import Redis
from starsessions.stores.redis import RedisStore
client = Redis.from_url('redis://localhost')
store = RedisStore(connection=client)
store = RedisStore(connection=client)
# close connection on shutdown
await client.close()
```
#### Redis key prefix
By default, all keys in Redis prefixed with `starsessions.`. If you want to change this use `prefix` argument.
```python
from starsessions.stores.redis import RedisStore
store = RedisStore(url='redis://localhost', prefix='my_sessions')
```
Prefix can be a callable:
```python
from starsessions.stores.redis import RedisStore
def make_prefix(key: str) -> str:
return 'my_sessions_' + key
store = RedisStore(url='redis://localhost', prefix=make_prefix)
```
#### Key expiration
The library automatically manages key expiration, usually you have nothing to do with it.
But for cases when `lifetime=0` we don't know when the session will be over, and we have to heuristically calculate TTL,
otherwise the data will remain in Redis forever. At this moment, we just set 30 days TTL. You can change it by
setting `gc_ttl` value on the store.
```python
from starsessions.stores.redis import RedisStore
store = RedisStore(url='redis://localhost', gc_ttl=3600) # max 1 hour
```
## Custom store
Creating new stores is quite simple. All you need is to extend `starsessions.SessionStore`
class and implement abstract methods.
Here is an example of how we can create a memory-based session store. Note, that it is important that `write` method
returns session ID as a string value.
```python
from typing import Dict
from starsessions import SessionStore
# instance of class that manages session persistence
class InMemoryStore(SessionStore):
def __init__(self):
self._storage = {}
async def read(self, session_id: str, lifetime: int) -> bytes:
""" Read session data from a data source using session_id. """
return self._storage.get(session_id, {})
async def write(self, session_id: str, data: bytes, lifetime: int, ttl: int) -> str:
""" Write session data into the data source and return session ID. """
self._storage[session_id] = data
return session_id
async def remove(self, session_id: str):
""" Remove session data. """
del self._storage[session_id]
async def exists(self, session_id: str) -> bool:
return session_id in self._storage
```
### lifetime and ttl
The `write` accepts two special arguments: `lifetime` and `ttl`.
The difference is that `lifetime` is the total session duration (set by the middleware)
and `ttl` is the remaining session time. After `ttl` seconds the data can be safely deleted from the storage.
> Your custom backend has to correctly handle cases when `lifetime = 0`.
> In such cases, you don't have an exact expiration value, and you would have to find a way to extend session TTL on the
> storage
> side, if any.
## Serializers
The library automatically serializes session data to string using JSON.
By default, we use `starsessions.JsonSerializer` but you can implement your own by extending `starsessions.Serializer`
class.
```python
import json
import typing
from starlette.middleware import Middleware
from starsessions import Serializer, SessionMiddleware
class MySerializer(Serializer):
def serialize(self, data: typing.Any) -> bytes:
return json.dumps(data).encode('utf-8')
def deserialize(self, data: bytes) -> typing.Dict[str, typing.Any]:
return json.loads(data)
middleware = [
Middleware(SessionMiddleware, serializer=MySerializer()),
]
```
## Session termination
The middleware will remove session data and cookies if the session has no data. Use `request.session.clear` to empty
data.
## Regenerating session ID
Sometimes you need a new session ID to avoid session fixation attacks (for example, after successful signs-in).
For that, use `starsessions.session.regenerate_session_id(connection)` utility.
```python
from starsessions.session import regenerate_session_id
from starlette.responses import Response
def login(request):
regenerate_session_id(request)
return Response('successfully signed in')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/alex-oleshkevich/starsessions",
"name": "starsessions",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.0",
"maintainer_email": null,
"keywords": "starlette, fastapi, asgi, session",
"author": "alex.oleshkevich",
"author_email": "alex.oleshkevich@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/86/a1/dd738cd47b7a1c681cae49c4f7c88cc953b2aca4de455c2aacda6652e7ce/starsessions-2.2.1.tar.gz",
"platform": null,
"description": "from sqlite3 import connect\n\n## Starsessions\n\nAdvanced sessions for Starlette and FastAPI frameworks\n\n\n\n\n\n\n\n\n## Installation\n\nInstall `starsessions` package:\n\n```bash\npip install starsessions\n```\n\nUse `redis` extra for [Redis support](#redis).\n\n## Quick start\n\nSee the example application in [`examples/`](examples) directory of this repository.\n\n## Usage\n\n1. Add `starsessions.SessionMiddleware` to your application to enable session support,\n2. Configure the session store and pass it to the middleware,\n3. Load the session in your view/middleware by calling `load_session(connection)` utility.\n\n```python\nfrom starlette.applications import Starlette\nfrom starlette.middleware import Middleware\nfrom starlette.responses import JSONResponse\nfrom starlette.routing import Route\n\nfrom starsessions import CookieStore, load_session, SessionMiddleware\n\n\nasync def index_view(request):\n await load_session(request)\n\n session_data = request.session\n return JSONResponse(session_data)\n\n\nsession_store = CookieStore(secret_key='TOP SECRET')\n\napp = Starlette(\n middleware=[\n Middleware(SessionMiddleware, store=session_store, lifetime=3600 * 24 * 14),\n ],\n routes=[\n Route('/', index_view),\n ]\n)\n```\n\n### Cookie security\n\nBy default, the middleware uses strict defaults.\nThe cookie lifetime is limited to the browser session and sent via HTTPS protocol only.\nYou can change these defaults by changing `cookie_https_only` and `lifetime` arguments:\n\n```python\nfrom starlette.middleware import Middleware\n\nfrom starsessions import CookieStore, SessionMiddleware\n\nsession_store = CookieStore(secret_key='TOP SECRET')\n\nmiddleware = [\n Middleware(SessionMiddleware, store=session_store, cookie_https_only=False, lifetime=3600 * 24 * 14),\n]\n```\n\nThe example above will let session usage over insecure HTTP transport and the session lifetime will be set to 14 days.\n\n### Loading session\n\nThe session data is not loaded by default. Call `load_session` to load data from the store.\n\n```python\nasync def index_view(request):\n await load_session(request)\n request.session['key'] = 'value'\n```\n\nHowever, if you try to access an uninitialized session, `SessionNotLoaded` exception will be raised.\n\n```python\nasync def index_view(request):\n request.session['key'] = 'value' # raises SessionNotLoaded\n```\n\nYou can automatically load a session by using `SessionAutoloadMiddleware` middleware.\n\n### Session autoload\n\nFor performance reasons, the session is not autoloaded by default. Sometimes it is annoying to call `load_session` too\noften.\nWe provide `SessionAutoloadMiddleware` class to reduce the boilerplate code by autoloading the session for you.\n\nThere are two options: always autoload or autoload for specific paths only.\nHere are examples:\n\n```python\nfrom starlette.middleware import Middleware\n\nfrom starsessions import CookieStore, SessionAutoloadMiddleware, SessionMiddleware\n\nsession_store = CookieStore(secret_key='TOP SECRET')\n\n# Always autoload\n\nmiddleware = [\n Middleware(SessionMiddleware, store=session_store),\n Middleware(SessionAutoloadMiddleware),\n]\n\n# Autoload session for selected paths\n\nmiddleware = [\n Middleware(SessionMiddleware, store=session_store),\n Middleware(SessionAutoloadMiddleware, paths=['/admin', '/app']),\n]\n\n# regex patterns also supported\nimport re\n\nadmin_rx = re.compile('/admin*')\n\nmiddleware = [\n Middleware(SessionMiddleware, store=session_store),\n Middleware(SessionAutoloadMiddleware, paths=[admin_rx]),\n]\n```\n\n### Rolling sessions\n\nThe default behavior of `SessionMiddleware` is to expire the cookie after `lifetime` seconds after it was set.\nFor example, if you create a session with `lifetime=3600`, the session will be terminated exactly in 3600 seconds.\nSometimes this may not be what you need, so we provide an alternate expiration strategy - rolling sessions.\n\nWhen rolling sessions are activated, the cookie expiration time will be extended by `lifetime` value on every response.\nLet's see how it works for example. First, on the first response you create a new session with `lifetime=3600`,\nthen the user does another request, and the session gets extended by another 3600 seconds, and so on.\nThis approach is useful when you want to use short-timed sessions but don't want them to interrupt in the middle of\nthe user's operation. With the rolling strategy, a session cookie will expire only after some period of the user's\ninactivity.\n\nTo enable the rolling strategy set `rolling=True`.\n\n```python\nfrom starlette.middleware import Middleware\nfrom starsessions import SessionMiddleware\n\nmiddleware = [\n Middleware(SessionMiddleware, lifetime=300, rolling=True),\n]\n```\n\nThe snippet above demonstrates an example setup where the session will be dropped after 300 seconds (5 minutes) of\ninactivity, but will be automatically extended by another 5 minutes while the user is online.\n\n### Cookie path\n\nYou can pass `cookie_path` argument to bind the session cookies to specific URLs. For example, to activate a session\ncookie\nonly for the admin area, use `cookie_path=\"/admin\"` middleware argument.\n\n```python\nfrom starlette.middleware import Middleware\nfrom starsessions import SessionMiddleware\n\nmiddleware = [\n Middleware(SessionMiddleware, cookie_path='/admin'),\n]\n```\n\nAll other URLs not matching the value of `cookie_path` will not receive cookies thus session will be unavailable.\n\n### Cookie domain\n\nYou can also specify which hosts can receive a cookie by passing `cookie_domain` argument to the middleware.\n\n```python\nfrom starlette.middleware import Middleware\nfrom starsessions import SessionMiddleware\n\nmiddleware = [\n Middleware(SessionMiddleware, cookie_domain='example.com'),\n]\n```\n\n> Note, this makes session cookies available for subdomains too.\n> For example, when you set `cookie_domain=example.com` then session cookie will be available on subdomains\n> like `app.example.com`.\n\n### Session-only cookies\n\nIf you want the session cookie to be automatically removed from the browser when the tab closes set `lifetime` to `0`.\n> Note, this depends on browser implementation!\n\n```python\nfrom starlette.middleware import Middleware\nfrom starsessions import SessionMiddleware\n\nmiddleware = [\n Middleware(SessionMiddleware, lifetime=0),\n]\n```\n\n## Built-in stores\n\n### Memory\n\nClass: `starsessions.InMemoryStore`\n\nSimply stores data in memory. The data is cleared after the server restart. Mostly for use with unit tests.\n\n### CookieStore\n\nClass: `starsessions.CookieStore`\n\nStores session data in a signed cookie on the client.\n\n### Redis\n\nClass: `starsessions.stores.redis.RedisStore`\n\nStores session data in a Redis server. The store accepts either a connection URL or an instance of `Redis`.\n\n> Requires [redis-py](https://github.com/redis/redis-py),\n> use `pip install starsessions[redis]`\n\n> Note, redis-py requires explicit disconnect of connection. The library does not handle it for you at the moment.\n> The recommended solution is to pass a Redis instance to the store and call `.close()` on application shutdown.\n> For example, you can close the connection using lifespan handler.\n> See more https://redis-py.readthedocs.io/en/latest/examples/asyncio_examples.html\n\n```python\nfrom redis.asyncio import Redis\n\nfrom starsessions.stores.redis import RedisStore\n\nclient = Redis.from_url('redis://localhost')\nstore = RedisStore(connection=client)\n\nstore = RedisStore(connection=client)\n\n# close connection on shutdown\nawait client.close()\n```\n\n#### Redis key prefix\n\nBy default, all keys in Redis prefixed with `starsessions.`. If you want to change this use `prefix` argument.\n\n```python\nfrom starsessions.stores.redis import RedisStore\n\nstore = RedisStore(url='redis://localhost', prefix='my_sessions')\n```\n\nPrefix can be a callable:\n\n```python\nfrom starsessions.stores.redis import RedisStore\n\n\ndef make_prefix(key: str) -> str:\n return 'my_sessions_' + key\n\n\nstore = RedisStore(url='redis://localhost', prefix=make_prefix)\n```\n\n#### Key expiration\n\nThe library automatically manages key expiration, usually you have nothing to do with it.\nBut for cases when `lifetime=0` we don't know when the session will be over, and we have to heuristically calculate TTL,\notherwise the data will remain in Redis forever. At this moment, we just set 30 days TTL. You can change it by\nsetting `gc_ttl` value on the store.\n\n```python\nfrom starsessions.stores.redis import RedisStore\n\nstore = RedisStore(url='redis://localhost', gc_ttl=3600) # max 1 hour\n```\n\n## Custom store\n\nCreating new stores is quite simple. All you need is to extend `starsessions.SessionStore`\nclass and implement abstract methods.\n\nHere is an example of how we can create a memory-based session store. Note, that it is important that `write` method\nreturns session ID as a string value.\n\n```python\nfrom typing import Dict\n\nfrom starsessions import SessionStore\n\n\n# instance of class that manages session persistence\n\nclass InMemoryStore(SessionStore):\n def __init__(self):\n self._storage = {}\n\n async def read(self, session_id: str, lifetime: int) -> bytes:\n \"\"\" Read session data from a data source using session_id. \"\"\"\n return self._storage.get(session_id, {})\n\n async def write(self, session_id: str, data: bytes, lifetime: int, ttl: int) -> str:\n \"\"\" Write session data into the data source and return session ID. \"\"\"\n self._storage[session_id] = data\n return session_id\n\n async def remove(self, session_id: str):\n \"\"\" Remove session data. \"\"\"\n del self._storage[session_id]\n\n async def exists(self, session_id: str) -> bool:\n return session_id in self._storage\n```\n\n### lifetime and ttl\n\nThe `write` accepts two special arguments: `lifetime` and `ttl`.\nThe difference is that `lifetime` is the total session duration (set by the middleware)\nand `ttl` is the remaining session time. After `ttl` seconds the data can be safely deleted from the storage.\n\n> Your custom backend has to correctly handle cases when `lifetime = 0`.\n> In such cases, you don't have an exact expiration value, and you would have to find a way to extend session TTL on the\n> storage\n> side, if any.\n\n## Serializers\n\nThe library automatically serializes session data to string using JSON.\nBy default, we use `starsessions.JsonSerializer` but you can implement your own by extending `starsessions.Serializer`\nclass.\n\n```python\nimport json\nimport typing\n\nfrom starlette.middleware import Middleware\n\nfrom starsessions import Serializer, SessionMiddleware\n\n\nclass MySerializer(Serializer):\n def serialize(self, data: typing.Any) -> bytes:\n return json.dumps(data).encode('utf-8')\n\n def deserialize(self, data: bytes) -> typing.Dict[str, typing.Any]:\n return json.loads(data)\n\n\nmiddleware = [\n Middleware(SessionMiddleware, serializer=MySerializer()),\n]\n```\n\n## Session termination\n\nThe middleware will remove session data and cookies if the session has no data. Use `request.session.clear` to empty\ndata.\n\n## Regenerating session ID\n\nSometimes you need a new session ID to avoid session fixation attacks (for example, after successful signs-in).\nFor that, use `starsessions.session.regenerate_session_id(connection)` utility.\n\n```python\nfrom starsessions.session import regenerate_session_id\nfrom starlette.responses import Response\n\n\ndef login(request):\n regenerate_session_id(request)\n return Response('successfully signed in')\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Advanced sessions for Starlette and FastAPI frameworks",
"version": "2.2.1",
"project_urls": {
"Documentation": "https://github.com/alex-oleshkevich/starsessions",
"Homepage": "https://github.com/alex-oleshkevich/starsessions",
"Repository": "https://github.com/alex-oleshkevich/starsessions"
},
"split_keywords": [
"starlette",
" fastapi",
" asgi",
" session"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d2cefc699345a3cdfb4425b5dc1e446f1b49702ac55907a6a4d5d806f2512dae",
"md5": "05ee090552fedca2296abc95a0fff5e9",
"sha256": "8097b33d70017b2d2331307f0ea923620b5bfb847118d2e5872805d0c1c16f83"
},
"downloads": -1,
"filename": "starsessions-2.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "05ee090552fedca2296abc95a0fff5e9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.0",
"size": 14621,
"upload_time": "2024-10-23T09:01:10",
"upload_time_iso_8601": "2024-10-23T09:01:10.880283Z",
"url": "https://files.pythonhosted.org/packages/d2/ce/fc699345a3cdfb4425b5dc1e446f1b49702ac55907a6a4d5d806f2512dae/starsessions-2.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "86a1dd738cd47b7a1c681cae49c4f7c88cc953b2aca4de455c2aacda6652e7ce",
"md5": "7677596e609decff6132825ec57b1ad3",
"sha256": "ce5e4448d9bf2c76222e56cd099ad92d22313e8a4def612e22b71a122cc11da0"
},
"downloads": -1,
"filename": "starsessions-2.2.1.tar.gz",
"has_sig": false,
"md5_digest": "7677596e609decff6132825ec57b1ad3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.0",
"size": 15048,
"upload_time": "2024-10-23T09:01:12",
"upload_time_iso_8601": "2024-10-23T09:01:12.343793Z",
"url": "https://files.pythonhosted.org/packages/86/a1/dd738cd47b7a1c681cae49c4f7c88cc953b2aca4de455c2aacda6652e7ce/starsessions-2.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-23 09:01:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alex-oleshkevich",
"github_project": "starsessions",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "starsessions"
}
JSON
