Skip to content
hikari-risa hikari-risa

risa.store.protocol

The contract a state store implements.

DEFAULT_LOCK_TIMEOUT module-attribute 

DEFAULT_LOCK_TIMEOUT: Final[float] = 10.0

Seconds Store.lock() waits for a key before it raises LockTimeoutError.

Store

Bases: Protocol

Where risa keeps the state of InStore views.

Implement it to keep state somewhere risa ships no store for, and check the implementation with risa.store.testing.verify_store. A missing or expired entry is never an error: it reads as None. Apart from LockTimeoutError from lock, any exception a method raises means the backend could not be reached, and risa reports it as StoreUnavailableError.

delete async 

delete(key: str) -> None

Remove the entry under key, if there is one.

Parameters:

  • key (str) –

    The entry's key, as for get_versioned.

get_versioned async 

get_versioned(key: str) -> VersionedEntry | None

Return the data and version under key, or None if there is none or it has expired.

Parameters:

  • key (str) –

    The entry's key, an opaque string. risa's are {prefix}:1:{hex}, and it passes the one key of a view's record to every method, lock included.

Returns:

  • VersionedEntry | None –

    The bytes last written with their version, or None.

lock 

lock(
    key: str, *, timeout: float = DEFAULT_LOCK_TIMEOUT
) -> AbstractAsyncContextManager[None]

Hold key exclusively while the returned context manager is entered.

risa holds it for the length of a click, so clicks on one view run one after another. A store that several processes share should exclude all of them; when such a lock lapses, the version check of put_if_version still decides whose write lands.

Parameters:

  • key (str) –

    The key to hold; risa passes the key of the record it is about to read and write. Holding one key does not make another wait, and the key needs no entry.

  • timeout (float, default: DEFAULT_LOCK_TIMEOUT ) –

    Seconds to wait for the lock, fractions included, before raising LockTimeoutError.

Raises:

put async 

put(key: str, value: bytes, *, ttl: float | None) -> None

Write value under key, whether or not an entry exists.

The entry's version changes. ttl is the entry's lifetime in seconds from now, and None clears any expiry, so the entry lives until it is deleted.

Parameters:

  • key (str) –

    The entry's key, as for get_versioned.

  • value (bytes) –

    The bytes to keep. get_versioned returns them unchanged, whatever they hold, empty included.

  • ttl (float | None) –

    Seconds the entry lives, counted from this write and fractions included. None gives it no expiry, which also clears the expiry an earlier write set.

put_if_version async 

put_if_version(
    key: str, value: bytes, *, expected: int, ttl: float | None
) -> int | None

Write value under key only if the entry is still at version expected.

The compare and the write are one atomic step: of several writers expecting the same version, exactly one succeeds. ttl works as in put.

Parameters:

  • key (str) –

    The entry's key, as for get_versioned.

  • value (bytes) –

    The bytes to keep if the write goes through.

  • expected (int) –

    A version from get_versioned, or returned by an earlier put_if_version. The write goes through only while the entry is still at exactly that version. Versions compare only within one entry's life: a store may restart them once the entry is deleted or has expired.

  • ttl (float | None) –

    Seconds the entry lives from this write, as in put. None gives it no expiry.

Returns:

  • int | None –

    The entry's new version, or None if the entry is missing, expired, or at a different version, in which case nothing was written.

touch async 

touch(key: str, *, ttl: float) -> None

Restart the lifetime of the entry under key, which now expires ttl seconds from now.

The data and version stay as they are, and a missing key stays missing.

Parameters:

  • key (str) –

    The entry's key, as for get_versioned.

  • ttl (float) –

    Seconds the entry now lives, counted from this call and replacing the expiry it had.

VersionedEntry 

VersionedEntry(data: bytes, version: int)

Bases: Struct

An entry as a store holds it.

Attributes:

  • data (bytes) –

    The bytes last written.

  • version (int) –

    The version of that write. It changes with every write to the entry.