Reference¶
Public functions¶
-
aiohttp_session.
get_session
(request)¶ A coroutine for getting session instance from request object.
See example below in Session section for
get_session()
usage.
-
aiohttp_session.
new_session
(request)¶ A coroutine for getting a new session regardless of whether a cookie exists.
Warning
Always use
new_session()
instead ofget_session()
in your login views to guard against Session Fixation attacks!Example usage:
from aiohttp_session import new_session async def handler(request): session = await new_session(request) session.new == True # This will always be True
-
aiohttp_session.
session_middleware
(storage)¶ Session middleware factory.
Create session middleware to pass into
aiohttp.web.Application
constructor.storage is a session storage instance (object used to store session data into cookies, Redis, database etc., class is derived from
AbstractStorage
).See also
Note
setup()
is new-fashion way for library setup.
-
aiohttp_session.
setup
(app, storage)¶ Setup session support for given app.
The function is shortcut for:
app.middlewares.append(session_middleware(storage))
app is
aiohttp.web.Application
instance.storage is a session storage instance (object used to store session data into cookies, Redis, database etc., class is derived from
AbstractStorage
).See also
Session¶
-
class
aiohttp_session.
Session
¶ Client’s session, a namespace that is valid for some period of continual activity that can be used to represent a user’s interaction with a web application.
Warning
Never create
Session
instances by hands, retieve those byget_session()
call.The
Session
is aMutableMapping
, thus it supports all dictionary methods, along with some extra attributes and methods:from aiohttp_session import get_session async def handler(request): session = await get_session(request) session['key1'] = 'value 1' assert 'key2' in session assert session['key2'] == 'value 2' # ...
-
created
¶ Creation UNIX TIMESTAMP, the value returned by
time.time()
for very first access to the session object.
-
identity
¶ Client’s identity. It may be cookie name or database key. Read-only property. For change use
Session.set_new_identity()
.
-
new
¶ A boolean. If new is
True
, this session is new. Otherwise, it has been constituted from data that was already serialized.
-
changed
()¶ Call this when you mutate a mutable value in the session namespace. See the note below for details on when, and why you should call this.
Note
Keys and values of session data must be JSON serializable when using one of the included storage backends. This means, typically, that they are instances of basic types of objects, such as strings, lists, dictionaries, tuples, integers, etc. If you place an object in a session data key or value that is not JSON serializable, an error will be raised when the session is serialized.
If you place a mutable value (for example, a list or a dictionary) in a session object, and you subsequently mutate that value, you must call the changed() method of the session object. In this case, the session has no way to know that is was modified. However, when you modify a session object directly, such as setting a value (i.e.,
__setitem__
), or removing a key (e.g.,del
orpop
), the session will automatically know that it needs to re-serialize its data, thus callingchanged()
is unnecessary. There is no harm in callingchanged()
in either case, so when in doubt, call it after you’ve changed sessioning data.
-
invalidate
()¶ Call this when you want to invalidate the session (dump all data, and – perhaps – set a clearing cookie).
-
Session storages¶
aiohttp_session
uses storages to save/load persistend session data.
Abstract Storage¶
All storages should be derived from AbstractStorage
and
implement both load_session()
and
save_session()
methods.
-
class
aiohttp_session.
AbstractStorage
(cookie_name="AIOHTTP_SESSION", *, domain=None, max_age=None, path='/', secure=None, httponly=True, encoder=json.dumps, decoder=json.loads)¶ Base class for session storage implementations.
It uses HTTP cookie for storing at least the key for session data, but some implementations may save all session info into cookies.
cookie_name – name of cookie used for saving session data.
domain – cookie’s domain,
str
orNone
.max_age – cookie’s max age,
int
orNone
.path – cookie’s path,
str
orNone
.secure – cookie’s secure flag,
bool
orNone
(the same asFalse
).httponly – cookie’s http-only flag,
bool
orNone
(the same asFalse
).encoder – session serializer. A callable with the following signature: def encode(param: Any) -> str: …. Default is
json.dumps()
.decoder – session deserializer. A callable with the following signature: def decode(param: str) -> Any: …. Default is
json.loads()
.New in version 2.3: Added encoder and decoder parameters.
-
max_age
¶ Maximum age for session data,
int
seconds orNone
for “session cookie” which last until you close your browser.
Name of cookie used for saving session data.
dict
of cookie params: domain, max_age, path, secure and httponly.
-
encoder
¶ The JSON serializer that will be used to dump session cookie data.
New in version 2.3.
-
decoder
¶ The JSON deserializer that will be used to load session cookie data.
New in version 2.3.
-
new_session
()¶ A coroutine for getting a new session regardless of whether a cookie exists.
Return
Session
instance.
-
load_session
(request)¶ An abstract coroutine, called by internal machinery for retrieving
Session
object for given request (aiohttp.web.Request
instance).Return
Session
instance.
-
save_session
(request, response, session)¶ An abstract coroutine, called by internal machinery for storing session (
Session
) instance for given request (aiohttp.web.Request
) using response (aiohttp.web.StreamResponse
or descendants).
A helper for loading cookie (
http.cookies.SimpleCookie
instance) from request (aiohttp.web.Request
).
A helper for saving cookie_data (
str
) into response (aiohttp.web.StreamResponse
or descendants).max_age is cookie lifetime given from session. Storage default is used if the value is
None
.
-
Simple Storage¶
For testing purposes there is SimpleCookieStorage
. It stores
session data as unencrypted and unsigned JSON data in browser cookies,
so it’s totally insecure.
Warning
Never use this storage on production!!! It’s highly insecure!!!
To use the storage you should push it into
session_middleware()
:
aiohttp_session.setup(app, aiohttp_session.SimpleCookieStorage())
-
class
aiohttp_session.
SimpleCookieStorage
(*, cookie_name="AIOHTTP_SESSION", domain=None, max_age=None, path='/', secure=None, httponly=True, encoder=json.dumps, decoder=json.loads)¶ Create unencrypted cookie storage.
The class is inherited from
AbstractStorage
.Parameters are the same as for
AbstractStorage
constructor.
Cookie Storage¶
The storage that saves session data in HTTP cookies as
Fernet
encrypted data.
To use the storage you should push it into
session_middleware()
:
app = aiohttp.web.Application(middlewares=[
aiohttp_session.cookie_storage.EncryptedCookieStorage(
b'Thirty two length bytes key.')])
Create encryted cookies storage.
The class is inherited from
AbstractStorage
.secret_key is
bytes
secret key with length of 32, used for encoding or base-64 encodedstr
one.Other parameters are the same as for
AbstractStorage
constructor.Note
For key generation use
cryptography.fernet.Fernet.generate_key()
method.
NaCl Storage¶
The storage that saves session data in HTTP cookies as
SecretBox
encrypted data.
To use the storage you should push it into
session_middleware()
:
app = aiohttp.web.Application(middlewares=[
aiohttp_session.nacl_storage.NaClCookieStorage(
b'Thirty two length bytes key.'])
Create encryted cookies storage.
The class is inherited from
AbstractStorage
.secret_key is
bytes
secret key with length of 32, used for encoding.Other parameters are the same as for
AbstractStorage
constructor.
Redis Storage¶
The storage that stores session data in Redis database and keeps only Redis keys (UUIDs actually) in HTTP cookies.
It operates with Redis database via redis.asyncio.Redis
.
To use the storage you need setup it first:
redis = await aioredis.from_url("redis://127.0.0.1:6379")
storage = aiohttp_session.redis_storage.RedisStorage(redis)
aiohttp_session.setup(app, storage)
-
class
aiohttp_session.redis_storage.
RedisStorage
(redis_pool, *, cookie_name="AIOHTTP_SESSION", domain=None, max_age=None, path='/', secure=None, httponly=True, key_factory=lambda: uuid.uuid4().hex, encoder=json.dumps, decoder=json.loads)¶ Create Redis storage for user session data.
The class is inherited from
AbstractStorage
.redis_pool is a
Redis
which should be created byfrom_url()
call, e.g.:redis = await aioredis.from_url("redis://localhost:6379") storage = aiohttp_session.redis_storage.RedisStorage(redis)
Other parameters are the same as for
AbstractStorage
constructor.
Memcached Storage¶
The storage that stores session data in Memcached and keeps only keys (UUIDs actually) in HTTP cookies.
It operates with Memcached database via aiomcache.Client
.
To use the storage you need setup it first:
mc = aiomcache.Client('localhost', 11211)
storage = aiohttp_session.memcached_storage.Client(mc)
aiohttp_session.setup(app, storage)
New in version 1.2.
-
class
aiohttp_session.redis_storage.
MemcachedStorage
(memcached_conn, *, cookie_name="AIOHTTP_SESSION", domain=None, max_age=None, path='/', secure=None, httponly=True, key_factory=lambda: uuid.uuid4().hex, encoder=json.dumps, decoder=json.loads)¶ Create Memcached storage for user session data.
The class is inherited from
AbstractStorage
.memcached_conn is a
Client
instance:mc = await aiomcache.Client('localhost', 6379) storage = aiohttp_session.memcached_storage.MemcachedStorage(mc)
Other parameters are the same as for
AbstractStorage
constructor.