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

Cache backend that stores entries in a relational database table.

Mirrors database cache store: entries live in a dedicated table (cache_key / cache_value / expiration) resolved through the cache.stores.database configuration, and atomic locks used by Cache::lock() are kept in a separate cache_locks-like table so the database driver does not require Redis or Memcached to support locking.

Async Method __currentCounter Return the raw payload and integer value stored at key.
Method __decode Deserialize a stored JSON payload back into a Python object.
Method __encode Serialize value to a JSON string suitable for storage.
Method __init__ Initialize the backend bound to a connection and table names.
Async Method __insertOrRetryUpdate Insert a new cache row, falling back to an update on conflict.
Async Method _ensureSchema Create the cache and lock tables on first use, if missing.
Async Method acquireLock Attempt to acquire the row-based lock for key in a single try.
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 table.
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 migrate Create the framework cache and lock tables without removing existing data.
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 shared TTL.
Async Method releaseLock Release the row-based lock for key when still owned by owner.
Async Method replace Replace a live cache row with a single conditional update.
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 _connection Database connection used to store cache entries and locks.
Instance Variable _entry_definition Entry definition produced by _build_entries_table.
Instance Variable _lock_definition Lock definition produced by _build_locks_table.
Instance Variable _lock_table Table name used to store atomic locks. Defaults to 'cache_locks' when not provided.
Instance Variable _ready Ready flag used by DatabaseCacheBackend.
Instance Variable _ready_lock Synchronization primitive controlling access to ready lock.
Instance Variable _table Table name used to store cache entries.
async def __currentCounter(self, key: str) -> tuple[str, int] | None: (source)

Return the raw payload and integer value stored at key.

Parameters
key:strCache key.
Returns
tuple[str, int] | NoneThe stored payload exactly as persisted, used later as the compare-and-swap witness, together with its integer value. None when the row is missing or already expired.
def __decode(self, raw: str | bytes | None) -> Any: (source)

Deserialize a stored JSON payload back into a Python object.

Parameters
raw:str | bytes | NoneRaw payload read from the cache_value column.
Returns
typing.AnyDecoded value, or None when raw is missing or invalid.
def __encode(self, value: Any) -> str: (source)

Serialize value to a JSON string suitable for storage.

Parameters
value:typing.AnyJSON-serializable value to encode.
Returns
strUTF-8 decoded JSON payload.
def __init__(self, connection: IConnection, table: str, lock_table: str | None = None): (source)

Initialize the backend bound to a connection and table names.

Parameters
connection:orionis.database.contracts.IConnectionDatabase connection used to store cache entries and locks.
table:strTable name used to store cache entries.
lock_table:str | None, optionalTable name used to store atomic locks. Defaults to 'cache_locks' when not provided.
Returns
NoneNo return value.
async def __insertOrRetryUpdate(self, key: str, encoded: str, expiration: float | None): (source)

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

Parameters
key:strCache key.
encoded:strJSON-encoded value already serialized by set.
expiration:float | NoneAbsolute expiration timestamp, or None for no expiry.
Returns
NoneNo return value.
async def _ensureSchema(self): (source)

Create the cache and lock tables on first use, if missing.

Returns
NoneNo return value.
async def acquireLock(self, key: str, owner: str, lease: float) -> bool: (source)

Attempt to acquire the row-based lock for key in a single try.

Inserts a fresh row for the lock, or steals an expired or self-owned row when the insert conflicts, mirroring DatabaseLock::acquire().

Parameters
key:strResource key to lock.
owner:strUnique token identifying the caller attempting to acquire.
lease:floatNumber of seconds the lock remains valid once acquired.
Returns
boolTrue when the lock was acquired.
Raises
orionis.database.exceptions.QueryExceptionIf insertion fails without an existing competing lock row.
async def add(self, key: str, value: Any, ttl: float | None = None) -> bool: (source)

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

The primary key decides the winner, so concurrent callers never both succeed and the operation is safe as a mutual-exclusion primitive.

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.
orionis.database.QueryExceptionIf the insert fails for any reason other than the key being already taken.
async def clear(self) -> bool: (source)

Remove all cache entries from the store table.

Returns
boolAlways True.
async def delete(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, 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, key: str, default: Any = None) -> Any: (source)

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

Expired entries are deleted on first read (lazy eviction), mirroring DatabaseStore::get().

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, 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. The update is applied with a compare-and-swap so concurrent writers never lose an increment, without relying on row-locking syntax that not every dialect supports.

Parameters
key:strCache key.
delta:intAmount to add (use negative values to decrement).
Returns
intNew value after increment.
Raises
orionis.database.QueryExceptionIf contention prevents the update from landing after _INCREMENT_ATTEMPTS rounds.
async def migrate(self): (source)

Create the framework cache and lock tables without removing existing data.

Returns
NoneNo return value.
Raises
orionis.database.QueryExceptionIf the connection cannot create either table.
async def multiGet(self, keys: list[str], default: Any = 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, pairs: list[tuple[str, Any]], ttl: float | None = None) -> bool: (source)

Store multiple key/value pairs with an optional shared 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 releaseLock(self, key: str, owner: str): (source)

Release the row-based lock for key when still owned by owner.

Parameters
key:strResource key to release.
owner:strToken that must match the current row owner.
Returns
NoneNo return value.
async def replace(self, key: str, value: Any, ttl: float | None = None) -> bool: (source)

Replace a live cache row with a single conditional update.

Parameters
key:strExisting cache key.
value:typing.AnyReplacement value.
ttl:float | NoneReplacement lifetime in seconds.
Returns
boolFalse when the entry is missing or has expired.
async def set(self, key: str, value: Any, ttl: float | None = None) -> bool: (source)

Store value under key with an optional TTL in seconds.

Updates the row when it already exists, otherwise inserts a new one, providing upsert semantics across every supported dialect without relying on driver-specific ON CONFLICT syntax.

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.
Raises
orionis.database.exceptions.QueryExceptionIf the row cannot be inserted or updated.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_connection = (source)

Database connection used to store cache entries and locks.

_entry_definition = (source)

Entry definition produced by _build_entries_table.

_lock_definition = (source)

Lock definition produced by _build_locks_table.

_lock_table = (source)

Table name used to store atomic locks. Defaults to 'cache_locks' when not provided.

Ready flag used by DatabaseCacheBackend.

_ready_lock = (source)

Synchronization primitive controlling access to ready lock.

Table name used to store cache entries.