Session

Session management: store, session objects, and user avatars.

Session

Server-managed session with metadata, Bag data, and auth context.

A Session groups request-scoped state under a unique ID with expiry tracking. SessionMiddleware creates or reconnects sessions via cookies and attaches them to scope["session"]. Each session holds an Avatar for the authenticated user and a Bag for arbitrary application data.

class genro_asgi.session.session.Session(session_id, auth, ttl)[source]

Bases: object

Server-managed session with meta, data (Bag), and auth snapshot.

_id: Unique session token.

_meta: Server-managed metadata (created_at, last_access, ttl).

_data: Application data as Bag.

_auth: Auth snapshot from session creation.

__init__(session_id, auth, ttl)[source]

Initialize session.

Parameters:

session_id (str) – Unique session token.
auth (dict[str, Any] | None) – Auth dict snapshot from authentication, or None.
ttl (int) – Time-to-live in seconds.

property auth: dict[str, Any] | None: Auth snapshot from session creation.

property avatar: Avatar: User identity avatar built from auth snapshot.

property data: Bag: Application data as Bag.

property id: str: Unique session token.

is_expired()[source]

Check if session has exceeded its TTL.

Return type:: bool

property meta: dict[str, Any]

created_at, last_access, ttl.

Type:: Server-managed metadata

touch()[source]

Update last_access timestamp.

Return type:: None

SessionStore

Session store — protocol and in-memory implementation.

class genro_asgi.session.store.MemorySessionStore(default_ttl=3600)[source]

Bases: object

In-memory session store. Default implementation.

_sessions: Dict mapping session_id to Session.

_default_ttl: Default TTL in seconds for new sessions.

__init__(default_ttl=3600)[source]

Initialize store.

Parameters:: default_ttl (int) – Default time-to-live in seconds for new sessions.

create(auth=None)[source]

Create a new session with unique token.

Parameters:: auth (dict[str, Any] | None) – Auth dict snapshot to store in session.
Return type:: Session
Returns:: New Session instance.

delete(session_id)[source]

Remove session from store.

Return type:: None

dump()[source]

Serialize all sessions for persistence.

Return type:: dict[str, Any]

get(session_id)[source]

Retrieve session by id. Returns None if not found or expired.

Return type:: Session | None

restore(data)[source]

Restore sessions from serialized data.

Parameters:: data (dict[str, Any]) – Dict from dump() output.
Return type:: None

class genro_asgi.session.store.SessionStore(*args, **kwargs)[source]

Bases: Protocol

Protocol for session storage backends.

create(auth=None)[source]

Create a new session with unique token.

Return type:: Session

delete(session_id)[source]

Remove session from store.

Return type:: None

dump()[source]

Serialize all sessions for persistence.

Return type:: dict[str, Any]

get(session_id)[source]

Retrieve session by id, or None if not found/expired.

Return type:: Session | None

restore(data)[source]

Restore sessions from serialized data.

Return type:: None

Avatar

Avatar — user identity with tags and extensible Bag data.

An Avatar is the authenticated user’s profile within a session. It carries the identity string, authorization tags, and arbitrary key-value data stored in a Bag. Created by SessionMiddleware from the auth result, or directly via Avatar(identity, tags, data).

class genro_asgi.session.avatar.Avatar(identity='anonymous', tags=None, auth=None)[source]

Bases: object

User identity with tags and extensible data (Bag).

_identity: User identifier (username, email, etc.).

_tags: Authorization tags (roles/permissions).

_data: Extensible user data as Bag.

__init__(identity='anonymous', tags=None, auth=None)[source]

Initialize avatar.

Parameters:

identity (str) – User identifier (ignored if auth is provided).
tags (list[str] | None) – Authorization tags (ignored if auth is provided).
auth (dict[str, Any] | None) – Auth dict — if provided, identity and tags are extracted from it.

property data: Bag: Extensible user data as Bag.

property identity: str: User identifier.

property tags: list[str]: Authorization tags.