# Data sets

## Defining data sets

class guidata.dataset.DataSet(title: str | None = None, comment: str | None = None, icon: str = '', readonly: bool = False, skip_defaults: bool = False)

  Construct a DataSet object is a set of DataItem objects

  Parameters:

    - title (str) – title

    - comment (str) – comment. Text shown on the top of the first data item

    - icon (str) – icon filename as in image search paths

    - readonly (bool) – if True, the DataSet is read-only

    - skip_defaults (bool) – if True, do not set default values for items

  get_items(copy=False) → list[DataItem]

    Returns all the DataItem objects from the DataSet instance. Ignore private items that have a name starting with an underscore (e.g. ‘_private_item = …’)

    Parameters:

      - copy – If True, deepcopy the DataItem list, else return the original.

      - False. (Defaults to)

    Returns:

      _description_

  classmethod create(**kwargs) → AutodocExampleParam1

    Create a new instance of the DataSet class

    Parameters:

      kwargs – keyword arguments to set the DataItem values

    Returns:

      DataSet instance

  get_title() → str

    Return data set title

    Returns:

      title

    Return type:

      str

  set_title(title: str) → None

    Set data set title

    Parameters:

      title (str) – title

  get_comment() → str | None

    Return data set comment

    Returns:

      comment

    Return type:

      str | None

  set_comment(comment: str | None) → None

    Set data set comment

    Parameters:

      comment (str | None) – comment

  get_icon() → str | None

    Return data set icon

    Returns:

      icon

    Return type:

      str | None

  set_icon(icon: str) → None

    Set data set icon

    Parameters:

      icon (str) – icon

  set_defaults() → None

    Set default values

  check() → list[str]

    Check the dataset item values

    Returns:

      list of errors

    Return type:

      list[str]

  text_edit() → None

    Edit data set with text input only

  edit(parent: QWidget | None = None, apply: Callable | None = None, wordwrap: bool = True, size: QSize | tuple[int, int] | None = None, object_name: str | None = None) → int

    Open a dialog box to edit data set

    Parameters:

      - parent – parent widget (default is None, meaning no parent)

      - apply – apply callback (default is None)

      - wordwrap – if True, comment text is wordwrapped

      - size – dialog size (QSize object or integer tuple (width, height))

      - object_name – object name for the dialog (default is None, meaning use class name + “Dialog”)

    Returns:

      Dialog exit code.

  view(parent: QWidget | None = None, wordwrap: bool = True, size: QSize | tuple[int, int] | None = None) → None

    Open a dialog box to view data set

    Parameters:

      - parent – parent widget (default is None, meaning no parent)

      - wordwrap – if True, comment text is wordwrapped

      - size – dialog size (QSize object or integer tuple (width, height))

  to_string(debug: bool | None = False, indent: str | None = None, align: bool | None = False, show_hidden: bool | None = True) → str

    Return readable string representation of the data set If debug is True, add more details on data items

    Parameters:

      - debug (bool) – if True, add more details on data items

      - indent (str) – indentation string (default is None, meaning no indentation)

      - align (bool) – if True, align data items (default is False)

      - show_hidden (bool) – if True, show hidden data items (default is True)

    Returns:

      string representation of the data set

    Return type:

      str

  accept(vis: object) → None

    Helper function that passes the visitor to the accept methods of all the items in this dataset

    Parameters:

      vis (object) – visitor object

  to_html() → str

    Return HTML representation of the dataset.

    Similar to Sigima’s TableResult transpose format with:

    - Title and comment in blue

    - Two-column table: item names (right-aligned) and values (left-aligned)

    - For BoolItem: checkbox in first column with label:text formatting

    Returns:

      HTML representation

  serialize(writer: HDF5Writer | JSONWriter | INIWriter) → None

    Serialize the dataset

    Parameters:

      writer (HDF5Writer | JSONWriter | INIWriter) – writer object

  deserialize(reader: HDF5Reader | JSONReader | INIReader) → None

    Deserialize the dataset

    Parameters:

      reader (HDF5Reader | JSONReader | INIReader) – reader object

  read_config(conf: UserConfig, section: str, option: str) → None

    Read configuration from a UserConfig instance

    Parameters:

      - conf (UserConfig) – UserConfig instance

      - section (str) – section name

      - option (str) – option name

  write_config(conf: UserConfig, section: str, option: str) → None

    Write configuration to a UserConfig instance

    Parameters:

      - conf (UserConfig) – UserConfig instance

      - section (str) – section name

      - option (str) – option name

  classmethod set_global_prop(realm: str, **kwargs) → None

    Set global properties for all data items in the dataset

    Parameters:

      - realm (str) – realm name

      - kwargs (dict) – properties to set

class guidata.dataset.DataSetGroup(datasets: list[DataSet], title: str | None = None, icon: str = '')

  Construct a DataSetGroup object, used to group several datasets together

  Parameters:

    - datasets (list[DataSet]) – list of datasets

    - title (str) – group title (optional)

    - icon (str) – group icon. Default is “” (no icon)

  This class tries to mimics the DataSet interface.

  The GUI should represent it as a notebook with one page for each contained dataset.

  get_title() → str

    Return data set group title

    Returns:

      data set group title

    Return type:

      str

  get_comment() → None

    Return data set group comment –> not implemented (will return None)

    Returns:

      data set group comment

    Return type:

      None

  get_icon() → str | None

    Return data set icon

    Returns:

      data set icon

    Return type:

      str | None

  check() → list[list[str]]

    Check data set group items

    Returns:

      list of errors

    Return type:

      list[list[str]]

  text_edit() → None

    Edit data set with text input only

  edit(parent: QWidget | None = None, apply: Callable | None = None, wordwrap: bool = True, size: QSize | tuple[int, int] | None = None, mode: str | None = None) → int

    Open a dialog box to edit data set

    Parameters:

      - parent – parent widget. Defaults to None.

      - apply – apply callback. Defaults to None.

      - wordwrap – if True, comment text is wordwrapped

      - size – dialog size (default: None)

      - mode – (str): dialog window style to use. Allowed values are “tabs”, “table” and None. Use “tabs” to navigate between datasets with tabs. Use “table” to create a table with one dataset by row (allows dataset editing by double clicking on a row). Defaults to None.

    Returns:

      dialog box return code

    Return type:

      int

  accept(vis: object) → None

    Helper function that passes the visitor to the accept methods of all the items in this dataset

    Parameters:

      vis (object) – visitor

  is_readonly() → bool

    Return True if all datasets in the DataSetGroup are in readonly mode.

    Returns:

      True if all datasets are in readonly, else False

  set_readonly(readonly=True)

    Set all datasets of the dataset group to readonly mode

    Parameters:

      readonly – Readonly flag. Defaults to True.

class guidata.dataset.ActivableDataSet(title: str | None = None, comment: str | None = None, icon: str = '')

  An ActivableDataSet instance must have an “enable” class attribute which will set the active state of the dataset instance (see example in: tests/activable_dataset.py)

  Parameters:

    - title (str) – dataset title (optional)

    - comment (str) – dataset comment (optional)

    - icon (str) – dataset icon. Default is “” (no icon)

  classmethod active_setup() → None

    This class method must be called after the child class definition in order to setup the dataset active state

## Grouping items

class guidata.dataset.BeginGroup(label: str)

  Data item which does not represent anything but a begin flag to define a data set group

  Parameters:

    label (str) – group label

  serialize(instance, writer) → None

    Serialize this item using the writer object

    This is a default implementation that should work for everything but new datatypes

    Parameters:

      - instance (DataSet) – instance of the DataSet

      - writer (HDF5Writer | JSONWriter | INIWriter) – writer object

  deserialize(instance, reader) → None

    Deserialize this item using the reader object

    Default base implementation supposes the reader can detect expected datatype from the stream

    Parameters:

      - instance (Any) – instance of the DataSet

      - reader (HDF5Reader | JSONReader | INIReader) – reader object

class guidata.dataset.EndGroup(label: str)

  Data item which does not represent anything but an end flag to define a data set group

  Parameters:

    label (str) – group label

  serialize(instance, writer) → None

    Serialize this item using the writer object

    This is a default implementation that should work for everything but new datatypes

    Parameters:

      - instance (DataSet) – instance of the DataSet

      - writer (HDF5Writer | JSONWriter | INIWriter) – writer object

  deserialize(instance, reader) → None

    Deserialize this item using the reader object

    Default base implementation supposes the reader can detect expected datatype from the stream

    Parameters:

      - instance (Any) – instance of the DataSet

      - reader (HDF5Reader | JSONReader | INIReader) – reader object

class guidata.dataset.BeginTabGroup(label: str)

  Data item which does not represent anything but a begin flag to define a data set tab group

  Parameters:

    label (str) – group label

class guidata.dataset.EndTabGroup(label: str)

  Data item which does not represent anything but an end flag to define a data set tab group

  Parameters:

    label (str) – group label

class guidata.dataset.SeparatorItem(label: str = '')

  Data item which represents a visual separator between other items

  In textual representation, it appears as a series of dashes. In GUI, it appears as a horizontal gray line.

  Parameters:

    label (str) – optional label for the separator (default: “”)

  get_string_value(instance: DataSet) → str

    Return a formatted string representation of the separator

    Parameters:

      instance (DataSet) – instance of the DataSet

    Returns:

      string representation as a series of dashes

    Return type:

      str

  serialize(instance: DataSet, writer: HDF5Writer | JSONWriter | INIWriter) → None

    Serialize this item using the writer object

    Separators don’t store any data, so this is a no-op.

    Parameters:

      - instance (DataSet) – instance of the DataSet

      - writer (HDF5Writer | JSONWriter | INIWriter) – writer object

  deserialize(instance: DataSet, reader: HDF5Reader | JSONReader | INIReader) → None

    Deserialize this item using the reader object

    Separators don’t store any data, so this is a no-op.

    Parameters:

      - instance (DataSet) – instance of the DataSet

      - reader (HDF5Reader | JSONReader | INIReader) – reader object

  check_value(value: Any, raise_exception: bool = False) → bool

    Check if value is valid for this data item

    Separators don’t store values, so always return True.

    Parameters:

      - value (Any) – value to check

      - raise_exception (bool) – if True, raise an exception if the value is invalid

    Returns:

      True (separators always have valid “values”)

    Return type:

      bool

  from_string(string_value: str) → None

    Transform string into valid data item’s value

    Separators don’t store values, so return None.

    Parameters:

      string_value (str) – string value

    Returns:

      separators don’t have values

    Return type:

      None

  get_value(instance: DataSet) → None

    Return data item’s value

    Separators don’t store values.

    Parameters:

      instance (DataSet) – instance of the DataSet

    Returns:

      separators don’t have values

    Return type:

      None

## Handling item properties

class guidata.dataset.ItemProperty(callable: Callable)

  Base class for item properties

  Parameters:

    callable (Callable) – callable to use to evaluate the value of the property

class guidata.dataset.FormatProp(fmt: str, ignore_error: bool | None = True)

  A Property that returns a string to help custom read-only representation of items

  Parameters:

    - fmt (str) – format string

    - ignore_error (bool) – ignore errors when formatting. Defaults to True.

class guidata.dataset.GetAttrProp(attr: str)

  A property that matches the value of an instance’s attribute

  Parameters:

    attr (str) – attribute to match

  set(instance: DataSet, item: DataItem, value: Any) → None

    Sets the value of the property given an instance, item and value Depending on implementation the value will be stored either on the instance, item or self

    Parameters:

      - instance (DataSet) – instance of the DataSet

      - item (Any) – item to set the value of

      - value (Any) – value to set

class guidata.dataset.ValueProp(value: Any)

  A property that retrieves a value stored elsewhere

  Parameters:

    value (Any) – value to store

  set(instance: DataSet, item: DataItem, value: Any) → None

    Sets the value of the property given an instance, item and value

    Parameters:

      - instance (DataSet) – instance of the DataSet

      - item (Any) – item to set the value of

      - value (Any) – value to set

class guidata.dataset.NotProp(prop: ItemProperty)

  Not property

  Parameters:

    prop (ItemProperty) – property to negate

  set(instance: DataSet, item: DataItem, value: Any) → None

    Sets the value of the property given an instance, item and value

    Parameters:

      - instance (DataSet) – instance of the DataSet

      - item (Any) – item to set the value of

      - value (Any) – value to set

class guidata.dataset.FuncProp(prop: ItemProperty, func: Callable, invfunc: Callable | None = None)

  An ‘operator property’

  Parameters:

    - prop (ItemProperty) – property to apply function to

    - func (function) – function to apply

    - invfunc (function) – inverse function (default: func)

  set(instance: DataSet, item: DataItem, value: Any) → None

    Sets the value of the property given an instance, item and value

    Parameters:

      - instance (DataSet) – instance of the DataSet

      - item (Any) – item to set the value of

      - value (Any) – value to set

class guidata.dataset.FuncPropMulti(props: list[ItemProperty], func: Callable, invfunc: Callable | None = None)

  An ‘operator property’ for multiple properties

  Parameters:

    - props (list[ItemProperty]) – properties to apply function to

    - func (function) – function to apply

    - invfunc (function) – inverse function (default: func)

  set(instance: DataSet, item: DataItem, value: Any) → None

    Sets the value of the property given an instance, item and value

    Parameters:

      - instance (DataSet) – instance of the DataSet

      - item (Any) – item to set the value of

      - value (Any) – value to set