Data serialization and deserialization¶

The guidata.io package provides the core features for data (guidata.dataset.DataSet or other objects) serialization and deserialization.

Base classes for I/O handlers¶

Base classes for writing custom readers and writers:

BaseIOHandler
WriterMixin

class guidata.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.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.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:

INIReader
INIWriter

class guidata.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_dict() → 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.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_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_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_dict(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:

JSONReader
JSONWriter

class guidata.io.JSONReader(fname_or_jsontext: str)¶

Class handling JSON deserialization

Parameters:: fname_or_jsontext – JSON filename or JSON text

read(group_name: str | None = None, func: ~collections.abc.Callable[[], ~typing.Any] | None = None, instance: ~typing.Any | None = None, default: ~typing.Any | ~guidata.io.jsonfmt.NoDefault = <class 'guidata.io.jsonfmt.NoDefault'>) → Any¶

Read a value from the current group or specified group_name.

Parameters:

group_name – The name of the group to read from. Defaults to None.
func – The function to use for reading the value. Defaults to None.
instance – An object that implements the DataSet-like deserialize method. Defaults to None.
default – The default value to return if the value is not found. Defaults to NoDefault (no default value: raises an exception if the value is not found).

Returns:

The read value.

read_any() → Any¶: Read any value type

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.

Parameters:

group_name – The name of the group to read the object sequence from.
klass – The object class which constructor requires no argument.
progress_callback – A function to call with an integer argument (progress: 0 –> 100). The function returns the cancel state (True: progress dialog has been canceled, False otherwise).

read_unicode() → Any¶: Read any value type

read_sequence() → Any¶: Read any value type

read_dict() → Any¶: Read any value type

read_float() → Any¶: Read any value type

read_int() → Any¶: Read any value type

read_str() → Any¶: Read any value type

read_bool() → Any¶: Read any value type

read_array() → Any¶: Read any value type

class guidata.io.JSONWriter(filename: str | None = None)¶

Class handling JSON serialization

write_any(val) → None¶: Write any value type

write_none() → None¶: Write None

write_sequence(val) → None¶: Write any value type

write_dict(val) → None¶: Write any value type

write_str(val) → None¶: Write any value type

write_bool(val) → None¶: Write any value type

write_int(val) → None¶: Write any value type

write_float(val) → None¶: Write any value type

write_array(val) → None¶: Write any value type

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 – The object sequence to write. Defaults to None.
group_name – The name of the group in which to write the objects.

HDF5 files (.h5)¶

Reader and writer for the serialization of data sets into .h5 files:

HDF5Reader
HDF5Writer

class guidata.io.HDF5Reader(filename: str)¶

Reader for HDF5 files. Inherits from HDF5Handler.

Parameters:: filename – The name of the HDF5 file.

read(group_name: str | None = None, func: ~collections.abc.Callable[[], ~typing.Any] | None = None, instance: ~typing.Any | None = None, default: ~typing.Any | ~guidata.io.h5fmt.NoDefault = <class 'guidata.io.h5fmt.NoDefault'>) → Any¶

Read a value from the current group or specified group_name.

Parameters:

group_name – The name of the group to read from. Defaults to None.
func – The function to use for reading the value. Defaults to None.
instance – An object that implements the DataSet-like deserialize method. Defaults to None.
default – The default value to return if the value is not found. Defaults to NoDefault (no default value: raises an exception if the value is not found).

Returns:

The read value.

read_any() → str | bytes¶

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

Returns:: The read value.

read_bool() → bool | None¶

Read a boolean value from the current group.

Returns:: The read boolean value, or None if the value is not found.

read_int() → int | None¶

Read an integer value from the current group.

Returns:: The read integer value, or None if the value is not found.

read_float() → float | None¶

Read a float value from the current group.

Returns:: The read float value, or None if the value is not found.

read_unicode() → str | bytes¶

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

Returns:: The read value.

read_str() → str | bytes¶

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

Returns:: The read value.

read_array() → ndarray¶

Read a numpy array from the current group.

Returns:: The read numpy array.

read_sequence() → list[Any]¶

Read a sequence from the current group.

Returns:: The read sequence.

read_dict() → dict[str, Any]¶

Read dictionary from h5 file

Returns:: Dictionary read from h5 file

read_list() → list[Any]¶

Read a list from the current group.

Returns:: The read list.

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.

Parameters:

group_name – The name of the group to read the object sequence from.
klass – The object class which constructor requires no argument.
progress_callback – A function to call with an integer argument (progress: 0 –> 100). The 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.

class guidata.io.HDF5Writer(filename: str)¶

Writer for HDF5 files. Inherits from HDF5Handler and WriterMixin.

Parameters:: filename – The name of the HDF5 file.

write(val: Any, group_name: str | None = None) → None¶

Write a value depending on its type, optionally within a named group.

Parameters:

val – The value to be written.
group_name – The name of the group. If provided, the group context will be used for writing the value.

write_any(val: Any) → None¶

Write the value to the HDF5 file as an attribute.

Parameters:: val – The value to write.

write_str(val: Any) → None¶

Write the value to the HDF5 file as an attribute.

Parameters:: val – The value to write.

write_list(val: Any) → None¶

Write the value to the HDF5 file as an attribute.

Parameters:: val – The value to write.

write_int(val: Any) → None¶

Write the value to the HDF5 file as an attribute.

Parameters:: val – The value to write.

write_float(val: Any) → None¶

Write the value to the HDF5 file as an attribute.

Parameters:: val – The value to write.

write_bool(val: bool) → None¶

Write the boolean value to the HDF5 file as an attribute.

Parameters:: val – The boolean value to write.

write_array(val: ndarray) → None¶

Write the numpy array value to the HDF5 file.

Parameters:: val – The numpy array value to write.

write_none() → None¶: Write a None value to the HDF5 file as an attribute.

write_sequence(val: list | tuple) → None¶

Write the list or tuple value to the HDF5 file as an attribute.

Parameters:: write. (The value to)

write_dict(val: dict[str, Any]) → None¶

Write dictionary to h5 file

Parameters:: val – dictionary to write

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 – The object sequence to write. Defaults to None.
group_name – The name of the group in which to write the objects.