Utilities

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

Configuration related functions

Access configured options

guidata.configtools.get_icon(name: str, default: str = 'not_found.png') → QG.QIcon

Construct a QIcon from the file with specified name name, default: filenames with extensions

Parameters:

• name (str) – name of the icon

• default (str) – default icon name. Defaults to “not_found.png”.

Returns:

icon

Return type:

QG.QIcon

guidata.configtools.get_image_file_path(name: str, default: str = 'not_found.png') → str

Return the absolute path to image with specified name name, default: filenames with extensions

Parameters:

• name (str) – name of the image

• default (str) – default image name. Defaults to “not_found.png”.

Raises:

RuntimeError – if image file not found

Returns:

absolute path to image

Return type:

str

guidata.configtools.get_image_label(name, default='not_found.png') → QW.QLabel

Construct a QLabel from the file with specified name name, default: filenames with extensions

Parameters:

• name (str) – name of the icon

• default (str) – default icon name. Defaults to “not_found.png”.

Returns:

label

Return type:

QW.QLabel

guidata.configtools.get_image_layout(imagename: str, text: str = '', tooltip: str = '', alignment: QC.Qt.Alignment = None) → tuple[QW.QHBoxLayout, QW.QLabel]

Construct a QHBoxLayout including image from the file with specified name, left-aligned text [with specified tooltip]

Parameters:

• imagename (str) – name of the icon

• text (str) – text to display. Defaults to “”.

• tooltip (str) – tooltip to display. Defaults to “”.

• alignment (QC.Qt.Alignment) – alignment of the text. Defaults to None.

Returns:

layout, label

Return type:

tuple[QW.QHBoxLayout, QW.QLabel]

guidata.configtools.get_family(families: str | list[str]) → str

Return the first installed font family in family list

Parameters:

families (str|list[str]) – font family or list of font families

Returns:

first installed font family

Return type:

str

guidata.configtools.get_font(conf: UserConfig, section: str, option: str = '') → QG.QFont

Construct a QFont from the specified configuration file entry conf: UserConfig instance section [, option]: configuration entry

Parameters:

• conf (UserConfig) – UserConfig instance

• section (str) – configuration entry

• option (str) – configuration entry. Defaults to “”.

Returns:

font

Return type:

QG.QFont

guidata.configtools.get_pen(conf: UserConfig, section: str, option: str = '', color: str = 'black', width: int = 1, style: str = 'SolidLine') → QG.QPen

Construct a QPen from the specified configuration file entry conf: UserConfig instance section [, option]: configuration entry [color]: default color [width]: default width [style]: default style

Parameters:

• conf (UserConfig) – UserConfig instance

• section (str) – configuration entry

• option (str) – configuration entry. Defaults to “”.

• color (str) – default color. Defaults to “black”.

• width (int) – default width. Defaults to 1.

• style (str) – default style. Defaults to “SolidLine”.

Returns:

pen

Return type:

QG.QPen

guidata.configtools.get_brush(conf: UserConfig, section: str, option: str = '', color: str = 'black', alpha: float = 1.0) → QG.QBrush

Construct a QBrush from the specified configuration file entry conf: UserConfig instance section [, option]: configuration entry [color]: default color [alpha]: default alpha-channel

Parameters:

• conf (UserConfig) – UserConfig instance

• section (str) – configuration entry

• option (str) – configuration entry. Defaults to “”.

• color (str) – default color. Defaults to “black”.

• alpha (float) – default alpha-channel. Defaults to 1.0.

Returns:

brush

Return type:

QG.QBrush

Add image paths

guidata.configtools.add_image_path(path: str, subfolders: bool = True) → None

Append image path (opt. with its subfolders) to global list IMG_PATH

Parameters:

• path (str) – image path

• subfolders (bool) – include subfolders

guidata.configtools.add_image_module_path(modname: str, relpath: str, subfolders: bool = True) → None

Appends image data path relative to a module name. Used to add module local data that resides in a module directory but will be shipped under sys.prefix / share/ …

modname must be the name of an already imported module as found in sys.modules

Parameters:

• modname (str) – module name

• relpath (str) – relative path to module data directory

• subfolders (bool) – include subfolders