Data set serialization and deserialization¶
The guidata.dataset.io
package provides the core features for data set
serialization and deserialization.
Base classes for I/O handlers¶
Base classes for writing custom readers and writers:
- class guidata.dataset.io.GroupContext(handler: BaseIOHandler, group_name: str)¶
Group context manager object.
This class provides a context manager for managing a group within a handler.
- Parameters:
handler (BaseIOHandler) – The handler object. It should be an instance of a subclass of BaseIOHandler.
group_name (str) – The group name. Represents the name of the group in the context.
- class guidata.dataset.io.BaseIOHandler¶
Base I/O Handler with group context manager. This class serves as the base class for I/O handlers. It provides methods for managing sections of a file, referred to as “groups”, as well as context management for these groups.
- group(group_name: str) GroupContext ¶
Enter a group and return a context manager to be used with the with statement. :param group_name: The name of the group to enter. :type group_name: str
- Returns:
A context manager for the group.
- Return type:
- class guidata.dataset.io.WriterMixin¶
Mixin class providing the write() method. This mixin class is intended to be used with classes that need to write different types of values.
- write(val: Any, group_name: str | None = None) None ¶
Write a value depending on its type, optionally within a named group. :param val: The value to be written. :type val: Any :param group_name: The name of the group. If provided, the group :type group_name: Optional[str] :param context will be used for writing the value.:
Configuration files (.ini)¶
Reader and writer for the serialization of data sets into .ini files:
- class guidata.dataset.io.INIReader(conf: Any, section: str, option: str)¶
User configuration reader.
This class extends the INIHandler to provide methods for reading different types of values from the user configuration.
- read_any() Any ¶
Read any value from the configuration.
This method reads a value from the configuration located by an option path, formed by joining all the current options.
- Returns:
The value read from the configuration.
- Return type:
Any
- read_bool() Any ¶
Read any value from the configuration.
This method reads a value from the configuration located by an option path, formed by joining all the current options.
- Returns:
The value read from the configuration.
- Return type:
Any
- read_int() Any ¶
Read any value from the configuration.
This method reads a value from the configuration located by an option path, formed by joining all the current options.
- Returns:
The value read from the configuration.
- Return type:
Any
- read_float() Any ¶
Read any value from the configuration.
This method reads a value from the configuration located by an option path, formed by joining all the current options.
- Returns:
The value read from the configuration.
- Return type:
Any
- read_array() Any ¶
Read any value from the configuration.
This method reads a value from the configuration located by an option path, formed by joining all the current options.
- Returns:
The value read from the configuration.
- Return type:
Any
- read_sequence() Any ¶
Read any value from the configuration.
This method reads a value from the configuration located by an option path, formed by joining all the current options.
- Returns:
The value read from the configuration.
- Return type:
Any
- read_none() Any ¶
Read any value from the configuration.
This method reads a value from the configuration located by an option path, formed by joining all the current options.
- Returns:
The value read from the configuration.
- Return type:
Any
- class guidata.dataset.io.INIWriter(conf: Any, section: str, option: str)¶
User configuration writer.
This class extends INIHandler and WriterMixin to provide methods for writing different types of values into the user configuration.
- write_any(val: Any) None ¶
Write any value into the configuration.
This method is used to write a value of any type into the configuration. It creates an option path by joining all the current options and writes the value into this path.
- Parameters:
val (Any) – The value to be written.
- write_bool(val: Any) None ¶
Write any value into the configuration.
This method is used to write a value of any type into the configuration. It creates an option path by joining all the current options and writes the value into this path.
- Parameters:
val (Any) – The value to be written.
- write_int(val: Any) None ¶
Write any value into the configuration.
This method is used to write a value of any type into the configuration. It creates an option path by joining all the current options and writes the value into this path.
- Parameters:
val (Any) – The value to be written.
- write_float(val: Any) None ¶
Write any value into the configuration.
This method is used to write a value of any type into the configuration. It creates an option path by joining all the current options and writes the value into this path.
- Parameters:
val (Any) – The value to be written.
- write_array(val: Any) None ¶
Write any value into the configuration.
This method is used to write a value of any type into the configuration. It creates an option path by joining all the current options and writes the value into this path.
- Parameters:
val (Any) – The value to be written.
- write_sequence(val: Any) None ¶
Write any value into the configuration.
This method is used to write a value of any type into the configuration. It creates an option path by joining all the current options and writes the value into this path.
- Parameters:
val (Any) – The value to be written.
- write_str(val: Any) None ¶
Write any value into the configuration.
This method is used to write a value of any type into the configuration. It creates an option path by joining all the current options and writes the value into this path.
- Parameters:
val (Any) – The value to be written.
JSON files (.json)¶
Reader and writer for the serialization of data sets into .json files:
- class guidata.dataset.io.JSONReader(fname_or_jsontext)¶
Class handling JSON deserialization
- Parameters:
fname_or_jsontext – JSON filename or JSON text
- read(group_name=None, func=None, instance=None)¶
Read value within current group or group_name.
Optional argument instance is an object which implements the DataSet-like deserialize method.
- read_any()¶
Read any value type
- read_object_list(group_name, klass, progress_callback=None)¶
Read object sequence in group. Objects must implement the DataSet-like deserialize method. klass is the object class which constructor requires no argument.
progress_callback: if not None, this function is called with an integer argument (progress: 0 –> 100). Function returns the cancel state (True: progress dialog has been canceled, False otherwise)
- read_unicode()¶
Read any value type
- read_sequence()¶
Read any value type
- read_float()¶
Read any value type
- read_int()¶
Read any value type
- read_str()¶
Read any value type
- read_bool()¶
Read any value type
- read_array()¶
Read any value type
- class guidata.dataset.io.JSONWriter(filename=None)¶
Class handling JSON serialization
- write_any(val)¶
Write any value type
- write_none()¶
Write None
- write_str(val)¶
Write any value type
- write_sequence(val)¶
Write any value type
- write_unicode(val)¶
Write any value type
- write_bool(val)¶
Write any value type
- write_int(val)¶
Write any value type
- write_float(val)¶
Write any value type
- write_array(val)¶
Write any value type
- write_object_list(seq, group_name)¶
Write object sequence in group. Objects must implement the DataSet-like serialize method
HDF5 files (.h5)¶
Reader and writer for the serialization of data sets into .h5 files:
- class guidata.dataset.io.HDF5Reader(filename: str)¶
Reader for HDF5 files. Inherits from HDF5Handler.
- Parameters:
filename (str) – The name of the HDF5 file.
- read(group_name: str | None = None, func: Callable[[], Any] | None = None, instance: Any | None = None) Any ¶
Read a value from the current group or specified group_name.
- Parameters:
group_name (str) – The name of the group to read from. Defaults to None.
func (Callable[[], Any]) – The function to use for reading the value. Defaults to None.
instance (Any) – An object that implements the DataSet-like deserialize method. Defaults to None.
- Returns:
The read value.
- Return type:
Any
- read_bool() bool | None ¶
Read a boolean value from the current group.
- Returns:
The read boolean value.
- Return type:
Optional[bool]
- read_int() int | None ¶
Read an integer value from the current group.
- Returns:
The read integer value.
- Return type:
Optional[int]
- read_float() float | None ¶
Read a float value from the current group.
- Returns:
The read float value.
- Return type:
Optional[float]
- read_array() ndarray ¶
Read a numpy array from the current group.
- Returns:
The read numpy array.
- Return type:
np.ndarray
- read_sequence() list[Any] ¶
Read a sequence from the current group.
- Returns:
The read sequence.
- Return type:
List[Any]
- read_object_list(group_name: str, klass: type[Any], progress_callback: Callable[[int], bool] | None = None) list[Any] ¶
Read an object sequence from a group.
Objects must implement the DataSet-like deserialize method. klass is the object class which constructor requires no argument.
progress_callback: if not None, this function is called with an integer argument (progress: 0 –> 100). Function returns the cancel state (True: progress dialog has been canceled, False otherwise)
- class guidata.dataset.io.HDF5Writer(filename: str)¶
Writer for HDF5 files. Inherits from HDF5Handler and WriterMixin.
- Parameters:
filename (str) – The name of the HDF5 file.
- write_any(val: Any) None ¶
Write the value to the HDF5 file as an attribute.
- Parameters:
val (Any) – The value to write.
- Returns:
None
- write_int(val: Any) None ¶
Write the value to the HDF5 file as an attribute.
- Parameters:
val (Any) – The value to write.
- Returns:
None
- write_float(val: Any) None ¶
Write the value to the HDF5 file as an attribute.
- Parameters:
val (Any) – The value to write.
- Returns:
None
- write_bool(val: bool) None ¶
Write the boolean value to the HDF5 file as an attribute.
- Parameters:
val (bool) – The boolean value to write.
- Returns:
None
- write_str(val: Any) None ¶
Write the value to the HDF5 file as an attribute.
- Parameters:
val (Any) – The value to write.
- Returns:
None
- write_unicode(val: Any) None ¶
Write the value to the HDF5 file as an attribute.
- Parameters:
val (Any) – The value to write.
- Returns:
None
- write_array(val: ndarray) None ¶
Write the numpy array value to the HDF5 file.
- Parameters:
val (np.ndarray) – The numpy array value to write.
- Returns:
None
- write_sequence(val: Any) None ¶
Write the value to the HDF5 file as an attribute.
- Parameters:
val (Any) – The value to write.
- Returns:
None
- write_object_list(seq: Sequence[Any] | None, group_name: str) None ¶
Write an object sequence to the HDF5 file in a group. Objects must implement the DataSet-like serialize method.
- Parameters:
seq (Sequence[Any]) – The object sequence to write. Defaults to None.
group_name (str) – The name of the group in which to write the objects.
- Returns:
None