ssapy_toolkit.io.dict_to_from_hdf5

Utilities for saving/loading nested Python dictionaries to/from HDF5.

Public API:

save_dict_to_hdf5(filename, data, …) load_dict_from_hdf5(filename, keys=None)

Functions

load_dict_from_hdf5(filename[, keys])

Load a dictionary previously stored with save_dict_to_hdf5(filename, data, ...).

save_dict_to_hdf5(filename, data[, mode, ...])

Save a (possibly nested) Python dictionary to an HDF5 file.
ssapy_toolkit.io.dict_to_from_hdf5.load_dict_from_hdf5(filename: str, keys: Set[str] | None = None) → dict[source]

Load a dictionary previously stored with save_dict_to_hdf5(filename, data, …).

Parameters:

  • filename (str) – Path to the HDF5 file.

  • keys (set of str, optional) – If provided, only the specified top-level keys are loaded from disk. All other keys are ignored, avoiding unnecessary decompression of large datasets. If None (default), all keys are loaded.

  • Behavior –

    • Groups marked with __is_sequence__=True are reconstructed as lists, even if empty.

    • Groups marked with __is_sequence__=False are reconstructed as dicts, even if empty.

    • Groups without the attribute:

      • if keys are 0..n-1 as strings, treated as lists

      • otherwise, treated as dicts.

    • Supported special types: astropy.time.Time, datetime.*, bytes, pickled objects.

ssapy_toolkit.io.dict_to_from_hdf5.save_dict_to_hdf5(filename: str, data: Mapping[str, Any], mode: str = 'w', *, pickle_objects: bool = True, compression: str | None = 'gzip', compression_opts: int | None = 4) → None[source]

Save a (possibly nested) Python dictionary to an HDF5 file.

Signature:

save_dict_to_hdf5(filename, data, …)

Supported types:

  • dict -> HDF5 group

  • list/tuple of numeric scalars -> HDF5 dataset (auto-converted to numpy array)

  • list/tuple of mixed/non-numeric -> HDF5 group with numeric keys (“0”, “1”, …)

  • numpy arrays -> datasets (with compression, if requested)

  • scalars: int/float/bool, numpy scalar types -> scalar datasets (no compression)

  • str -> variable-length UTF-8 datasets

  • bytes/bytearray/memoryview -> bytes datasets

  • datetime.datetime/date/time -> stored as ISO strings

  • astropy.time.Time -> stored as (mjd, scale, format, meta)

  • other objects -> pickled if pickle_objects=True

Notes:

  • Flat numeric lists/tuples are automatically converted to numpy arrays to avoid the “thousands of groups” explosion that occurs when storing large lists element-by-element.