src.fairreckitlib.core.io.io_utility

  1"""This module contains IO utility functions that connect with external packages.
  2
  3Functions:
  4
  5    load_array_from_hdf5: load array data from hdf5 file.
  6    load_json: load dictionary from json file.
  7    load_yml: load dictionary from yml file.
  8    save_array_to_hdf5: save array data to hdf5 file.
  9    save_json: save dictionary to json file.
 10    save_yml: save dictionary to yml file.
 11
 12This program has been developed by students from the bachelor Computer Science at
 13Utrecht University within the Software Project course.
 14© Copyright Utrecht University (Department of Information and Computing Sciences)
 15"""
 16
 17import json
 18from typing import Any, Dict, List, Union
 19
 20import h5py
 21import numpy as np
 22import yaml
 23
 24
 25def load_array_from_hdf5(file_path: str, array_name: str) -> np.array:
 26    """Load a single array from a HDF5 binary data file.
 27
 28    This function raises a FileNotFoundError when the specified file does not exist.
 29    Counterpart of the save_array_to_hdf5 function.
 30
 31    Args:
 32        file_path: path to where the HDF5 file is stored.
 33        array_name: name of the array to retrieve from the file.
 34
 35    Returns:
 36        the array data from the file.
 37    """
 38    with h5py.File(file_path, "r") as file:
 39        return np.array(file.get(array_name))
 40
 41
 42def load_json(file_path: str, encoding: str='utf-8') -> Union[Dict[str, Any], List]:
 43    """Load a json file.
 44
 45    This function raises a FileNotFoundError when the specified file does not exist.
 46    Counterpart of the save_json function.
 47
 48    Args:
 49        file_path: path to where the json file is stored.
 50        encoding: the encoding to use for reading the file contents.
 51
 52    Returns:
 53        the resulting dictionary.
 54    """
 55    with open(file_path, encoding=encoding) as out_file:
 56        return json.load(out_file)
 57
 58
 59def load_yml(file_path: str, encoding: str='utf-8') -> Union[Dict[str, Any], List]:
 60    """Load a yml file.
 61
 62    This function raises a FileNotFoundError when the specified file does not exist.
 63    Counterpart of the save_yml function.
 64
 65    Args:
 66        file_path: path to where the yml file is stored.
 67        encoding: the encoding to use for reading the file contents.
 68
 69    Returns:
 70        the resulting dictionary.
 71    """
 72    with open(file_path, 'r', encoding=encoding) as yml_file:
 73        return yaml.safe_load(yml_file)
 74
 75
 76def save_array_to_hdf5(file_path: str, arr: List[Any], array_name: str) -> None:
 77    """Save a single array to a HDF5 binary data file.
 78
 79    Counterpart of the load_array_from_hdf5 function.
 80
 81    Args:
 82        file_path: path to where the HDF5 file will be stored.
 83        arr: the source array to save in the file.
 84        array_name: name of the array to save in the file.
 85    """
 86    with h5py.File(file_path, "w") as file:
 87        file.create_dataset(array_name, data=arr)
 88
 89
 90def save_json(file_path: str, data: Union[Dict[str, Any], List],
 91              *, encoding: str='utf-8', indent=None) -> None:
 92    """Save a json file.
 93
 94    Counterpart of the load_json function.
 95
 96    Args:
 97        file_path: path to where the json file will be stored.
 98        data: the source dictionary to save in the file.
 99        encoding: the encoding to use for writing the file contents.
100        indent: the indent level for pretty printing JSON array elements and object members.
101    """
102    with open(file_path, 'w', encoding=encoding) as file:
103        json.dump(data, file, indent=indent)
104
105
106def save_yml(file_path: str, data: Union[Dict[str, Any], List], *, encoding: str='utf-8') -> None:
107    """Save a yml file.
108
109    Counterpart of the load_yml function.
110
111    Args:
112        file_path: path to where the yml file will be stored.
113        data: the source dictionary to save in the file.
114        encoding: the encoding to use for writing the file contents.
115    """
116    with open(file_path, 'w', encoding=encoding) as yml_file:
117        yaml.dump(data, yml_file)