ORIONIS API REFERENCE

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

class documentation

Session store that persists each session as a row in a database table.

Mirrors orionis.cache.stores.database.DatabaseCacheBackend: records live in a dedicated table (id / payload / expires_at) resolved through the session.connection configuration, using upsert-by-retry semantics so no dialect-specific ON CONFLICT syntax is required.

Unlike the cache backend, a plain SQL table has no native TTL, so expired rows are evicted lazily on orionis.session.stores.database.DatabaseSessionStore.read and can be swept in bulk via orionis.session.stores.database.DatabaseSessionStore.gc.

Parameters
connectionDatabase connection used to persist session records.
tableTable name used to store session records. Defaults to 'sessions'.
Method __decode Deserialize a stored JSON payload back into a Python dict.
Method __encode Serialize data to a JSON string suitable for storage.
Method __init__ Bind the store to connection and the target table.
Async Method __insertOrRetryUpdate Insert a new session row, falling back to an update on conflict.
Async Method _ensureSchema Create the sessions table on first use, if missing.
Async Method delete Remove the record for session_id (no-op when absent).
Async Method gc Remove all rows whose expires_at is in the past.
Async Method migrate Create the framework session table without removing existing data.
Async Method read Return the stored record for session_id, or None.
Async Method update Update only a live session row with a single SQL statement.
Async Method write Insert or replace the record keyed by its identifier.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _connection Database connection used to persist session records.
Instance Variable _definition Original declaration from which runtime metadata was compiled.
Instance Variable _ready Ready flag used by DatabaseSessionStore.
Instance Variable _ready_lock Synchronization primitive controlling access to ready lock.
Instance Variable _table Table name used to store session records.
def __decode(self, raw: str | bytes | None) -> dict[str, Any] | None: (source)

Deserialize a stored JSON payload back into a Python dict.

Parameters
raw:str | bytes | NoneRaw payload read from the payload column.
Returns
dict[str, typing.Any] | NoneDecoded data, or None when raw is missing or invalid.
def __encode(self, data: dict[str, Any]) -> str: (source)

Serialize data to a JSON string suitable for storage.

Parameters
data:dict[str, typing.Any]Session data payload to encode.
Returns
strUTF-8 decoded JSON payload.
def __init__(self, connection: IConnection, table: str = _DEFAULT_TABLE): (source)

Bind the store to connection and the target table.

Parameters
connection:orionis.database.contracts.IConnectionDatabase connection used to persist session records.
table:str, optionalTable name used to store session records.
Returns
NoneNo return value.
async def __insertOrRetryUpdate(self, session_id: str, payload: str, expiration: int): (source)

Insert a new session row, falling back to an update on conflict.

Observe a failed retry separately and preserve the original insertion error when recovery cannot be confirmed.

Parameters
session_id:strUnique session identifier.
payload:strJSON-encoded session data already serialized by orionis.session.stores.database.DatabaseSessionStore.write.
expiration:intAbsolute expiration timestamp (whole epoch seconds).
Returns
NoneNo return value.
async def _ensureSchema(self): (source)

Create the sessions table on first use, if missing.

Returns
NoneNo return value.
async def delete(self, session_id: str) -> bool: (source)

Remove the record for session_id (no-op when absent).

Parameters
session_id:strUnique session identifier to remove.
Returns
boolTrue only when a row was deleted.
async def gc(self): (source)

Remove all rows whose expires_at is in the past.

Unlike a native TTL-backed cache, a SQL table never evicts stale rows on its own, so this performs a single bulk DELETE.

Returns
NoneNo return value.
async def migrate(self): (source)

Create the framework session table without removing existing data.

Returns
NoneNo return value.
Raises
orionis.database.QueryExceptionIf the connection cannot create the table.
async def read(self, session_id: str) -> SessionRecord | None: (source)

Return the stored record for session_id, or None.

Parameters
session_id:strUnique session identifier to look up.
Returns
orionis.session.entities.record.SessionRecord | NoneThe stored record, or None when absent, expired or corrupted.
async def update(self, record: SessionRecord) -> bool: (source)

Update only a live session row with a single SQL statement.

Parameters
record:orionis.session.entities.record.SessionRecordReplacement payload and expiration.
Returns
boolFalse when the session was deleted or expired.
async def write(self, record: SessionRecord): (source)

Insert or replace the record keyed by its identifier.

A record that has already expired is deleted instead of written.

Parameters
record:orionis.session.entities.record.SessionRecordThe record to persist.
Returns
NoneNo return value.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_connection = (source)

Database connection used to persist session records.

_definition = (source)

Original declaration from which runtime metadata was compiled.

Ready flag used by DatabaseSessionStore.

_ready_lock = (source)

Synchronization primitive controlling access to ready lock.

Table name used to store session records.