# 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 | int | float | date | datetime | list[Any] | ndarray

    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 | int | float | date | datetime | list[Any] | ndarray

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

    Returns:

      The read value.

  read_str() → str | bytes | int | float | date | datetime | list[Any] | ndarray

    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 | int | float | date | datetime | list[Any] | ndarray

    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_datetime(val: datetime) → None

    Write a datetime value to the HDF5 file with type metadata.

    Parameters:

      val – The datetime value to write.

  write_date(val: date) → None

    Write a date value to the HDF5 file with type metadata.

    Parameters:

      val – The date 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.