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

class FileSessionStore(ISessionStore): (source)

Constructor: FileSessionStore(directory)

View In Hierarchy

Session store that persists each session as a JSON file on disk.

One JSON file per session, named {session_id}.json, stored inside directory. Resolve relative directories when constructing the store and create the directory when it does not exist. Active worker operations finish before caller cancellation propagates; cancellation does not roll back a write or deletion that has already completed.

Expired sessions are evicted lazily during orionis.session.stores.file.FileSessionStore.read, keeping hot-path operations at O(1) complexity. Bulk removal of stale files can be triggered explicitly via orionis.session.stores.file.FileSessionStore.gc.

Notes

The JSON envelope stores id, expires_at and data. Payloads must be JSON-compatible, and expiration is represented as a UTC timestamp.

Parameters
directoryPath to the directory where session files are stored.
Static Method _tempPath Build a unique staging path for an atomic write.
Method __init__ Resolve the storage directory and create it when missing.
Method _deleteFile Unlink path, silently ignoring a missing-file error.
Method _deleteStaleTemp Remove stale staging data after its session writer releases ownership.
Method _deserialize Decode JSON bytes into a session record.
Method _gcSweep Scan the store directory and remove stale or corrupt files.
Method _lock Select a bounded, stable cross-process lock for a session file.
Method _path Return the absolute path to the JSON file for session_id.
Method _readFile Read path as raw bytes, returning None if absent.
Method _readRecord Load, decode and validate the record stored at path.
Method _replace Publish tmp as path, retrying a transient sharing violation.
Method _serialize Encode record to compact JSON bytes via msgspec.
Method _updateRecord Replace an existing live session under its cross-process lock.
Method _writeFile Atomically write content to path.
Method _writeRecord Serialise record and store it atomically at path.
Async Method delete Remove the session file for session_id (no-op when absent).
Async Method gc Remove all expired, corrupt, or incomplete session files.
Async Method read Load and return the live record for session_id, or None.
Async Method update Update only a live session without recreating a deleted file.
Async Method write Serialise and persist record to disk atomically.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _directory Canonical absolute directory containing the session files.
Instance Variable _locks Locks produced by tuple.
Instance Variable _rename_lock Writes run on worker threads, so publishing two payloads for the same session must not overlap inside this process.
def _tempPath(path: Path) -> Path: (source)

Build a unique staging path for an atomic write.

Parameters
path:pathlib.PathFinal destination file.
Returns
pathlib.PathSibling path carrying a random infix, so concurrent writers of the same session never share a staging file, and still ending in .tmp so the sweep keeps telling both apart.
def __init__(self, directory: Path): (source)

Resolve the storage directory and create it when missing.

Parameters
directory:pathlib.PathFilesystem path to the session storage directory.
Returns
NoneNo return value.
def _deleteFile(self, path: Path) -> bool: (source)

Unlink path, silently ignoring a missing-file error.

Parameters
path:pathlib.PathSession file to remove.
Returns
boolTrue when this call removed the session file.
def _deleteStaleTemp(self, path: Path, stale_before: float): (source)

Remove stale staging data after its session writer releases ownership.

Parameters
path:pathlib.PathStaging file whose name matches the writer's format.
stale_before:floatLatest modification time eligible for cleanup, in epoch seconds.
Returns
NoneNo return value.
def _deserialize(self, raw: bytes) -> SessionRecord | None: (source)

Decode JSON bytes into a session record.

Return a orionis.session.entities.record.SessionRecord instance. Type validation is delegated entirely to msgspec; any structural mismatch or missing field is treated as corruption.

Parameters
raw:bytesRaw JSON bytes previously written by orionis.session.stores.file.FileSessionStore._serialize.
Returns
orionis.session.entities.record.SessionRecord | NoneDeserialised record, or None on any decode error.
def _gcSweep(self): (source)

Scan the store directory and remove stale or corrupt files.

Scan with os.scandir and remove expired or corrupt session files. Observe I/O failures without deleting unreadable files. Consider only staging names produced by the writer, acquiring the corresponding session lock before checking their age and removing them.

Returns
NoneNo return value.
def _lock(self, path: Path) -> BaseFileLock: (source)

Select a bounded, stable cross-process lock for a session file.

Parameters
path:pathlib.PathSession file protected by the lock.
Returns
filelock.BaseFileLockPlatform lock serializing validation, replacement and deletion.
def _path(self, session_id: str) -> Path: (source)

Return the absolute path to the JSON file for session_id.

Parameters
session_id:strUnique session identifier.
Returns
pathlib.PathFull path to {session_id}.json inside the store directory.
Raises
orionis.session.exceptions.SessionStorageExceptionIf an identifier contains path syntax or exceeds its limit.
def _readFile(self, path: Path) -> bytes | None: (source)

Read path as raw bytes, returning None if absent.

Parameters
path:pathlib.PathFile to read.
Returns
bytes | NoneFile contents, or None when the file does not exist.
def _readRecord(self, path: Path) -> SessionRecord | None: (source)

Load, decode and validate the record stored at path.

Runs entirely on a worker thread: file I/O, JSON decoding and the eviction of an expired or corrupt file happen in a single hop.

Parameters
path:pathlib.PathSession file to load.
Returns
orionis.session.entities.record.SessionRecord | NoneThe live record, or None when absent, expired or corrupt.
def _replace(self, tmp: Path, path: Path): (source)

Publish tmp as path, retrying a transient sharing violation.

The rename is serialised per store instance, and retried when the operating system refuses it because another process is swapping the same destination. POSIX never reaches the retry branch.

Parameters
tmp:pathlib.PathStaging file holding the serialised payload.
path:pathlib.PathDestination session file.
Returns
NoneNo return value.
Raises
OSErrorIf the rename keeps failing after the last attempt.
def _serialize(self, record: SessionRecord) -> bytes: (source)

Encode record to compact JSON bytes via msgspec.

Parameters
record:orionis.session.entities.record.SessionRecordRecord to serialise.
Returns
bytesUTF-8 encoded JSON payload.
def _updateRecord(self, path: Path, record: SessionRecord) -> bool: (source)

Replace an existing live session under its cross-process lock.

Parameters
path:pathlib.PathExisting session file.
record:orionis.session.entities.record.SessionRecordReplacement record.
Returns
boolFalse when another worker deleted or expired the record.
def _writeFile(self, path: Path, content: bytes): (source)

Atomically write content to path.

Writes to a unique .tmp sibling first, then renames over the destination to prevent partial reads from concurrent processes. A failed write removes its own staging file before propagating.

Parameters
path:pathlib.PathDestination file path.
content:bytesSerialised session payload.
Returns
NoneNo return value.
Raises
OSErrorIf the payload cannot be staged or renamed into place.
def _writeRecord(self, path: Path, record: SessionRecord): (source)

Serialise record and store it atomically at path.

Parameters
path:pathlib.PathDestination session file.
record:orionis.session.entities.record.SessionRecordThe record to persist.
Returns
NoneNo return value.
async def delete(self, session_id: str) -> bool: (source)

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

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

Remove all expired, corrupt, or incomplete session files.

The directory scan runs on a thread-pool worker so it never blocks the event loop. This method must be called explicitly; it is never triggered automatically by orionis.session.stores.file.FileSessionStore.read, orionis.session.stores.file.FileSessionStore.write, or orionis.session.stores.file.FileSessionStore.delete.

Returns
NoneNo return value.
async def read(self, session_id: str) -> SessionRecord | None: (source)

Load and return the live record for session_id, or None.

Expired or corrupt records are evicted lazily: the file is deleted and None is returned without triggering a GC cycle.

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

Update only a live session without recreating a deleted file.

Parameters
record:orionis.session.entities.record.SessionRecordReplacement record.
Returns
boolWhether the session still existed and was updated.
async def write(self, record: SessionRecord): (source)

Serialise and persist record to disk atomically.

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

Declare the instance attribute slots reserved by this class.

_directory = (source)

Canonical absolute directory containing the session files.

Locks produced by tuple.

_rename_lock = (source)

Writes run on worker threads, so publishing two payloads for the same session must not overlap inside this process.