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:
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:
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)