qrunch.storage.persisters

Contains Persisters.

Functions

to_overwriting_policy_enum(value)

Coerce literal to OverwritingPolicy.

Classes

FilePersister

Class to handle reading and writing serialized byte data to a file.

OverwritingPolicy

Enum defining how to handle existing cube files.
class FilePersister

Bases: PersisterProtocol

Class to handle reading and writing serialized byte data to a file.

__init__(directory: Path | None, extension: str = '.qdk', overwriting_policy: OverwritingPolicy = OverwritingPolicy.RENAME, padding_width: int = 3) → None

Initiate FilePersister.

Parameters:

  • directory (Path | None) – Path to the directory where data should be written.

  • extension (str) – The file extension to use (default is “.qdk”).

  • overwriting_policy (OverwritingPolicy) – Policy to handle existing files.

  • padding_width (int) – The width of the padding. 3 correspond to 001-style padding .

Return type:

None

file_path(name: str) → Path

Create file path by appending the extension.

Parameters:

name (str) – The base name of the data file (without extension).

Return type:

Path

has_data(key: str) → bool

Check if the file exists and contains data.

Parameters:

key (str) – The key under which the data is stored.

Return type:

bool

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

Check if the file exists and contains data.

Parameters:

  • key (str) – The key under which the data is stored.

  • unique_id (str) – The unique id of describing the data to write.

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 unique_ids for the data stored under the given key for which metadata can be loaded.

Parameters:

key (str) – The key for which to find the stored data.

Returns:

The list of unique ids found for the key.

Return type:

list[str]

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

Read serialized byte data from a file.

Parameters:

  • key (str) – The key under which the data is stored.

  • unique_id (str) – The unique id of describing the data to write.

Raises:

  • FileNotFoundError – If the file does not exist.

  • ValueError – If the file is empty.

  • IOError – If the file is not readable.

Return type:

list[bytes]

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

Write serialized byte data to a file.

Parameters:

  • key (str) – The key under which the data is stored.

  • unique_id (str) – The unique id of describing the data to write.

  • serialized_data (bytes) – Serialized byte data to write.

Raises:

IOError – If the file is not writable.

Return type:

None

class OverwritingPolicy

Bases: Enum

Enum defining how to handle existing cube files.

ERROR = 'error'
IGNORE = 'ignore'
OVERWRITE = 'overwrite'
RENAME = 'rename'
to_overwriting_policy_enum(value: Literal['overwrite', 'error', 'rename', 'ignore'] | OverwritingPolicy) → OverwritingPolicy

Coerce literal to OverwritingPolicy.

Parameters:

value (Literal['overwrite', 'error', 'rename', 'ignore'] | ~qrunch.storage.persisters.OverwritingPolicy) – Either an enum member or its underlying value string.

Raises:

ValueError – If value is a string and does not match any NoisySimulators member.

Return type:

OverwritingPolicy