Utilities

Utilities package for guidata.

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 object to string.

If obj is bytes-like, try decoding as UTF-8, falling back to Latin-1. Otherwise, use 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 or standard Qt icon names

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

Translations utilities

Description

This module provides utilities for managing translations in guidata. It is based on Babel.

Three functions are provided:

• scan_translations(): Extracts translatable strings from Python files and generates translation files.

• compile_translations(): Compiles translation files into binary format.

• main(): Convenience function to call scan_translations() or compile_translations() with command-line arguments.

Usage

To extract translatable strings and generate translation files, use:

$ # Scan translations
$ python -m guidata.utils.translations scan --name <name> --directory <directory>
$ # Alternatively, you can use the command-line tool:
$ guidata-translations scan --name <name> --directory <directory>

To compile translation files into binary format, use:

$ # Compile translations
$ python -m guidata.utils.translations compile --name <name> --directory <directory>
$ # Alternatively, you can use the command-line tool:
$ guidata-translations compile --name <name> --directory <directory>