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 FileCacheBackend: (source)

Constructor: FileCacheBackend(path)

View In Hierarchy

Implement asynchronous cache operations over filesystem entries.

Static Method __readEntryUnlocked Read a cache entry while its file lock is held.
Static Method __tempPath Return a unique staging path for file.
Method __createSync Publish entry atomically only when its locked path is absent.
Method __file Return the filesystem path for key.
Method __incrementSync Update a counter while holding its file lock.
Method __init__ Initialize the backend and create the cache directory if needed.
Method __lock Select the stable cross-process lock stripe for a cache file.
Method __readSync Read and decode a cache file synchronously.
Method __replaceIfPresent Replace a live entry while holding its cross-process lock.
Method __replaceSync Publish tmp as file, retrying a transient sharing violation.
Method __unlinkSync Remove file, ignoring missing-file errors.
Method __writeEntryUnlocked Publish a cache entry while its file lock is held.
Method __writeSync Atomically write entry to file via tmp-then-rename.
Async Method add Store value under key only if the key does not already exist.
Async Method clear Remove all cache entries from the store directory.
Async Method delete Remove key from the store.
Async Method exists Return True if key exists and has not expired.
Async Method get Return the cached value for key, or default when absent/expired.
Async Method increment Increment the integer stored at key by delta.
Async Method multiGet Return a list of values for keys in the same order.
Async Method multiSet Store multiple key/value pairs with an optional TTL.
Async Method replace Replace an existing live key without recreating a deleted entry.
Async Method set Store value under key with an optional TTL in seconds.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _counter_lock Queue counter updates made through this backend instance.
Instance Variable _locks Locks produced by tuple.
Instance Variable _path Directory where cache files will be stored.
Instance Variable _rename_lock Writes run in worker threads, so the rename needs a thread lock.
Property lockNamespace Return the canonical directory used to identify cache locks.
def __readEntryUnlocked(file: Path) -> dict | None: (source)

Read a cache entry while its file lock is held.

Parameters
file:pathlib.PathPath to the cache entry.
Returns
dict | NoneLive decoded entry, or None when missing, expired, or invalid.
def __tempPath(file: Path) -> Path: (source)

Return a unique staging path for file.

Parameters
file:pathlib.PathTarget cache file.
Returns
pathlib.PathSibling path ending in .tmp that no concurrent writer of the same key can collide with.
def __createSync(self: Self, file: Path, entry: dict) -> bool: (source)

Publish entry atomically only when its locked path is absent.

Parameters
file:pathlib.PathTarget cache file.
entry:dictSerializable cache entry.
Returns
boolTrue when the file was created by this call, False when another writer got there first.
def __file(self: Self, key: str) -> Path: (source)

Return the filesystem path for key.

Parameters
key:strCache key.
Returns
pathlib.PathPath to the corresponding .json file.
def __incrementSync(self: Self, file: Path, delta: int) -> int: (source)

Update a counter while holding its file lock.

Parameters
file:pathlib.PathCounter file to update.
delta:intAmount to add to the current value.
Returns
intUpdated counter value.
def __init__(self: Self, path: Path): (source)

Initialize the backend and create the cache directory if needed.

Parameters
path:pathlib.PathDirectory where cache files will be stored.
Returns
NoneNo return value.
def __lock(self: Self, file: Path) -> BaseFileLock: (source)

Select the stable cross-process lock stripe for a cache file.

Parameters
file:pathlib.PathCache file protected by the lock.
Returns
filelock.BaseFileLockPlatform lock shared by writes, replacement and deletion.
def __readSync(self: Self, file: Path) -> dict | None: (source)

Read and decode a cache file synchronously.

Parameters
file:pathlib.PathPath to the cache file.
Returns
dict | NoneLive entry, or None when absent, expired, unreadable or malformed.
def __replaceIfPresent(self: Self, file: Path, entry: dict) -> bool: (source)

Replace a live entry while holding its cross-process lock.

Parameters
file:pathlib.PathTarget cache file.
entry:dictEncoded replacement entry.
Returns
boolFalse when the previous entry has disappeared or expired.
def __replaceSync(self: Self, tmp: Path, file: Path): (source)

Publish tmp as file, retrying a transient sharing violation.

Parameters
tmp:pathlib.PathStaging file holding the encoded entry.
file:pathlib.PathDestination cache file.
Returns
NoneNo return value.
Raises
OSErrorIf the rename keeps failing after the last attempt.
def __unlinkSync(self: Self, file: Path) -> int: (source)

Remove file, ignoring missing-file errors.

Parameters
file:pathlib.PathFile to remove.
Returns
intOne when a file was removed, otherwise zero.
def __writeEntryUnlocked(self: Self, file: Path, entry: dict): (source)

Publish a cache entry while its file lock is held.

Parameters
file:pathlib.PathDestination cache file.
entry:dictEncodable cache entry.
Returns
NoneNo return value.
Raises
OSErrorIf staging or publishing the entry fails.
def __writeSync(self: Self, file: Path, entry: dict): (source)

Atomically write entry to file via tmp-then-rename.

Parameters
file:pathlib.PathTarget cache file.
entry:dictSerializable cache entry.
Returns
NoneNo return value.
Raises
OSErrorIf the entry cannot be staged or renamed into place.
async def add(self: Self, key: str, value: Any, ttl: float | None = None) -> bool: (source)

Store value under key only if the key does not already exist.

Hold the cross-process file lock while checking absence and atomically publishing a staged entry. Concurrent callers cannot both succeed.

Parameters
key:strCache key.
value:typing.AnyValue to store.
ttl:float | NoneOptional TTL in seconds.
Returns
boolTrue on success.
Raises
ValueErrorIf the key already exists and has not expired.
async def clear(self: Self) -> bool: (source)

Remove all cache entries from the store directory.

Returns
boolAlways True.
async def delete(self: Self, key: str) -> int: (source)

Remove key from the store.

Parameters
key:strCache key.
Returns
int1 if the key existed, 0 otherwise.
async def exists(self: Self, key: str) -> bool: (source)

Return True if key exists and has not expired.

Parameters
key:strCache key.
Returns
boolTrue when the cache key exists and its entry has not expired.
async def get(self: Self, key: str, default: Any | None = None) -> Any: (source)

Return the cached value for key, or default when absent/expired.

Expired entries are deleted on first read (lazy eviction).

Parameters
key:strCache key.
default:typing.AnyValue returned when the key is not found or has expired.
Returns
typing.AnyStored value or default.
async def increment(self: Self, key: str, delta: int = 1) -> int: (source)

Increment the integer stored at key by delta.

Creates the key with value delta if it does not exist, and keeps the expiry of an existing entry untouched.

Parameters
key:strCache key.
delta:intAmount to add (use negative values to decrement).
Returns
intNew value after increment.
async def multiGet(self: Self, keys: list[str], default: Any | None = None) -> list[Any]: (source)

Return a list of values for keys in the same order.

Parameters
keys:list[str]Cache keys.
default:typing.AnyReturned for each missing/expired key.
Returns
list[typing.Any]Cached values in key order, using the supplied default for misses.
async def multiSet(self: Self, pairs: list[tuple[str, Any]], ttl: float | None = None) -> bool: (source)

Store multiple key/value pairs with an optional TTL.

Parameters
pairs:list[tuple[str, typing.Any]]Sequence of (key, value) pairs.
ttl:float | NoneShared TTL applied to every pair.
Returns
boolAlways True.
async def replace(self: Self, key: str, value: Any, ttl: float | None = None) -> bool: (source)

Replace an existing live key without recreating a deleted entry.

Parameters
key:strExisting cache key.
value:typing.AnyReplacement value.
ttl:float | NoneReplacement lifetime in seconds.
Returns
boolWhether the entry was replaced atomically.
async def set(self: Self, key: str, value: Any, ttl: float | None = None) -> bool: (source)

Store value under key with an optional TTL in seconds.

Parameters
key:strCache key.
value:typing.AnyJSON-serializable value to cache.
ttl:float | NoneTime-to-live in seconds. None means no expiry.
Returns
boolAlways True.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_counter_lock = (source)

Queue counter updates made through this backend instance.

Locks produced by tuple.

Directory where cache files will be stored.

_rename_lock = (source)

Writes run in worker threads, so the rename needs a thread lock.

lockNamespace: Path = (source)

Return the canonical directory used to identify cache locks.

Returns
pathlib.PathAbsolute directory shared by backends storing the same files.