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 FileSessionStore(ISessionStore): (source)
Constructor: FileSessionStore(directory)
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 | |
| directory | Path to the directory where session files are stored. |
| Static Method | _temp |
Build a unique staging path for an atomic write. |
| Method | __init__ |
Resolve the storage directory and create it when missing. |
| Method | _delete |
Unlink path, silently ignoring a missing-file error. |
| Method | _delete |
Remove stale staging data after its session writer releases ownership. |
| Method | _deserialize |
Decode JSON bytes into a session record. |
| Method | _gc |
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 | _read |
Read path as raw bytes, returning None if absent. |
| Method | _read |
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 | _update |
Replace an existing live session under its cross-process lock. |
| Method | _write |
Atomically write content to path. |
| Method | _write |
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 |
Writes run on worker threads, so publishing two payloads for the same session must not overlap inside this process. |
Build a unique staging path for an atomic write.
| Parameters | |
path:pathlib.Path | Final destination file. |
| Returns | |
pathlib.Path | Sibling 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. |
Resolve the storage directory and create it when missing.
| Parameters | |
directory:pathlib.Path | Filesystem path to the session storage directory. |
| Returns | |
None | No return value. |
Unlink path, silently ignoring a missing-file error.
| Parameters | |
path:pathlib.Path | Session file to remove. |
| Returns | |
bool | True when this call removed the session file. |
Remove stale staging data after its session writer releases ownership.
| Parameters | |
path:pathlib.Path | Staging file whose name matches the writer's format. |
stalefloat | Latest modification time eligible for cleanup, in epoch seconds. |
| Returns | |
None | No return value. |
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:bytes | Raw JSON bytes previously written by
orionis.session.stores.file.FileSessionStore._serialize. |
| Returns | |
orionis.session.entities.record.SessionRecord | None | Deserialised record, or None on any decode error. |
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 | |
None | No return value. |
Select a bounded, stable cross-process lock for a session file.
| Parameters | |
path:pathlib.Path | Session file protected by the lock. |
| Returns | |
filelock.BaseFileLock | Platform lock serializing validation, replacement and deletion. |
Return the absolute path to the JSON file for session_id.
| Parameters | |
sessionstr | Unique session identifier. |
| Returns | |
pathlib.Path | Full path to {session_id}.json inside the store directory. |
| Raises | |
orionis.session.exceptions.SessionStorageException | If an identifier contains path syntax or exceeds its limit. |
Read path as raw bytes, returning None if absent.
| Parameters | |
path:pathlib.Path | File to read. |
| Returns | |
bytes | None | File contents, or None when the file does not exist. |
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.Path | Session file to load. |
| Returns | |
orionis.session.entities.record.SessionRecord | None | The live record, or None when absent, expired or corrupt. |
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.Path | Staging file holding the serialised payload. |
path:pathlib.Path | Destination session file. |
| Returns | |
None | No return value. |
| Raises | |
OSError | If the rename keeps failing after the last attempt. |
Encode record to compact JSON bytes via msgspec.
| Parameters | |
record:orionis.session.entities.record.SessionRecord | Record to serialise. |
| Returns | |
bytes | UTF-8 encoded JSON payload. |
Replace an existing live session under its cross-process lock.
| Parameters | |
path:pathlib.Path | Existing session file. |
record:orionis.session.entities.record.SessionRecord | Replacement record. |
| Returns | |
bool | False when another worker deleted or expired the record. |
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.Path | Destination file path. |
content:bytes | Serialised session payload. |
| Returns | |
None | No return value. |
| Raises | |
OSError | If the payload cannot be staged or renamed into place. |
Serialise record and store it atomically at path.
| Parameters | |
path:pathlib.Path | Destination session file. |
record:orionis.session.entities.record.SessionRecord | The record to persist. |
| Returns | |
None | No return value. |
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 | |
None | No return value. |
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 | |
sessionstr | Unique session identifier to look up. |
| Returns | |
orionis.session.entities.record.SessionRecord | None | The live record, or None when absent, expired, or corrupt. |
Update only a live session without recreating a deleted file.
| Parameters | |
record:orionis.session.entities.record.SessionRecord | Replacement record. |
| Returns | |
bool | Whether the session still existed and was updated. |
Serialise and persist record to disk atomically.
| Parameters | |
record:orionis.session.entities.record.SessionRecord | The record to store. |
| Returns | |
None | No return value. |