# Data items

## Base class

class guidata.dataset.DataItem(label: str, default: Any | None = None, help: str | None = '', check: bool | None = True, allow_none: bool = False)

  DataSet data item

  Parameters:

    - label (str) – item label

    - default (Any) – default value

    - help (str) – text displayed on data item’s tooltip

    - check (bool) – check value (default: True)

    - allow_none (bool) – if True, None values are allowed regardless of the expected type (default: False)

## Numeric items

class guidata.dataset.FloatItem(label: str, default: float | None = None, min: float | None = None, max: float | None = None, nonzero: bool | None = None, unit: str = '', step: float = 0.1, slider: bool = False, help: str = '', check: bool = True, allow_none: bool = False)

  Construct a float data item

  Parameters:

    - label – item name

    - default – default value (optional)

    - min – minimum value (optional)

    - max – maximum value (optional)

    - nonzero – if True, zero is not a valid value (optional)

    - unit – physical unit (optional)

    - even – if True, even values are valid, if False, odd values are valid if None (default), ignored (optional)

    - slider – if True, shows a slider widget right after the line edit widget (default is False)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=False)

  type

    alias of `float`

  get_value_from_reader(reader: HDF5Reader | JSONReader | INIReader) → float

    Reads value from the reader object, inside the try…except statement defined in the base item deserialize method

class guidata.dataset.IntItem(label: str, default: int | None = None, min: int | None = None, max: int | None = None, nonzero: bool | None = None, unit: str = '', even: bool | None = None, slider: bool = False, help: str = '', check: bool = True, allow_none: bool = False)

  Construct an integer data item

  Parameters:

    - label – item name

    - default – default value (optional)

    - min – minimum value (optional)

    - max – maximum value (optional)

    - nonzero – if True, zero is not a valid value (optional)

    - unit – physical unit (optional)

    - even – if True, even values are valid, if False, odd values are valid if None (default), ignored (optional)

    - slider – if True, shows a slider widget right after the line edit widget (default is False)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=False)

  type

    alias of `int`

  get_auto_help(instance: DataSet) → str

    Override DataItem method

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

    Override DataItem method

  get_value_from_reader(reader: HDF5Reader | JSONReader | INIReader) → Any

    Reads value from the reader object, inside the try…except statement defined in the base item deserialize method

class guidata.dataset.FloatArrayItem(label: str, default: NDArray | None = None, help: str = '', format: str = '%.3f', transpose: bool = False, minmax: str = 'all', check: bool = True, variable_size=False, allow_none: bool = True, check_callback: Callable[[np.ndarray, bool], bool] | None = None)

  Construct a float array data item

  Parameters:

    - label – item name

    - default – default value (optional)

    - help – text shown in tooltip (optional)

    - format – formatting string (example: ‘%.3f’) (optional)

    - transpose – transpose matrix (display only)

    - large – view all float of the array

    - minmax – “all” (default), “columns”, “rows”

    - check – if False, value is not checked (optional, default=True)

    - variable_size – if True, allows to add/remove row/columns on all axis

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=True)

    - check_callback – additional callback to check the value (function of two arguments (value, raise_exception) returning a boolean, where value is the value to check and raise_exception is a boolean indicating whether to raise an exception on invalid value)

  type

    alias of `ndarray`

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

    Override DataItem method

  format_string(instance: DataSet, value: Any, fmt: str, func: Callable) → str

    Override DataItem method

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

    Serialize this item

  get_value_from_reader(reader: HDF5Reader | JSONReader | INIReader) → Any

    Reads value from the reader object, inside the try…except statement defined in the base item deserialize method

## Text items

class guidata.dataset.StringItem(label: str, default: str | None = None, notempty: bool | None = None, wordwrap: bool = False, password: bool = False, regexp: str | None = None, help: str = '', check: bool = True, allow_none: bool = False, readonly: bool = False)

  Construct a string data item

  Parameters:

    - label – item name

    - default – default value (optional)

    - notempty – if True, empty string is not a valid value (optional)

    - wordwrap – toggle word wrapping (optional)

    - password – if True, text is hidden (optional)

    - regexp – regular expression for checking value (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (ineffective for strings)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=False)

    - readonly – if True, the item is read-only (optional, default=False)

  type

    alias of `str`

  get_auto_help(instance: DataSet) → str

    Override DataItem method

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

    Override DataItem method

  from_string(value: str) → str

    Override DataItem method

  get_string_value(instance: DataSet) → str

    Override DataItem method

  get_value_from_reader(reader: HDF5Reader | JSONReader | INIReader) → Any

    Reads value from the reader object, inside the try…except statement defined in the base item deserialize method

class guidata.dataset.TextItem(label: str, default: str | None = None, notempty: bool | None = None, wordwrap: bool = True, help: str = '', allow_none: bool = False, readonly: bool = False, regexp: str | None = None)

  Construct a text data item (multiline string)

  Parameters:

    - label – item name

    - default – default value (optional)

    - notempty – if True, empty string is not a valid value (optional)

    - wordwrap – toggle word wrapping (optional)

    - help – text shown in tooltip (optional)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=False)

    - readonly – if True, the item is read-only (optional, default=False)

    - regexp – regular expression for value validation (optional)

## Date and time items

class guidata.dataset.DateItem(label: str, default: date | None = None, format: str | None = None, help: str | None = '', check: bool | None = True, allow_none: bool = False)

  DataSet data item

  Parameters:

    - label – item label

    - default – default value (optional)

    - format – date format (as in `datetime.date.strftime()`)

    - help – text displayed on data item’s tooltip

    - check – check value (default: True)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=False)

  type

    alias of `date`

class guidata.dataset.DateTimeItem(label: str, default: datetime | None = None, format: str | None = None, help: str | None = '', check: bool | None = True, allow_none: bool = False)

  DataSet data item

  Parameters:

    - label – item label

    - default – default value (optional)

    - format – date format (as in `datetime.date.strftime()`)

    - help – text displayed on data item’s tooltip

    - check – check value (default: True)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=False)

  type

    alias of `datetime`

## Color items

class guidata.dataset.ColorItem(label: str, default: str | None = None, notempty: bool | None = None, regexp: str | None = None, help: str = '', check: bool = True, allow_none: bool = True)

  Construct a color data item

  Parameters:

    - label – item name

    - default – default value (optional)

    - notempty – if True, empty string is not a valid value (optional)

    - regexp – regular expression for checking value (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (ineffective for strings)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=True)

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

    Override DataItem method

  get_value_from_reader(reader: HDF5Reader | JSONReader | INIReader) → str

    Reads value from the reader object, inside the try…except statement defined in the base item deserialize method

## File items

class guidata.dataset.FileSaveItem(label: str, formats: tuple[str, ...] | str = '*', default: list[str] | str | None = None, basedir: str | None = None, all_files_first: bool = False, regexp: str | None = None, help: str = '', check: bool = True, allow_none: bool = False)

  Construct a path data item for a file to be saved

  Parameters:

    - label – item name

    - formats – wildcard filter

    - default – default value (optional)

    - basedir – default base directory (optional)

    - regexp – regular expression for checking value (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

    - all_files_first – if True, “All files” is the first item in the list (optional, default=False)

  get_auto_help(instance: DataSet) → str

    Override DataItem method

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

    Override DataItem method

  from_string(value) → str

    Override DataItem method

  add_extension(value) → str

    Add extension to filename value: possible value for data item

class guidata.dataset.FileOpenItem(label: str, formats: tuple[str, ...] | str = '*', default: list[str] | str | None = None, basedir: str | None = None, all_files_first: bool = False, regexp: str | None = None, help: str = '', check: bool = True, allow_none: bool = False)

  Construct a path data item for a file to be opened

  Parameters:

    - label – item name

    - formats – wildcard filter

    - default – default value (optional)

    - basedir – default base directory (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

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

    Override DataItem method

class guidata.dataset.FilesOpenItem(label: str, formats: str = '*', default: list[str] | str | None = None, basedir: str | None = None, all_files_first: bool = False, regexp: str | None = None, help: str = '', check: bool = True, allow_none: bool = False)

  Construct a path data item for multiple files to be opened.

  Parameters:

    - label – item name

    - formats – wildcard filter

    - default – default value (optional)

    - basedir – default base directory (optional)

    - regexp – regular expression for checking value (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

    - all_files_first – if True, “All files” is the first item in the list (optional, default=False)

  type

    alias of `list`

  static paths_basename(paths: str | list[str])

    Return the basename of a path or a list of paths

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

    Override DataItem method

  from_string(value: Any) → list[str]

    Override DataItem method

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

    Serialize this item

  get_value_from_reader(reader: HDF5Reader | JSONReader | INIReader) → list[str]

    Reads value from the reader object, inside the try…except statement defined in the base item deserialize method

class guidata.dataset.DirectoryItem(label: str, default: str | None = None, notempty: bool | None = None, wordwrap: bool = False, password: bool = False, regexp: str | None = None, help: str = '', check: bool = True, allow_none: bool = False, readonly: bool = False)

  Construct a path data item for a directory.

  Parameters:

    - label – item name

    - default – default value (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

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

    Override DataItem method

## Choice items

class guidata.dataset.BoolItem(text: str = '', label: str = '', default: bool | None = None, help: str = '', check: bool = True, allow_none: bool = False)

  Construct a boolean data item

  Parameters:

    - text – form’s field name (optional)

    - label – item name

    - default – default value (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=False)

  type

    alias of `bool`

  get_string_value(instance: DataSet) → str

    Override DataItem method

  get_value_from_reader(reader: HDF5Reader | JSONReader | INIReader) → bool

    Reads value from the reader object, inside the try…except statement defined in the base item deserialize method

class guidata.dataset.ChoiceItem(label: str, choices: ~typing.Iterable[~guidata.dataset.dataitems._T] | ~collections.abc.Callable[[~typing.Any], ~typing.Iterable[~guidata.dataset.dataitems._T]] | ~enum.EnumType, default: tuple[()] | type[~guidata.dataset.dataitems.FirstChoice] | int | ~guidata.dataset.dataitems._T | ~enum.Enum | None = <class 'guidata.dataset.dataitems.FirstChoice'>, help: str = '', check: bool = True, radio: bool = False, size: tuple[int, int] | None = None, allow_none: bool = True)

  Construct a data item for a list of choices.

  Parameters:

    - label – item name

    - choices – string list or (key, label) list function of two arguments (item, value) returning a list of tuples (key, label, image) where image is an icon path, a QIcon instance or a function of one argument (key) returning a QIcon instance

    - default – default value (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

    - radio – if True, shows radio buttons instead of a combo box (default is False)

    - size – size (optional) of the combo box or button widget (for radio buttons)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=True)

  type

    alias of `Any`

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

    Override DataItem method

  get_value(instance: DataSet) → str | None

    Override DataItem.get_value

  get_string_value(instance: DataSet) → str

    Override DataItem method

class guidata.dataset.MultipleChoiceItem(label: str, choices: list[str], default: tuple[()] = (), help: str = '', check: bool = True, allow_none: bool = True)

  Construct a data item for a list of choices – multiple choices can be selected

  Parameters:

    - label – item name

    - choices – string list or (key, label) list

    - default – default value (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=True)

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

    Override DataItem method

  horizontal(row_nb: int = 1) → MultipleChoiceItem

    Method to arange choice list horizontally on n rows

    Example: nb = MultipleChoiceItem(“Number”, [‘1’, ‘2’, ‘3’] ).horizontal(2)

  vertical(col_nb: int = 1) → MultipleChoiceItem

    Method to arange choice list vertically on n columns

    Example: nb = MultipleChoiceItem(“Number”, [‘1’, ‘2’, ‘3’] ).vertical(2)

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

    Serialize this item

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

    Deserialize this item

class guidata.dataset.ImageChoiceItem(label: str, choices: ~typing.Iterable[~guidata.dataset.dataitems._T] | ~collections.abc.Callable[[~typing.Any], ~typing.Iterable[~guidata.dataset.dataitems._T]] | ~enum.EnumType, default: tuple[()] | type[~guidata.dataset.dataitems.FirstChoice] | int | ~guidata.dataset.dataitems._T | ~enum.Enum | None = <class 'guidata.dataset.dataitems.FirstChoice'>, help: str = '', check: bool = True, radio: bool = False, size: tuple[int, int] | None = None, allow_none: bool = True)

  Construct a data item for a list of choices with images

  Parameters:

    - label – item name

    - choices – (label, image) list, or (key, label, image) list, or function of two arguments (item, value) returning a list of tuples (key, label, image) where image is an icon path, a QIcon instance or a function of one argument (key) returning a QIcon instance

    - default – default value (optional)

    - help – text shown in tooltip (optional)

    - radio – if True, shows radio buttons instead of a combo box (default is False)

    - size – size (optional) of the combo box or button widget (for radio buttons)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=True)

## Other items

class guidata.dataset.ButtonItem(label: str, callback: Callable, icon: str | None = None, default: Any | None = None, help: str = '', check: bool = True, size: tuple[int, int] | None = None, allow_none: bool = True)

  Construct a simple button that calls a method when hit

  Parameters:

    - label – item name

    - callback – function with four parameters (dataset, item, value, parent) where dataset (DataSet) is an instance of the parent dataset, item (DataItem) is an instance of ButtonItem (i.e. self), value (unspecified) is the value of ButtonItem (default ButtonItem value or last value returned by the callback) and parent (QObject) is button’s parent widget

    - icon – icon show on the button (optional) (str: icon filename as in guidata/guiqwt image search paths)

    - default – default value passed to the callback (optional)

    - help – text shown in button’s tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

    - size – size (optional) of the button widget

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=True)

  The value of this item is unspecified but is passed to the callback along with the whole dataset. The value is assigned the callback`s return value.

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

    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: DataSet, reader: HDF5Reader | JSONReader | INIReader) → Any

    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.DictItem(label, default: dict | None = None, help='', check=True, allow_none: bool = False)

  Construct a data item representing a dictionary

  Parameters:

    - label – item name

    - default – default value (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)

    - allow_none – if True, None is a valid value regardless of other constraints (optional, default=False)

  type

    alias of `dict`

  serialize(instance, writer)

    Serialize this item

  get_value_from_reader(reader)

    Reads value from the reader object, inside the try…except statement defined in the base item deserialize method

class guidata.dataset.FontFamilyItem(label: str, default: str | None = None, notempty: bool | None = None, wordwrap: bool = False, password: bool = False, regexp: str | None = None, help: str = '', check: bool = True, allow_none: bool = False, readonly: bool = False)

  Construct a font family name item

  Parameters:

    - label – item name

    - default – default value (optional)

    - help – text shown in tooltip (optional)

    - check – if False, value is not checked (optional, default=True)