qrunch.storage.storage_protocols

Module containing protocols needed for storage.

Classes

KeyUniqueId	The (key, unique_id) pair.
LoadPolicy	Enum for defining policies for behavior when loading.
PersisterProtocol	Protocol defining a shared interface for persisters.
SerializerProtocol	Protocol defining the interface for dataclass serialization.

class KeyUniqueId

Bases: object

The (key, unique_id) pair. Immutable identifier for persisted data.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

• key – The key associated with the data.

• unique_id – The unique identifier for the data.

__init__(*, key: str, unique_id: str) → None

Parameters:

• key (str)

• unique_id (str)

Return type:

None

key: str

unique_id: str

class LoadPolicy

Bases: Enum

Enum for defining policies for behavior when loading.

EXPECTED = 'expected'

The data is expected to be present; raise an error if not.

FALLBACK = 'fallback'

Fallback to calculating the result.

OFF = 'off'

Do not load.

RAISE_ON_HASH_COLLISION = 'raise_on_hash_collision'

Raise an error if data for key unique id exists, but metadata differs.

class PersisterProtocol

Bases: Protocol

Protocol defining a shared interface for persisters.

__init__(*args, **kwargs)

has_data(key: str) → bool

Check if the data associated with name exists and contains data.

Parameters:

key (str)

Return type:

bool

has_matching_data(key: str, unique_id: str) → bool

Check if the data associated with name exists and contains data.

Parameters:

• key (str)

• unique_id (str)

Return type:

bool

key_and_unique_ids() → set[KeyUniqueId]

Enumerate (key, unique_id) pairs discovered from persisted filenames.

Scan the configured directory (or current working directory if unset) and parse stems of files that match the internal naming scheme: _ui__<uid>__eui_<key>[_<n>_].<extension>

Return type:

set[KeyUniqueId]

list_data_for_key(key: str) → list[str]

Return a list of names that include the partial_name substring.

Parameters:

key (str)

Return type:

list[str]

read(key: str, unique_id: str) → list[bytes]

Read serialized byte data.

Parameters:

• key (str)

• unique_id (str)

Return type:

list[bytes]

write(key: str, unique_id: str, serialized_data: bytes) → None

Write serialized byte data.

Parameters:

• key (str)

• unique_id (str)

• serialized_data (bytes)

Return type:

None

class SerializerProtocol

Bases: Protocol

Protocol defining the interface for dataclass serialization.

__init__(*args, **kwargs)

from_bytes(serialized_data: bytes, cls: type[T]) → T

Deserialize bytes back into a dataclass instance of the given type.

Parameters:

• serialized_data (bytes) – Serialized byte data.

• cls (type[T]) – The expected dataclass type.

Return type:

T

to_bytes(instance: Any) → bytes

Serialize a dataclass instance into bytes.

Parameters:

instance (Any) – The dataclass instance to serialize.

Return type:

bytes