Utilities

Data sets

guidata.utils.update_dataset(dest: gdt.DataSet, source: Any | dict[str, Any], visible_only: bool = False) None

Update dest dataset items from source dataset.

Parameters:
  • dest (DataSet) – The destination dataset object to update.

  • source (Union[Any, Dict[str, Any]]) – The source object or dictionary containing matching attribute names.

  • visible_only (bool) – If True, update only visible items. Defaults to False.

For each DataSet item, the function will try to get the attribute of the same name from the source.

If the attribute exists in the source object or the key exists in the dictionary, it will be set as the corresponding attribute in the destination dataset.

Returns:

None

guidata.utils.restore_dataset(source: gdt.DataSet, dest: Any | dict[str, Any]) None

Restore dest dataset items from source dataset.

Parameters:
  • source (DataSet) – The source dataset object to restore from.

  • dest (Union[Any, Dict[str, Any]]) – The destination object or dictionary.

This function is almost the same as update_dataset but requires the source to be a DataSet instead of the destination.

Symmetrically from update_dataset, dest may also be a dictionary.

Returns:

None

Miscellaneous utility functions

Running programs

guidata.utils.misc.run_program(name, args: str = '', cwd: str = None, shell: bool = True, wait: bool = False) None

Run program in a separate process.

Parameters:
  • name (str) – The program name.

  • args (str) – The program arguments. Defaults to “”.””

  • cwd (str) – The current working directory. Defaults to None.

  • shell (bool) – If True, run program in a shell. Defaults to True.

  • wait (bool) – If True, wait for program to finish. Defaults to False.

Raises:

RuntimeError – If program is not installed.

guidata.utils.misc.is_program_installed(basename: str) str | None

Return program absolute path if installed in PATH, otherwise None.

Parameters:

basename (str) – The program base name.

Returns:

The program absolute path if installed in PATH,

otherwise None.

Return type:

str | None

guidata.utils.misc.run_shell_command(cmdstr, **subprocess_kwargs)

Execute the given shell command.

Note that *args and **kwargs will be passed to the subprocess call.

If ‘shell’ is given in subprocess_kwargs it must be True, otherwise ProgramError will be raised.

If ‘executable’ is not given in subprocess_kwargs, it will be set to the value of the SHELL environment variable.

Note that stdin, stdout and stderr will be set by default to PIPE unless specified in subprocess_kwargs.

Str cmdstr:

The string run as a shell command.

Subprocess_kwargs:

These will be passed to subprocess.Popen.

Strings

guidata.utils.misc.to_string(obj: Any) str

Convert to string, trying utf-8 then latin-1 codec

Parameters:

obj (Any) – Object to convert to string

Returns:

String representation of object

Return type:

str

guidata.utils.misc.decode_fs_string(string: str) str

Convert string from file system charset to unicode

Parameters:

string (str) – String to convert

Returns:

Converted string

Return type:

str