# 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>