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.
Implement asynchronous cache operations over filesystem entries.
| Static Method | __read |
Read a cache entry while its file lock is held. |
| Static Method | __temp |
Return a unique staging path for file. |
| Method | __create |
Publish entry atomically only when its locked path is absent. |
| Method | __file |
Return the filesystem path for key. |
| Method | __increment |
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 | __read |
Read and decode a cache file synchronously. |
| Method | __replace |
Replace a live entry while holding its cross-process lock. |
| Method | __replace |
Publish tmp as file, retrying a transient sharing violation. |
| Method | __unlink |
Remove file, ignoring missing-file errors. |
| Method | __write |
Publish a cache entry while its file lock is held. |
| Method | __write |
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 | multi |
Return a list of values for keys in the same order. |
| Async Method | multi |
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 |
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 |
Writes run in worker threads, so the rename needs a thread lock. |
| Property | lock |
Return the canonical directory used to identify cache locks. |
Read a cache entry while its file lock is held.
| Parameters | |
file:pathlib.Path | Path to the cache entry. |
| Returns | |
dict | None | Live decoded entry, or None when missing, expired, or invalid. |
Return a unique staging path for file.
| Parameters | |
file:pathlib.Path | Target cache file. |
| Returns | |
pathlib.Path | Sibling path ending in .tmp that no concurrent writer of the same key can collide with. |
Publish entry atomically only when its locked path is absent.
| Parameters | |
file:pathlib.Path | Target cache file. |
entry:dict | Serializable cache entry. |
| Returns | |
bool | True when the file was created by this call, False when another writer got there first. |
Return the filesystem path for key.
| Parameters | |
key:str | Cache key. |
| Returns | |
pathlib.Path | Path to the corresponding .json file. |
Update a counter while holding its file lock.
| Parameters | |
file:pathlib.Path | Counter file to update. |
delta:int | Amount to add to the current value. |
| Returns | |
int | Updated counter value. |
Initialize the backend and create the cache directory if needed.
| Parameters | |
path:pathlib.Path | Directory where cache files will be stored. |
| Returns | |
None | No return value. |
Select the stable cross-process lock stripe for a cache file.
| Parameters | |
file:pathlib.Path | Cache file protected by the lock. |
| Returns | |
filelock.BaseFileLock | Platform lock shared by writes, replacement and deletion. |
Read and decode a cache file synchronously.
| Parameters | |
file:pathlib.Path | Path to the cache file. |
| Returns | |
dict | None | Live entry, or None when absent, expired, unreadable or malformed. |
Replace a live entry while holding its cross-process lock.
| Parameters | |
file:pathlib.Path | Target cache file. |
entry:dict | Encoded replacement entry. |
| Returns | |
bool | False when the previous entry has disappeared or expired. |
Publish tmp as file, retrying a transient sharing violation.
| Parameters | |
tmp:pathlib.Path | Staging file holding the encoded entry. |
file:pathlib.Path | Destination cache file. |
| Returns | |
None | No return value. |
| Raises | |
OSError | If the rename keeps failing after the last attempt. |
Remove file, ignoring missing-file errors.
| Parameters | |
file:pathlib.Path | File to remove. |
| Returns | |
int | One when a file was removed, otherwise zero. |
Publish a cache entry while its file lock is held.
| Parameters | |
file:pathlib.Path | Destination cache file. |
entry:dict | Encodable cache entry. |
| Returns | |
None | No return value. |
| Raises | |
OSError | If staging or publishing the entry fails. |
Atomically write entry to file via tmp-then-rename.
| Parameters | |
file:pathlib.Path | Target cache file. |
entry:dict | Serializable cache entry. |
| Returns | |
None | No return value. |
| Raises | |
OSError | If the entry cannot be staged or renamed into place. |
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:str | Cache key. |
value:typing.Any | Value to store. |
ttl:float | None | Optional TTL in seconds. |
| Returns | |
bool | True on success. |
| Raises | |
ValueError | If the key already exists and has not expired. |
Return the cached value for key, or default when absent/expired.
Expired entries are deleted on first read (lazy eviction).
| Parameters | |
key:str | Cache key. |
default:typing.Any | Value returned when the key is not found or has expired. |
| Returns | |
typing.Any | Stored value or default. |
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.Any | Returned for each missing/expired key. |
| Returns | |
list[typing.Any] | Cached values in key order, using the supplied default for misses. |
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 | None | Shared TTL applied to every pair. |
| Returns | |
bool | Always True. |
Replace an existing live key without recreating a deleted entry.
| Parameters | |
key:str | Existing cache key. |
value:typing.Any | Replacement value. |
ttl:float | None | Replacement lifetime in seconds. |
| Returns | |
bool | Whether the entry was replaced atomically. |
Store value under key with an optional TTL in seconds.
| Parameters | |
key:str | Cache key. |
value:typing.Any | JSON-serializable value to cache. |
ttl:float | None | Time-to-live in seconds. None means no expiry. |
| Returns | |
bool | Always True. |
Return the canonical directory used to identify cache locks.
| Returns | |
pathlib.Path | Absolute directory shared by backends storing the same files. |