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:

GroupContext

begin(section: str) None

Begin a new section. This method is called when a new section is started. It adds the section to the list of options, which effectively makes it the current section. :param section: The name of the section to begin. :type section: str

end(section: str) None

End the current section. This method is called when a section is ended. It removes the section from the list of options, asserting it’s the expected one, and moves to the previous section if any. :param section: The name of the section to end. :type section: str

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

read_str() 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_unicode() 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.

write_unicode(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_none() None

Write a None value into the configuration.

This method writes a None value into the configuration.

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_any() str | bytes

Read a value from the current group as a generic type.

Returns:

The read value.

Return type:

Union[str, bytes]

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_unicode() str | bytes

Read a value from the current group as a generic type.

Returns:

The read value.

Return type:

Union[str, bytes]

read_str() str | bytes

Read a value from the current group as a generic type.

Returns:

The read value.

Return type:

Union[str, bytes]

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)

read_none() str | bytes

Read a value from the current group as a generic type.

Returns:

The read value.

Return type:

Union[str, bytes]

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_none() None

Write a None value to the HDF5 file as an attribute.

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