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)[source]
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)[source]
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 thePYDM_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)[source]
Look for files at the search paths common to PyDM.
The search order is as follows:
The
base_path
argumentQt 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] [source]
Get the clipboard instance. Requires a QApplication.
- pydm.utilities.get_clipboard_modes() List[int] [source]
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 [source]
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()[source]
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 [source]
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 toTrue
.
- Returns:
module – The imported module.
- Return type:
types.ModuleType
- pydm.utilities.is_pydm_app(app=None)[source]
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()[source]
Check whether or not running inside Qt Designer.
- Returns:
True if inside Designer, False otherwise.
- Return type:
bool
- pydm.utilities.is_ssh_session()[source]
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)[source]
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 exceptionex
.
include_traceback (bool, optional) – Include traceback information in the log message.
level (int, optional) – Logging level to use.
- pydm.utilities.only_main_thread(func)[source]
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)[source]
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()[source]
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)[source]
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)[source]
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)[source]
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.
Icons
- class pydm.utilities.iconfont.IconFont(*args, **kwargs)[source]
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] [source]
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 [source]
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] [source]
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
Macro
- pydm.utilities.macro.parse_macro_string(macro_string)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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