Utilities

PyDM comes with a set of utility methods ranging from simple replacement of protocol in a string, handling macro substitution in files, etc.

General

pydm.utilities.copy_to_clipboard(text: str, *, quiet: bool = False)

Copy text to the clipboard.

Parameters:

• text (str) – The text to copy to the clipboard.

• quiet (bool, optional, keyword-only) – If quiet is set, do not log the copied text. Defaults to False.

pydm.utilities.find_display_in_path(file, mode=None, path=None, pathext=None)

Look for a display file in a given path. This is basically a wrapper on top of the which command defined below so we don’t need to keep redefining the PYDM_DISPLAYS_PATH variable.

Parameters:

• file (str) – The file name.

• mode (int) – The mode required for the file, defaults to os.F_OK | os.R_OK. Which ensure that the file exists and we can read it.

• path (str) – The PATH string.

Returns:

Returns the full path to the file or None in case it was not found.

Return type:

str

pydm.utilities.find_file(fname, base_path=None, mode=None, extra_path=None, raise_if_not_found=False)

Look for files at the search paths common to PyDM.

The search order is as follows:

• The base_path argument

• Qt Designer Path - the path for the current form as reported by the designer

• The current working directory

• Directories listed in extra_path

• Directories listed in the environment variable PYDM_DISPLAYS_PATH

Parameters:

• fname (str) – The file name. Environment variables, ~ and ~user constructs before search.

• base_path (str) – The directory name of a file pathname from a display, if any

• mode (int) – The mode required for the file, defaults to os.F_OK | os.R_OK. Which ensure that the file exists and we can read it.

• extra_path (list) – Additional paths to look for file.

• raise_if_not_found (bool) – Flag which if False will add a check that raises a FileNotFoundError instead of returning None when the file is not found.

Returns:

file_path – Returns the file path or None in case the file was not found

Return type:

str

pydm.utilities.get_clipboard() → Optional[QClipboard]

Get the clipboard instance. Requires a QApplication.

pydm.utilities.get_clipboard_modes() → List[int]

Get the clipboard modes for the current platform.

Returns:

Qt-specific modes to try for interacting with the clipboard.

Return type:

list of int

pydm.utilities.get_clipboard_text() → str

Get text from the clipboard. If unavailable or unset, empty string.

Returns:

The clipboard text, if available.

Return type:

str

pydm.utilities.get_designer_current_path()

Fetch the absolute path for the current active form at Qt Designer.

Returns:

path – The absolute path for the current active form or None in case not available

Return type:

str, None

pydm.utilities.import_module_by_filename(source_filename: str, *, add_to_modules: bool = True) → module

For a given source filename, import it and search for objects.

Parameters:

• source_filename (str) – The source code filename.

• add_to_modules (bool, optional, keyword-only) – Add the imported module to sys.modules. Defaults to True.

Returns:

module – The imported module.

Return type:

types.ModuleType

pydm.utilities.is_pydm_app(app=None)

Check whether or not QApplication.instance() is a PyDMApplication.

Parameters:

app (QApplication, Optional) – The app to inspect. If no application is provided the current running QApplication will be queried.

Returns:

True if it is a PyDMApplication, False otherwise.

Return type:

bool

pydm.utilities.is_qt_designer()

Check whether or not running inside Qt Designer.

Returns:

True if inside Designer, False otherwise.

Return type:

bool

pydm.utilities.is_ssh_session()

Whether or not this is a SSH session.

Returns:

True if it is a ssh session, False otherwise.

Return type:

bool

pydm.utilities.log_failures(logger: Logger, explanation: str = 'Failed to run {func.__name__}', include_traceback: bool = False, level: int = 30)

Decorator that wraps a function to be run.

Exceptions raised while executing that function will be logged. In case of an exception, the wrapper will return None.

Parameters:

• logger (logging.Logger) – The logger instance to log messages to.

• explanation (str, optional) –

  The explanation message to include. Format arguments include:

  func, args, kwargs, and the exception ex.

• include_traceback (bool, optional) – Include traceback information in the log message.

• level (int, optional) – Logging level to use.

pydm.utilities.only_main_thread(func)

Decorator that wraps a function which should only be executed at the Qt main thread.

The decorator will log an error message and raise a RuntimeError if the decorated function is invoked from a thread other than the Qt main one.

Parameters:

func (callable) – The function to wrap

Return type:

wrapper

pydm.utilities.path_info(path_str)

Retrieve basic information about the given path.

Parameters:

path_str (str) – The path from which to extract information.

Returns:

base dir, file name, list of args

Return type:

tuple

pydm.utilities.setup_renderer()

This utility function reverts the renderer to Software rendering if it is running in a SSH session.

pydm.utilities.which(cmd, mode=1, path=None, pathext=None, extra_path=None)

Given a command, mode, and a PATH string, return the path which conforms to the given mode on the PATH, or None if there is no such file. mode defaults to os.F_OK | os.X_OK. path defaults to the result of os.environ.get(“PATH”), or can be overridden with a custom search path. Note: This function was backported from the Python 3 source code and modified to deal with the case in which we WANT to look at the path even with a relative path.

pydm.utilities.remove_protocol.parsed_address(address)

Returns the given address parsed into a 6-tuple. The parsing is done by urllib.parse.urlparse

Parameters:

address (str) – The address from which to remove the address prefix.

Returns:

parsed_address

Return type:

tuple

pydm.utilities.remove_protocol.protocol_and_address(address)

Returns the Protocol and Address pieces of a Channel Address

Parameters:

address (str) – The address from which to remove the address prefix.

Returns:

• protocol (str) – The protocol used. None in case the protocol is not specified.

• addr (str) – The piece of the address without the protocol.

pydm.utilities.remove_protocol.remove_protocol(addr)

Removes the first occurrence of the protocol string (‘://’) from the string addr

Parameters:

addr (str) – The address from which to remove the address prefix.

Return type:

str

Icons

class pydm.utilities.iconfont.IconFont(*args, **kwargs)

IconFont represents an icon font. Users will generally want to use IconFont.icon() to get a QIcon object for the character they want.

font(size: int) → Optional[QFont]

Load the font at a given pixel size.

Returns:

The font, if available. If a QApplication is not yet created, None will be returned.

Return type:

QtGui.QFont or None

get_char_for_name(name: str) → str

Get a character icon for the given name from the character map.

Parameters:

name (str) – The user-friendly icon name.

Returns:

The Qt-facing icon text to use with the font.

Return type:

str

icon(name, color=None) → Optional[QIcon]

Retrieve the icon given a name and color.

Parameters:

• name (str) – The Icon string identifier. Icon strings can be found at: https://fontawesome.com/icons?d=gallery

• color (QColor, Optional) – The base color to use when constructing the Icon. Default is QColor(90, 90, 90).

Returns:

The desired Icon. None if a QApplication is not yet available.

Return type:

QIcon

load_font(ttf_filename, charmap_filename)

Load font from ttf_filename with a mapping defined in charmap_filename.

Macro

pydm.utilities.macro.parse_macro_string(macro_string)

Parses a macro string and returns a dictionary. First, this method attempts to parse the string as JSON. If that fails, it attempts to parse it as an EPICS-style macro string. The parsing algorithm for that case is very closely based on macParseDefns in libCom/macUtil.c

pydm.utilities.macro.substitute_in_file(file_path, macros)

Substitute the macros given by ${name} at the given file with the entries on the macros dictionary.

Parameters:

• file_path (str) – The path to the file in which to substitute

• macros (dict) – Dictionary containing macro name as key and value as what will be substituted.

Returns:

file – File-like object with the proper substitutions.

Return type:

io.StringIO

Colors

pydm.utilities.colors.hex_from_svg_color(color_string)

Returns the HEX color based on its SVG equivalent.

Parameters:

color_string (str) – The SVG color string. E.g. black

Returns:

The HEX color string.

Return type:

str

pydm.utilities.colors.svg_color_from_hex(hex_string, hex_on_fail=False)

Returns the SVG color based on its HEX equivalent.

Parameters:

• hex_string (str) – The color code in hex. E.g. #000000

• hex_on_fail (bool, Optional) – Whether or not to return the hex_string when an invalid color is submitted. Default is False.

Returns:

The SVG color string.

Return type:

str

Units

pydm.utilities.units.convert(unit, desired)

Find the conversion rate of two different unit strings.

Parameters:

• unit (str) – The current unit string

• desired (str) – The desired unit string

Returns:

The relation between unit and desired or None if not found.

Return type:

float or None

pydm.utilities.units.find_unit(unit)

Find the conversion of a unit string.

Parameters:

unit (str) – The unit string

Returns:

The unit value relative to the standard or None if not found.

Return type:

float or None

pydm.utilities.units.find_unit_options(unit)

Find the options for a given unit.

Parameters:

unit (str) – The unit string

Returns:

The list of similar units in crescent order or None if not found.

Return type:

list or None

pydm.utilities.units.find_unittype(unit)

Find the type of a unit string.

Parameters:

unit (str) – The unit string

Returns:

tp – The unit type name or None if not found.

Return type:

str