Parser Helpers

apply_rewrite_rule(rewrite_rule, arg_list)

Apply a rewrite rule to an argument list. Rewrite rules often look like '$(A),$(A).SEVR', which can expand a single argument into multiple arguments by replacing placeholders.

For example

rewrite_rule = '$(A),$(A).SEVR' arg_list = ['myPV']

=> new_args = ['myPV', 'myPV.SEVR']

Parameters

rewrite_rule : str The rewrite rule, without the leading '@' (e.g. '$(A),$(A).SEVR'). arg_list : List[str] The list of arguments to which we apply the rule.

Returns

List[str] A new list of arguments produced by the rewrite rule.

Source code in pydmconverter/edm/parser_helpers.py

def apply_rewrite_rule(rewrite_rule: str, arg_list: List[str]) -> List[str]:
    """
    Apply a rewrite rule to an argument list. Rewrite rules often look like
    '$(A),$(A).SEVR', which can expand a single argument into multiple arguments
    by replacing placeholders.

    For example:
        rewrite_rule = '$(A),$(A).SEVR'
        arg_list = ['myPV']
      => new_args = ['myPV', 'myPV.SEVR']

    Parameters
    ----------
    rewrite_rule : str
        The rewrite rule, without the leading '@' (e.g. '$(A),$(A).SEVR').
    arg_list : List[str]
        The list of arguments to which we apply the rule.

    Returns
    -------
    List[str]
        A new list of arguments produced by the rewrite rule.
    """
    placeholders = "ABCDEFGHIJKL"

    arg_map = {}
    for i, arg_val in enumerate(arg_list):
        if i < len(placeholders):
            arg_map[placeholders[i]] = arg_val

    new_args = []

    for part in rewrite_rule.split(","):
        result = part

        for letter, val in arg_map.items():
            result = result.replace("$(" + letter + ")", val)
        new_args.append(result)

    return new_args

clean_escape_characters(expr)

Remove extra ' characters from CALC/LOC expressions.

Parameters

expression : str The expression to be cleaned.

Returns

str The new expression with \s removed.

Source code in pydmconverter/edm/parser_helpers.py

def clean_escape_characters(expr: str) -> str:
    """
    Remove extra \' characters from CALC/LOC expressions.

    Parameters
    ----------
    expression : str
        The expression to be cleaned.

    Returns
    -------
    str
        The new expression with \\s removed.
    """
    expr = expr.lstrip("\\")
    expr = expr.replace(r"\{", "{").replace(r"\}", "}")
    # TODO: If more \ removal cases are needed, add them here

    return expr

convert_color_property_to_qcolor(fillColor, color_data)

Convert the EDM 'fillColor', 'bgColor', 'fgColor' property into a tuple representing RGBA values.

Returns:

Type	Description
Optional[Tuple[int, int, int, int]]	Optional[Tuple[int, int, int, int]]: A tuple (red, green, blue, alpha) or None.

Source code in pydmconverter/edm/parser_helpers.py

def convert_color_property_to_qcolor(fillColor: str, color_data: Dict[str, Any]) -> Optional[Tuple[int, int, int, int]]:
    """
    Convert the EDM 'fillColor', 'bgColor', 'fgColor' property into a tuple representing RGBA values.

    Returns:
        Optional[Tuple[int, int, int, int]]: A tuple (red, green, blue, alpha) or None.
    """
    if fillColor.startswith("rgb"):
        color_info = get_color_by_rgb(fillColor)
    else:
        color_info = get_color_by_index(color_data, fillColor)
    if not color_info:
        logger.warning(f"Could not find a color for fillColor '{fillColor}'. Using default gray.")
        return (128, 128, 128, 255)

    rgb = color_info.get("rgb")
    if not rgb or len(rgb) < 3:
        logger.warning(f"Invalid RGB data for color '{fillColor}': {rgb}")
        return (128, 128, 128, 255)
    red, green, blue = rgb[:3]
    alpha = 255

    # Without a colors.list (parse_colors_list gives max None), or one with no "max"
    # line, components are 16-bit: EDM starts from maxColor = 0x10000 (color_pkg.cc).
    max_val = color_data.get("max") or 0x10000
    rgbMax = max(rgb)
    if rgbMax > 256:
        # Scale from 0-65535 to 0-255
        red = int(red * 255 / (max_val - 1))
        green = int(green * 255 / (max_val - 1))
        blue = int(blue * 255 / (max_val - 1))

    # result = (red, green, blue, alpha)
    result = RGBA(r=red, g=green, b=blue, a=alpha)
    logger.info(f"Converted {fillColor} to color: {result}")

    return result

edm_atof(text)

C atof() semantics: the longest numeric prefix (decimal, hex, inf/nan), else 0.0.

Source code in pydmconverter/edm/parser_helpers.py

def edm_atof(text: str) -> float:
    """C ``atof()`` semantics: the longest numeric prefix (decimal, hex, inf/nan), else 0.0."""
    text = text.lstrip()
    hex_match = _HEX_PREFIX_RE.match(text)
    if hex_match:
        token = hex_match.group(0)
        sign = -1.0 if token.startswith("-") else 1.0
        return sign * float.fromhex(token.lstrip("+-"))
    match = _DEC_PREFIX_RE.match(text) or _SPECIAL_PREFIX_RE.match(text)
    return float(match.group(0)) if match else 0.0

get_calc_arguments(args)

Split the text after a CALC PV's ( into its arguments like EDM's get_arg (calc_pv_factory.cc).

Runs of ,, spaces, tabs and ) before an argument are skipped, so an empty argument disappears and the ones after it move up ((X,,Y) makes Y argument B). An argument ends at a top-level , or at the first ) it did not open, so a stray ) never becomes part of a PV name.

Source code in pydmconverter/edm/parser_helpers.py

def get_calc_arguments(args: str) -> List[str]:
    """
    Split the text after a CALC PV's ``(`` into its arguments like EDM's
    ``get_arg`` (calc_pv_factory.cc).

    Runs of ``,``, spaces, tabs and ``)`` before an argument are skipped, so an
    empty argument disappears and the ones after it move up (``(X,,Y)`` makes Y
    argument B). An argument ends at a top-level ``,`` or at the first ``)`` it
    did not open, so a stray ``)`` never becomes part of a PV name.
    """
    arguments = []
    i = 0
    while True:
        while i < len(args) and args[i] in ", \t)":
            i += 1
        if i >= len(args):
            return arguments
        # Like get_arg, start looking for the end after the first character.
        end = i + 1
        depth = 0
        while end < len(args):
            if args[end] == "(":
                depth += 1
            elif args[end] == ")":
                depth -= 1
                if depth < 0:
                    break
            elif args[end] == "," and depth == 0:
                break
            end += 1
        arguments.append(args[i:end].rstrip())
        i = end

get_calc_groups(edm_pv)

Split a CALC PV into its expression (a calc.list name or an inline {...} expression) and the text after the ( that opens its arguments.

As in EDM's CALC_PV_Factory::create (calc_pv_factory.cc), the expression ends at the first ( outside braces; without one there are no arguments.

Source code in pydmconverter/edm/parser_helpers.py

def get_calc_groups(edm_pv: str) -> Tuple[str, str]:
    """
    Split a CALC PV into its expression (a calc.list name or an inline ``{...}``
    expression) and the text after the ``(`` that opens its arguments.

    As in EDM's ``CALC_PV_Factory::create`` (calc_pv_factory.cc), the expression
    ends at the first ``(`` outside braces; without one there are no arguments.
    """
    prefix = "CALC\\"
    if not edm_pv.startswith(prefix):
        raise ValueError(f"Not a CALC PV: {edm_pv}")

    edm_pv = edm_pv[len(prefix) :]
    braces = 0
    for i, ch in enumerate(edm_pv):
        if ch == "{":
            braces += 1
        elif ch == "}" and braces:
            braces -= 1
        elif ch == "(" and not braces:
            return edm_pv[:i], edm_pv[i + 1 :]
    return edm_pv, ""

get_color_by_index(color_data, index)

Retrieve the color definition from color_data using an index string like 'index 3'.

Parameters:

Name	Type	Description	Default
color_data	Dict[str, Any]	The parsed colors.list data.	required
index	str	The color index string, e.g., 'index 3'.	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Optional[Dict[str, Any]]: The corresponding color dictionary (expected to have an 'rgb' key) or None if not found.

Source code in pydmconverter/edm/parser_helpers.py

def get_color_by_index(color_data: Dict[str, Any], index: str) -> Optional[Dict[str, Any]]:
    """
    Retrieve the color definition from color_data using an index string like 'index 3'.

    Args:
        color_data (Dict[str, Any]): The parsed colors.list data.
        index (str): The color index string, e.g., 'index 3'.

    Returns:
        Optional[Dict[str, Any]]: The corresponding color dictionary (expected to have an 'rgb' key)
                                  or None if not found.
    """
    match = re.match(r"index\s+(\d+)", index)
    if match:
        idx = int(match.group(1))
        color = color_data.get("static", {}).get(idx)
        if not color:
            color = rule_static_color(color_data, idx)
        if not color:
            logger.warning(f"Color index {idx} not found in colors.list.")
        return color
    logger.warning(f"Invalid color index format: '{index}'.")
    return None

get_color_by_rgb(colorStr)

Retrieve the color definition from color_data using an rgb string like 'rgb 0 0 0'.

Parameters:

Name	Type	Description	Default
colorStr	str	The color index string, e.g., 'rgb 0 0 0'.	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Optional[Dict[str, Any]]: The corresponding color dictionary (expected to have an 'rgb' key) or None if not found.

Source code in pydmconverter/edm/parser_helpers.py

def get_color_by_rgb(colorStr: str) -> Optional[Dict[str, Any]]:
    """
    Retrieve the color definition from color_data using an rgb string like 'rgb 0 0 0'.

    Args:
        colorStr (str): The color index string, e.g., 'rgb 0 0 0'.

    Returns:
        Optional[Dict[str, Any]]: The corresponding color dictionary (expected to have an 'rgb' key)
                                  or None if not found.
    """
    color_list: list[str] = colorStr.split()  # tolerate any run of whitespace between components
    output_dict = {}
    output_dict["rgb"] = [int(s) for s in color_list[1:]]  # get ints from list excluding 'rgb' at index 0

    return output_dict

loc_conversion(edm_string)

Convert an EDM local PV string to a PyDM local variable string, mapping types to supported PyDM types.

Supported PyDM types: - int - float - str - array (numpy.ndarray)

Enum ('e') is mapped to int for simplicity in this conversion.

A value with no recognized type prefix (e.g. "CMOS:LI20:3490") becomes a str PV holding the whole text, whereas EDM drops its first two characters.

Other attributes without a ":" are read as EDM's setAttributes (loc_pv_factory.cc) reads them: the first character is the type and the next one is skipped, so "LOC\x=intPv=Show" is an int holding 0. A bare number stays an int ("LOC\x=0"); attributes starting with no type EDM knows give a bare "loc://" that declares nothing.

Parameters

edm_string : str EDM local PV string to be converted. Expected format is: "LOC\name=type:value" (with optional scope modifiers and ignoring special functions).

Returns

pydm_string : str Corresponding PyDM string in the format: "loc://?type=&init=".

Raises

ValueError If the EDM string does not start with 'LOC\' or if it lacks the proper format.

Source code in pydmconverter/edm/parser_helpers.py

def loc_conversion(edm_string: str) -> str:
    """
    Convert an EDM local PV string to a PyDM local variable string, mapping types to supported PyDM types.

    Supported PyDM types:
    - int
    - float
    - str
    - array (numpy.ndarray)

    Enum ('e') is mapped to int for simplicity in this conversion.

    A value with no recognized type prefix (e.g. "CMOS:LI20:3490") becomes a
    str PV holding the whole text, whereas EDM drops its first two characters.

    Other attributes without a ":" are read as EDM's setAttributes
    (loc_pv_factory.cc) reads them: the first character is the type and the
    next one is skipped, so "LOC\\x=intPv=Show" is an int holding 0. A bare
    number stays an int ("LOC\\x=0"); attributes starting with no type EDM
    knows give a bare "loc://<name>" that declares nothing.

    Parameters
    ----------
    edm_string : str
        EDM local PV string to be converted. Expected format is:
        "LOC\\name=type:value" (with optional scope modifiers and ignoring special functions).

    Returns
    -------
    pydm_string : str
        Corresponding PyDM string in the format:
        "loc://<name>?type=<mapped_type>&init=<value>".

    Raises
    ------
    ValueError
        If the EDM string does not start with 'LOC\\' or if it lacks the proper format.
    """
    prefix = "LOC\\"
    if not edm_string.startswith(prefix):
        raise ValueError("Provided string does not start with 'LOC\\'")

    content = edm_string[len(prefix) :]

    # if "$(" in content and ")" in content:
    #    content = content.split(")", 1)[-1]

    type_mapping = {
        "d": "float",
        "i": "int",
        "s": "str",
        "e": "int",  # mapping enum to int
    }

    try:
        name, type_and_value = content.split("=", 1)
        name = name.lstrip("\\")
        # EDM reads the attributes up to the next "=" or "~", skipping repeated
        # separators as in LOC\name==0 (strtok_r in loc_pv_factory.cc create).
        type_and_value = re.split(r"[=~]", type_and_value.lstrip("=~"), maxsplit=1)[0]
    except ValueError:
        name = content.lstrip("\\")
        return f"loc://{name}"
        # raise ValueError("Invalid EDM format: Missing '=' separator")

    try:
        type_char, value = type_and_value.split(":", 1)
    except ValueError:
        try:
            if (
                len(type_and_value) > 1 and type_and_value[0] in type_mapping and type_and_value[1] == ","
            ):  # ex. type_and_value=i,10
                value = type_and_value[2:]
                type_char = type_and_value[0]
            else:
                int(type_and_value)  # testing if this is a proper int
                value = type_and_value
                type_char = "i"
            """if type_and_value.startswith("d,"):
                value = type_and_value[2:]
                float(value)
                type_char = "d"
            elif type_and_value.startswith("i,"):
                value = type_and_value[2:]
                int(value)
                type_char = "i"
            elif type_and_value == "s,":
                value = type_and_value[2:]
                type_char = "s"
            """
        except ValueError:
            try:
                float(type_and_value)
                value = type_and_value
                type_char = "d"
            except ValueError:
                if type_and_value[:1] not in type_mapping:
                    # No type EDM knows either, as in LOC\$(!W)intPv=ShowChannels.
                    # EDM ignores the attributes of all but a variable's first
                    # declaration, so name the variable without declaring it: an
                    # empty string declared here could win over the real one.
                    logger.warning(f"Unparseable local PV attributes '{type_and_value}' for '{name}', not declaring it")
                    return f"loc://{name}"
                # The first character is the type and the next one is skipped,
                # as in EDM's setAttributes; an int, double or enum value is read
                # with atol/atof, so LOC\name=intPv is an int holding 0.
                # A lone type character reads the same way: LOC\name=d is a
                # double holding 0, not a blank init PyDM never configures.
                type_char, value = type_and_value[0], type_and_value[2:]
                if type_char != "s":
                    head, sep, states = value.partition(",") if type_char == "e" else (value, "", "")
                    number_pattern = r"\s*[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?" if type_char == "d" else r"\s*[+-]?\d+"
                    number = re.match(number_pattern, head)
                    value = (number.group().strip() if number else "0") + sep + states

    edm_type = type_char.lower()
    if edm_type.isdigit():
        value = edm_type
        edm_type = "i"
    pydm_type = type_mapping.get(edm_type)
    if pydm_type is None:
        # logger.warning(f"Unsupported type character: {type_char}")
        # return f"No loc here"
        if edm_type and len(edm_type) > 1:
            # No type prefix, e.g. LOC\DISP=CMOS:LI20:3490. EDM's default case
            # makes a string PV but still drops a type char and separator, so
            # it stores "OS:LI20:3490". Keep the whole text instead: it is the
            # author's value, and int readers like menuMux see 0 either way.
            edm_type = "s"
            pydm_type = type_mapping[edm_type]
            value = type_and_value
            logger.warning(
                f"Local PV '{name}' has no recognized type in '{type_and_value}', using it as a string value"
            )
        else:
            raise ValueError(f"Unsupported type character: {type_char}")

    if value.strip().upper() == "RAND()":
        raise NotImplementedError("Special function RAND() is not supported yet.")

        # a calc pv would have to be returned instead of a local pv
        # pydm_string = f"calc://{name}?var=loc://temp&expr=np.random.rand()"
        # an invisible widget with the definiation of a temp local pv would have to be added to the screen as well
        # temp_pv_string = "loc://temp?type=float&init=0.0"

    elif edm_type == "e":
        value_arr: List[str] = value.split(",")
        init: str = value_arr[0]
        enum_string: List[str] = value_arr[1:]
        query = f"init={qs_escape(init)}&enum_string={qs_escape(str(enum_string))}"
        pydm_string = f"loc://{name}?type={pydm_type}&{query}"
    else:
        pydm_string = f"loc://{name}?type={pydm_type}&init={qs_escape(value)}"

    return pydm_string

loc_str_init(url)

Initial value of a str loc:// URL as loc_conversion writes it; "" for any other channel.

Source code in pydmconverter/edm/parser_helpers.py

def loc_str_init(url: str) -> str:
    """Initial value of a str loc:// URL as loc_conversion writes it; "" for any other channel."""
    if not url.startswith("loc://") or not re.search(r"[?&]type=str(&|$)", url):
        return ""
    match = re.search(r"[?&]init=([^&]*)", url)
    return unquote(match.group(1)) if match else ""

normalize_search_paths(search_paths)

Normalize extra search directories into a list of path strings.

A lone path (str or os.PathLike) is accepted as well as a sequence of paths, so a plain string is not split into its characters. Empty entries are dropped, as in an EDMDATAFILES split, so "" never stands for the current directory; a caller who wants the CWD searched passes ".".

Parameters

search_paths : str | os.PathLike | Sequence[str | os.PathLike], optional A single directory, a sequence of directories, or None.

Returns

List[str] The non-empty directories as strings, in order; empty when search_paths is None.

Source code in pydmconverter/edm/parser_helpers.py

def normalize_search_paths(search_paths: SearchPaths) -> List[str]:
    """
    Normalize extra search directories into a list of path strings.

    A lone path (str or os.PathLike) is accepted as well as a sequence of paths,
    so a plain string is not split into its characters. Empty entries are dropped,
    as in an EDMDATAFILES split, so ``""`` never stands for the current directory;
    a caller who wants the CWD searched passes ``"."``.

    Parameters
    ----------
    search_paths : str | os.PathLike | Sequence[str | os.PathLike], optional
        A single directory, a sequence of directories, or None.

    Returns
    -------
    List[str]
        The non-empty directories as strings, in order; empty when search_paths is
        None.
    """
    if search_paths is None:
        return []
    if isinstance(search_paths, (str, os.PathLike)):
        search_paths = [search_paths]
    return [path for path in map(os.fspath, search_paths) if path]

parse_calc_list(calc_list_path)

Parse an EPICS-style calc.list file and return a dictionary mapping calculation names to a tuple of (rewrite_rule, expression).

The file format typically looks like

CALC1 ...
# ...
<calc_name>
[@rewrite_rule]
<expression>
# ...

Parameters

calc_list_path : str Path to the calc.list file.

Returns

Dict[str, Tuple[Optional[str], Optional[str]]] A dictionary with keys as calculation names (e.g. 'sum', 'diff') and values as a 2-tuple (rewrite_rule, expression). Both are optional: rewrite_rule may be None if not present, and expression may also be None if the file has incomplete entries.

Source code in pydmconverter/edm/parser_helpers.py

def parse_calc_list(calc_list_path: str) -> Dict[str, Tuple[Optional[str], Optional[str]]]:
    """
    Parse an EPICS-style calc.list file and return a dictionary mapping
    calculation names to a tuple of (rewrite_rule, expression).

    The file format typically looks like:
        ```
        CALC1 ...
        # ...
        <calc_name>
        [@rewrite_rule]
        <expression>
        # ...
        ```
    Parameters
    ----------
    calc_list_path : str
        Path to the calc.list file.

    Returns
    -------
    Dict[str, Tuple[Optional[str], Optional[str]]]
        A dictionary with keys as calculation names (e.g. 'sum', 'diff') and
        values as a 2-tuple (rewrite_rule, expression). Both are optional:
        rewrite_rule may be None if not present, and expression may also be None
        if the file has incomplete entries.
    """
    calc_dict: Dict[str, Tuple[Optional[str], Optional[str]]] = {}

    if calc_list_path is None or not os.path.isfile(calc_list_path):
        return calc_dict

    with open(calc_list_path, "r") as f:
        lines = [line.strip() for line in f]

    i = 1  # first line of file should be ignored
    while i < len(lines):
        line = lines[i]

        if not line or line.startswith("#"):
            i += 1
            continue

        calc_name = line
        i += 1

        rewrite_rule: Optional[str] = None
        expression: Optional[str] = None

        while i < len(lines) and (not lines[i] or lines[i].startswith("#")):
            i += 1

        if i < len(lines) and lines[i].startswith("@"):
            rewrite_rule = lines[i][1:].strip()
            i += 1

        while i < len(lines) and (not lines[i] or lines[i].startswith("#")):
            i += 1

        if i < len(lines):
            expression = lines[i]
            i += 1

        calc_dict[calc_name] = (rewrite_rule, expression)

    return calc_dict

parse_calc_pv(edm_pv)

Parse an EDM-style CALC PV reference and extract the calculation name (or inline expression), list of arguments, and whether it's an inline expression (curly braces).

EDM CALC PV examples

• 'CALC\sum(pv1, pv2)'
• 'CALC\{A+B}(pv1, pv2)'
• 'CALC\{(A)}($(P)$(R)Acquire)'

Parameters

edm_pv : str The EDM-style CALC PV string to parse. For example, 'CALC\sum(pv1, pv2)'.

Returns

calc_name_or_expr : str The calculation name (e.g. 'sum') or inline expression (e.g. 'A+B'). arg_list : List[str] The list of arguments, e.g. ['pv1', 'pv2']. is_inline_expr : bool True if the EDM PV used inline curly brace syntax (e.g. '{A+B}'), False otherwise.

Raises

ValueError If the given edm_pv string doesn't match the expected CALC syntax.

Source code in pydmconverter/edm/parser_helpers.py

def parse_calc_pv(edm_pv: str) -> Tuple[str, List[str], bool]:
    """
    Parse an EDM-style CALC PV reference and extract the calculation name (or inline
    expression), list of arguments, and whether it's an inline expression (curly braces).

    EDM CALC PV examples:
      - 'CALC\\sum(pv1, pv2)'
      - 'CALC\\\\{A+B\\}(pv1, pv2)'
      - 'CALC\\\\{(A)\\}($(P)$(R)Acquire)'

    Parameters
    ----------
    edm_pv : str
        The EDM-style CALC PV string to parse. For example, 'CALC\\sum(pv1, pv2)'.

    Returns
    -------
    calc_name_or_expr : str
        The calculation name (e.g. 'sum') or inline expression (e.g. 'A+B').
    arg_list : List[str]
        The list of arguments, e.g. ['pv1', 'pv2'].
    is_inline_expr : bool
        True if the EDM PV used inline curly brace syntax (e.g. '{A+B}'),
        False otherwise.

    Raises
    ------
    ValueError
        If the given edm_pv string doesn't match the expected CALC syntax.
    """

    expr_part, args_part = get_calc_groups(edm_pv)
    name_or_expr = clean_escape_characters(expr_part).strip()
    arg_list = get_calc_arguments(clean_escape_characters(args_part))
    for i in range(len(arg_list)):
        if arg_list[i].startswith("LOC\\"):
            arg_list[i] = loc_conversion(arg_list[i])

    is_inline_expr = False
    if name_or_expr.startswith("{") and name_or_expr.endswith("}"):
        is_inline_expr = True
        name_or_expr = name_or_expr[1:-1]
    return name_or_expr, arg_list, is_inline_expr

parse_color_rule_condition(text)

Parse one colors.list rule condition line, EDM grammar (color_pkg.cc ver4InitFromFile).

[op] number [(&& | ||) [op] number] : result or default : result; a bare number implies =. result is a static colour name, or &&/|| to join this condition with the next one (no colour of its own).

Returns a dict with condition (the text before the colon), color (the result colour name, None for a join), default (always true), terms ([(python_op, value)], one or two), connector ("&&"/"||" between the two terms, or None) and join ("&&"/"||"/None), or None when the line does not follow the grammar.

Source code in pydmconverter/edm/parser_helpers.py

def parse_color_rule_condition(text: str) -> Optional[Dict[str, Any]]:
    """Parse one colors.list rule condition line, EDM grammar (color_pkg.cc ver4InitFromFile).

    ``[op] number [(&& | ||) [op] number] : result`` or ``default : result``; a
    bare number implies ``=``. ``result`` is a static colour name, or ``&&``/``||``
    to join this condition with the next one (no colour of its own).

    Returns a dict with ``condition`` (the text before the colon), ``color`` (the
    result colour name, ``None`` for a join), ``default`` (always true), ``terms``
    (``[(python_op, value)]``, one or two), ``connector`` (``"&&"``/``"||"`` between
    the two terms, or ``None``) and ``join`` (``"&&"``/``"||"``/``None``), or
    ``None`` when the line does not follow the grammar.
    """
    condition_text, sep, _ = text.partition(":")
    tokens = _rule_tokens(text)
    if not sep or not tokens:
        return None
    parsed: Dict[str, Any] = {
        "condition": condition_text.strip(),
        "color": None,
        "default": False,
        "terms": [],
        "connector": None,
        "join": None,
    }
    pos = 0

    def term() -> bool:
        nonlocal pos
        if pos >= len(tokens):
            return False
        token = tokens[pos]
        op = "="
        if token in RULE_OPERATORS:
            op = token
            pos += 1
            if pos >= len(tokens):
                return False
            token = tokens[pos]
        value = _rule_number(token)
        if value is None:
            return False
        parsed["terms"].append((RULE_OPERATORS[op], value))
        pos += 1
        return True

    if tokens[0] == "default":
        parsed["default"] = True
        pos = 1
    else:
        if not term():
            return None
        if pos < len(tokens) and tokens[pos] in RULE_CONNECTORS:
            parsed["connector"] = tokens[pos]
            pos += 1
            if not term():
                return None
    if pos >= len(tokens) or tokens[pos] != ":":
        return None
    pos += 1
    if pos >= len(tokens):
        return None
    result = tokens[pos]
    if result in RULE_CONNECTORS:
        parsed["join"] = result
    else:
        parsed["color"] = result
    return parsed

parse_colors_list(filepath)

Parse an EDM colors.list file into a structured Python dictionary.

Parameters

filepath : str Path to the colors.list file.

Returns

Dict[str, Any] A dictionary representing the parsed content of the colors.list file.

Keys
----
version : Dict[str, int]
    Dictionary containing {"major", "minor", "release"}.
blinkms : int or None
    The blink period in milliseconds.
columns : int or None
    Number of columns in the color palette.
max : int or None
    The maximum RGB component value + 1 (e.g. 256 or 0x10000).
alias : Dict[str, str]
    Maps an alias name to a (static or rule-based) color name.
static : Dict[int, Dict[str, Union[str, List[int]]]]
    Static color definitions keyed by their numeric index.
    Each value is a dictionary containing:
      - "name": str
      - "rgb": List[int]  (3 values) or 6 values if blinking
rules : Dict[int, Dict[str, Any]]
    Rule definitions keyed by their numeric index.
    Each value is a dictionary containing:
      - "name": str
      - "conditions": List[Dict[str, str]]
        Each condition has:
          - "condition": str  (e.g. ">0 && <10" or "default")
          - "color": str
menumap : List[str]
    List of color names as displayed in the color name menu.
alarm : Dict[str, str]
    Alarm color configuration. Keys are alarm states, values are color names.

Notes

• The first non-comment, non-empty line must be the version line: e.g. "4 0 0".
• The parser assumes a well-formed file. If your file structure differs, you may need to handle additional edge cases (e.g. malformed lines, trailing braces, etc.).
• A “blinking” static color has six numeric components for its two RGB states.
• A rule line has the form: rule { ... }.
• The menumap and alarm blocks must each be enclosed in braces.
• The alias lines have the form: alias .

Source code in pydmconverter/edm/parser_helpers.py

def parse_colors_list(filepath: str) -> Dict[str, Any]:
    """
    Parse an EDM `colors.list` file into a structured Python dictionary.

    Parameters
    ----------
    filepath : str
        Path to the `colors.list` file.

    Returns
    -------
    Dict[str, Any]
        A dictionary representing the parsed content of the `colors.list` file.

        Keys
        ----
        version : Dict[str, int]
            Dictionary containing {"major", "minor", "release"}.
        blinkms : int or None
            The blink period in milliseconds.
        columns : int or None
            Number of columns in the color palette.
        max : int or None
            The maximum RGB component value + 1 (e.g. 256 or 0x10000).
        alias : Dict[str, str]
            Maps an alias name to a (static or rule-based) color name.
        static : Dict[int, Dict[str, Union[str, List[int]]]]
            Static color definitions keyed by their numeric index.
            Each value is a dictionary containing:
              - "name": str
              - "rgb": List[int]  (3 values) or 6 values if blinking
        rules : Dict[int, Dict[str, Any]]
            Rule definitions keyed by their numeric index.
            Each value is a dictionary containing:
              - "name": str
              - "conditions": List[Dict[str, str]]
                Each condition has:
                  - "condition": str  (e.g. ">0 && <10" or "default")
                  - "color": str
        menumap : List[str]
            List of color names as displayed in the color name menu.
        alarm : Dict[str, str]
            Alarm color configuration. Keys are alarm states, values are color names.

    Notes
    -----
    - The first non-comment, non-empty line must be the version line: e.g. "4 0 0".
    - The parser assumes a well-formed file. If your file structure differs, you may need to
      handle additional edge cases (e.g. malformed lines, trailing braces, etc.).
    - A “blinking” static color has six numeric components for its two RGB states.
    - A rule line has the form: rule <index> <name> { ... }.
    - The menumap and alarm blocks must each be enclosed in braces.
    - The alias lines have the form: alias <alias_name> <color_name>.
    """

    re_comment = re.compile(r"^\s*#")
    re_setting = re.compile(r"^\s*([a-zA-Z0-9_]+)\s*=\s*([^\s]+)")
    re_alias = re.compile(r"^\s*alias\s+(\S+)\s+(.+)$")

    # Regex for static color definitions:
    # e.g. static 25 Controller { 0 0 65535 }
    # or   static 26 "blinking red" { 65535 0 0 41120 0 0 }
    # Captures: index, name, content inside braces
    re_static = re.compile(r"^\s*static\s+(\d+)\s+\"?([^\"{]+)\"?\s*\{\s*([^}]*)\}")

    # Regex for rule definitions:
    # e.g. rule 100 exampleRule {
    #        =100 || =200 : strange
    #        default      : green
    #      }
    re_rule_header = re.compile(r"^\s*rule\s+(\d+)\s+(.*?){?\s*$")

    parsed_data: Dict[str, Any] = {
        "version": {},
        "blinkms": None,
        "columns": None,
        "max": None,
        "alias": {},
        "static": {},
        "rules": {},
        "menumap": [],
        "alarm": {},
    }

    if filepath is None:
        return parsed_data

    with open(filepath, "r", encoding="utf-8") as f:
        lines = f.readlines()

    def skip_blanks_and_comments(idx: int) -> int:
        while idx < len(lines):
            line_stripped = lines[idx].strip()
            if not line_stripped or re_comment.match(line_stripped):
                idx += 1
            else:
                break
        return idx

    idx = 0
    idx = skip_blanks_and_comments(idx)
    if idx >= len(lines):
        raise ValueError("File is empty or missing version line.")

    first_line = lines[idx].strip()
    idx += 1

    version_parts = first_line.split()
    if len(version_parts) != 3:
        raise ValueError("Version line must have exactly three integers: e.g. '4 0 0'.")

    parsed_data["version"] = {
        "major": int(version_parts[0]),
        "minor": int(version_parts[1]),
        "release": int(version_parts[2]),
    }

    while idx < len(lines):
        line = lines[idx].strip()
        idx += 1

        if not line or re_comment.match(line):
            continue

        match_setting = re_setting.match(line)
        if match_setting:
            key, value_str = match_setting.groups()
            try:
                if value_str.startswith("0x"):
                    value_int = int(value_str, 16)
                else:
                    value_int = int(value_str)
                parsed_data[key] = value_int
            except ValueError:
                parsed_data[key] = value_str
            continue

        match_alias = re_alias.match(line)
        if match_alias:
            alias_name, color_name = match_alias.groups()
            color_name = color_name.strip().strip('"')
            parsed_data["alias"][alias_name] = color_name
            continue

        match_static = re_static.match(line)
        if match_static:
            idx_str, color_name, rgb_str = match_static.groups()
            color_index = int(idx_str)
            color_name = color_name.strip()
            rgb_vals_str = rgb_str.replace(",", " ")
            rgb_vals = rgb_vals_str.split()

            def convert_val(v: str) -> int:
                v = v.strip()
                return int(v, 16) if v.startswith("0x") else int(v)

            rgb_nums = [convert_val(v) for v in rgb_vals]

            parsed_data["static"][color_index] = {
                "name": color_name,
                "rgb": rgb_nums,
            }
            continue

        match_rule = re_rule_header.match(line)
        if match_rule:
            rule_index_str, rule_name_part = match_rule.groups()
            rule_index = int(rule_index_str)
            rule_name_part = rule_name_part.strip()

            if rule_name_part.endswith("{"):
                rule_name_part = rule_name_part[:-1].strip()

            conditions = []
            if "{" not in line:
                idx = skip_blanks_and_comments(idx)

            while idx < len(lines):
                inner_line = _strip_color_comment(lines[idx]).strip()
                idx += 1
                if not inner_line or re_comment.match(inner_line):
                    continue
                if inner_line.startswith("}"):
                    break

                condition = parse_color_rule_condition(inner_line)
                if condition is None:
                    logger.warning(f"Unparseable condition in colors.list rule {rule_index}: '{inner_line}'")
                    continue
                conditions.append(condition)

            parsed_data["rules"][rule_index] = {"name": rule_name_part.strip('"'), "conditions": conditions}
            continue

        if line.startswith("menumap"):
            idx = skip_blanks_and_comments(idx)
            while idx < len(lines):
                inner_line = lines[idx].strip()
                idx += 1
                if inner_line.startswith("}"):
                    break
                if not inner_line or re_comment.match(inner_line):
                    continue
                color_name = inner_line.strip().strip('"')
                parsed_data["menumap"].append(color_name)
            continue

        if line.startswith("alarm"):
            idx = skip_blanks_and_comments(idx)
            while idx < len(lines):
                inner_line = lines[idx].strip()
                idx += 1
                if inner_line.startswith("}"):
                    break
                if not inner_line or re_comment.match(inner_line):
                    continue
                # Split on the FIRST colon only: colour names carry colons of
                # their own ("Monitor: MINOR").
                alarm_state, sep, color_name = inner_line.partition(":")
                if sep:
                    parsed_data["alarm"][alarm_state.strip()] = color_name.strip().strip('"')
            continue

        logging.warning(f"Unrecognized line in colors.list: '{line}'")

    for possible_key in ("blinkms", "columns", "max"):
        if possible_key in parsed_data:
            parsed_data[possible_key] = parsed_data[possible_key]
        else:
            parsed_data[possible_key] = None

    return parsed_data

parse_edm_macros(macro_string)

Parse an EDM macro string into a dictionary for PyDM widgets.

EDM macros are in the format: "KEY1=value1,KEY2=value2,KEY3=value3" This function converts them to a Python dict: {"KEY1": "value1", "KEY2": "value2", "KEY3": "value3"}

Parameters

macro_string : str The EDM macro string to parse (e.g., "P=CAMR:LI20:110,R=:ASYN")

Returns

dict A dictionary containing the parsed macro key-value pairs. Returns an empty dict if the input is empty or None.

Examples

parse_edm_macros("P=CAMR:LI20:110,R=:ASYN") {'P': 'CAMR:LI20:110', 'R': ':ASYN'} parse_edm_macros("DEVICE=IOC:SYS0:1") {'DEVICE': 'IOC:SYS0:1'} parse_edm_macros("") {}

Source code in pydmconverter/edm/parser_helpers.py

def parse_edm_macros(macro_string: str) -> dict:
    """
    Parse an EDM macro string into a dictionary for PyDM widgets.

    EDM macros are in the format: "KEY1=value1,KEY2=value2,KEY3=value3"
    This function converts them to a Python dict: {"KEY1": "value1", "KEY2": "value2", "KEY3": "value3"}

    Parameters
    ----------
    macro_string : str
        The EDM macro string to parse (e.g., "P=CAMR:LI20:110,R=:ASYN")

    Returns
    -------
    dict
        A dictionary containing the parsed macro key-value pairs.
        Returns an empty dict if the input is empty or None.

    Examples
    --------
    >>> parse_edm_macros("P=CAMR:LI20:110,R=:ASYN")
    {'P': 'CAMR:LI20:110', 'R': ':ASYN'}
    >>> parse_edm_macros("DEVICE=IOC:SYS0:1")
    {'DEVICE': 'IOC:SYS0:1'}
    >>> parse_edm_macros("")
    {}
    """
    if not macro_string or not isinstance(macro_string, str):
        return {}

    macro_dict = {}
    macro_string = macro_string.strip()

    if not macro_string:
        return {}

    pairs = _split_macro_pairs(macro_string)

    for pair in pairs:
        pair = pair.strip()
        if not pair:
            continue
        if "=" in pair:
            key, value = pair.split("=", 1)
            key = key.strip()
            value = value.strip()
            if value.startswith('"') and value.endswith('"'):
                value = value[1:-1]
            if value.startswith("'") and value.endswith("'"):
                value = value[1:-1]
            macro_dict[key] = value
        else:
            logger.warning(f"Invalid macro pair format: '{pair}' in macro string: '{macro_string}'")

    return macro_dict

qs_escape(text, plus=True)

Escape a value for the query of a loc:// or calc:// address.

PyDM reads these queries with parse_qs (local_plugin.py and calc_plugin.py UrlToPython), which ends a value at "&", decodes "%XX" and turns "+" into a space. Only those characters are escaped: anything else, macros like ${EDM_W} included, stays as written, since PyDM substitutes macros in the address before it parses it. The calc plugin protects "+" itself (parse_qs(query.replace("+", "%2B"))), so its values pass plus=False.

Parameters

text : str The value as the variable or calc should see it. plus : bool, optional Whether to escape "+" too (the local plugin's queries).

Returns

str The value with "%", "&" and, with plus, "+" percent-encoded.

Source code in pydmconverter/edm/parser_helpers.py

def qs_escape(text: str, plus: bool = True) -> str:
    """
    Escape a value for the query of a loc:// or calc:// address.

    PyDM reads these queries with parse_qs (local_plugin.py and calc_plugin.py
    UrlToPython), which ends a value at "&", decodes "%XX" and turns "+" into a
    space. Only those characters are escaped: anything else, macros like
    ${EDM_W} included, stays as written, since PyDM substitutes macros in the
    address before it parses it. The calc plugin protects "+" itself
    (parse_qs(query.replace("+", "%2B"))), so its values pass plus=False.

    Parameters
    ----------
    text : str
        The value as the variable or calc should see it.
    plus : bool, optional
        Whether to escape "+" too (the local plugin's queries).

    Returns
    -------
    str
        The value with "%", "&" and, with plus, "+" percent-encoded.
    """
    text = text.replace("%", "%25").replace("&", "%26")
    return text.replace("+", "%2B") if plus else text

reformat_calc_expression(exp)

Convert EPICS calc expression operators to Python equivalents.

PyDM's calc plugin evaluates the expr query as a Python expression, so EPICS-only operators must be translated or PyDM raises a SyntaxError when the display is opened.

Conversions: - ^ exponentiation -> ** - # not equal -> != - = equality -> == (leaving <=, >=, !=, == untouched) - && / || -> and / or - !x logical not -> (not x) - cond ? a : b ternary -> (a if cond else b) (handles nesting, also inside parentheses)

Source code in pydmconverter/edm/parser_helpers.py

def reformat_calc_expression(exp):
    """
    Convert EPICS calc expression operators to Python equivalents.

    PyDM's calc plugin evaluates the ``expr`` query as a Python expression, so
    EPICS-only operators must be translated or PyDM raises a SyntaxError when the
    display is opened.

    Conversions:
    - ``^`` exponentiation -> ``**``
    - ``#`` not equal -> ``!=``
    - ``=`` equality -> ``==`` (leaving ``<=``, ``>=``, ``!=``, ``==`` untouched)
    - ``&&`` / ``||`` -> ``and`` / ``or``
    - ``!x`` logical not -> ``(not x)``
    - ``cond ? a : b`` ternary -> ``(a if cond else b)`` (handles nesting, also
      inside parentheses)
    """
    # Exponentiation: ^ -> **
    exp = exp.replace("^", "**")

    # Not equal: # -> !=
    exp = exp.replace("#", "!=")

    # Equality: single = -> ==, without touching <=, >=, !=, ==, :=
    exp = re.sub(r"(?<![<>=!:])=(?!=)", "==", exp)

    # Logical operators
    exp = exp.replace("&&", " and ").replace("||", " or ")
    exp = _convert_calc_not(exp)

    # C-style ternary -> Python conditional expression
    exp = _convert_calc_ternary(exp)

    return exp

replace_calc_and_loc_in_edm_content(edm_content, filepath, calc_list_file=None, calc_reuse_short=True, search_paths=None)

Replace both CALC...(...) and LOC...=... references in the EDM file content with PyDM equivalents. The first time each unique reference appears, the replacement is the full PyDM string; subsequent appearances use the short form.

Parameters

edm_content : str The full text of the EDM file, as a single string. filepath : str path of the given edm file calc_list_file : str, optional An explicit path to a calc.list file used to resolve named CALC PVs. Overrides the default calc.list search locations. calc_reuse_short : bool, optional When True (the PyDM target), the second and later appearances of a calc use the short calc://<id> form (the plugin reuses the registered config). The react/IR target passes False: every appearance carries the full query so the formula hoister can lower each one independently. search_paths : str | os.PathLike | Sequence[str | os.PathLike], optional Extra directories (a single path or a sequence of paths) searched for calc.list (see :func:search_calc_list).

Returns

new_content : str The EDM content after all CALC and LOC references have been replaced. encountered_calcs : Dict[str, Dict[str, str]] A dictionary of all encountered CALC references, mapping the original EDM reference to {"full": ..., "short": ...}. encountered_locs : Dict[str, Dict[str, str]] A dictionary of all encountered LOC references, similarly mapping each unique original LOC reference to "full" and "short" addresses.

Source code in pydmconverter/edm/parser_helpers.py

def replace_calc_and_loc_in_edm_content(
    edm_content: str,
    filepath: str,
    calc_list_file: Optional[str] = None,
    calc_reuse_short: bool = True,
    search_paths: SearchPaths = None,
) -> Tuple[str, Dict[str, Dict[str, str]], Dict[str, Dict[str, str]]]:
    """
    Replace both CALC\\...(...) and LOC\\...=... references in the EDM file content
    with PyDM equivalents. The first time each unique reference appears, the
    replacement is the full PyDM string; subsequent appearances use the short form.

    Parameters
    ----------
    edm_content : str
        The full text of the EDM file, as a single string.
    filepath : str
        path of the given edm file
    calc_list_file : str, optional
        An explicit path to a calc.list file used to resolve named CALC PVs.
        Overrides the default calc.list search locations.
    calc_reuse_short : bool, optional
        When True (the PyDM target), the second and later appearances of a calc
        use the short ``calc://<id>`` form (the plugin reuses the registered
        config). The react/IR target passes False: every appearance carries the
        full query so the formula hoister can lower each one independently.
    search_paths : str | os.PathLike | Sequence[str | os.PathLike], optional
        Extra directories (a single path or a sequence of paths) searched for
        calc.list (see :func:`search_calc_list`).

    Returns
    -------
    new_content : str
        The EDM content after all CALC and LOC references have been replaced.
    encountered_calcs : Dict[str, Dict[str, str]]
        A dictionary of all encountered CALC references, mapping the original
        EDM reference to {"full": ..., "short": ...}.
    encountered_locs : Dict[str, Dict[str, str]]
        A dictionary of all encountered LOC references, similarly mapping each
        unique original LOC reference to "full" and "short" addresses.
    """
    calc_list_path = search_calc_list(filepath, calc_list_file, search_paths)
    calc_dict = parse_calc_list(calc_list_path)

    encountered_calcs: Dict[str, Dict[str, str]] = {}
    encountered_locs: Dict[str, Dict[str, str]] = {}

    calc_pattern = re.compile(r'"(CALC\\\\[^"]+)"')

    def replace_calc_match(match: re.Match) -> str:
        edm_pv = match.group(1)
        if edm_pv not in encountered_calcs:
            try:
                full_url = translate_calc_pv_to_pydm(edm_pv, calc_dict=calc_dict)
            except ValueError as e:
                # Leave the original EDM reference in place so one bad calc
                # does not abort the conversion of the whole file.
                logger.warning(f"Could not translate CALC PV '{edm_pv}': {e}")
                return match.group(0)
            short_url = full_url.split("?", 1)[0]
            encountered_calcs[edm_pv] = {"full": full_url, "short": short_url}
            return full_url
        else:
            return encountered_calcs[edm_pv]["short" if calc_reuse_short else "full"]

    new_content = calc_pattern.sub(replace_calc_match, edm_content)

    # loc_pattern = re.compile(r'LOC\\+[^=]+=[dies]:[^"]*')]
    loc_pattern = re.compile(r'"(LOC\\[^"]+)"')

    def replace_loc_match(match: re.Match) -> str:
        edm_pv = match.group(1)
        if edm_pv not in encountered_locs:
            if "=" not in edm_pv:  # For case when calling pvs (with no =)
                cleaned_pv = re.sub(r"^LOC\\+", "", edm_pv)
                full_url = f"loc://{cleaned_pv}"
                short_url = full_url
            else:
                try:
                    full_url = loc_conversion(edm_pv)  # TODO: remove the ifs later
                except (ValueError, NotImplementedError) as e:
                    # Leave the original EDM reference in place so one bad
                    # local PV does not abort the conversion of the whole file.
                    logger.warning(f"Could not translate LOC PV '{edm_pv}': {e}")
                    return match.group(0)
                if full_url:
                    short_url = full_url.split("?", 1)[0]
                else:
                    full_url, short_url = "", ""
            encountered_locs[edm_pv] = {"full": full_url, "short": short_url}
            return full_url
        elif "=" in edm_pv:
            return encountered_locs[edm_pv]["full"]
        return encountered_locs[edm_pv]["short"]

    new_content = loc_pattern.sub(replace_loc_match, new_content)

    return new_content, encountered_calcs, encountered_locs

resolve_inside(base, name, allowed_roots)

Resolve a file name taken from an untrusted input, confined to allowed roots.

The check looks only at the path, never at whether the file exists, so a rejection says nothing about the filesystem outside the roots.

Parameters

base : str | os.PathLike Directory the name is relative to. name : str The file name as written in the input. allowed_roots : Sequence[Path] Already-resolved directories the result must lie inside (any one of them).

Returns

Path | None (base / name).resolve(), or None when name is absolute (any anchor, which also covers Windows drive and root forms), cannot be resolved (e.g. a NUL byte or a symlink loop), or resolves outside every allowed root (.., or a symlink pointing elsewhere).

Source code in pydmconverter/edm/parser_helpers.py

def resolve_inside(base: Union[str, "os.PathLike[str]"], name: str, allowed_roots: Sequence[Path]) -> Optional[Path]:
    """
    Resolve a file name taken from an untrusted input, confined to allowed roots.

    The check looks only at the path, never at whether the file exists, so a
    rejection says nothing about the filesystem outside the roots.

    Parameters
    ----------
    base : str | os.PathLike
        Directory the name is relative to.
    name : str
        The file name as written in the input.
    allowed_roots : Sequence[Path]
        Already-resolved directories the result must lie inside (any one of them).

    Returns
    -------
    Path | None
        ``(base / name).resolve()``, or None when ``name`` is absolute (any anchor,
        which also covers Windows drive and root forms), cannot be resolved (e.g. a
        NUL byte or a symlink loop), or resolves outside every allowed root (``..``,
        or a symlink pointing elsewhere).
    """
    if Path(name).anchor:
        return None
    try:
        candidate = (Path(base) / name).resolve()
    except (OSError, RuntimeError, ValueError):
        return None
    if any(candidate.is_relative_to(root) for root in allowed_roots):
        return candidate
    return None

rule_static_color(color_data, idx)

The colour a rule index shows when no condition applies, or None.

EDM gives a rule colour the pixel of its FIRST condition that names a result colour (color_pkg.cc, "use first rule condition as static color for rule"), and evalRule returns the rule index itself when nothing matches — so that colour is both the static rendering and the no-match fallback. The returned dict is the static entry's (rgb may carry six components for a blinking colour) plus rule: the rule index.

Source code in pydmconverter/edm/parser_helpers.py

def rule_static_color(color_data: Dict[str, Any], idx: int) -> Optional[Dict[str, Any]]:
    """The colour a rule index shows when no condition applies, or ``None``.

    EDM gives a rule colour the pixel of its FIRST condition that names a result
    colour (color_pkg.cc, "use first rule condition as static color for rule"),
    and ``evalRule`` returns the rule index itself when nothing matches — so that
    colour is both the static rendering and the no-match fallback. The returned
    dict is the static entry's (``rgb`` may carry six components for a blinking
    colour) plus ``rule``: the rule index.
    """
    rule = (color_data or {}).get("rules", {}).get(idx)
    if not rule:
        return None
    for condition in rule.get("conditions", ()):
        name = condition.get("color")
        if name:
            static = static_color_by_name(color_data, name)
            if static is None:
                logger.warning(f"colors.list rule {idx} names unknown colour '{name}'.")
                return None
            return {**static, "rule": idx}
    return None

search_calc_list(file_path, cli_calc_file=None, search_paths=None)

Search for a calc.list file and return its full path, returns None if no calc.list is found.

The search checks the following locations in order:

1. cli_calc_file, if provided.
2. calc.list in the same directory as file_path.
3. calc.list in a config subdirectory next to file_path.
4. calc.list (then config/calc.list) in each of search_paths, in order.
5. $EDMFILES/calc.list.
6. calc.list beside $EDMCOLORFILE.

Parameters

file_path : str The path to a file whose directory will be searched for 'calc.list'. cli_calc_file : str, optional An explicit path to a calc.list file (e.g. from the --calc-list CLI option). If provided and valid, it overrides the other locations. search_paths : str | os.PathLike | Sequence[str | os.PathLike], optional Extra directories to search (a single path or a sequence of paths), e.g. the directory an uploaded screen came from when the file itself was staged elsewhere.

Returns

Optional[str] The full path to the found 'calc.list' file if it exists; otherwise, None.

Source code in pydmconverter/edm/parser_helpers.py

def search_calc_list(
    file_path: str, cli_calc_file: Optional[str] = None, search_paths: SearchPaths = None
) -> Optional[str]:
    """
    Search for a calc.list file and return its full path, returns None if no calc.list is found.

    The search checks the following locations in order:

    1. cli_calc_file, if provided.
    2. calc.list in the same directory as file_path.
    3. calc.list in a config subdirectory next to file_path.
    4. calc.list (then config/calc.list) in each of search_paths, in order.
    5. $EDMFILES/calc.list.
    6. calc.list beside $EDMCOLORFILE.

    Parameters
    ----------
    file_path : str
        The path to a file whose directory will be searched for 'calc.list'.
    cli_calc_file : str, optional
        An explicit path to a calc.list file (e.g. from the --calc-list CLI
        option). If provided and valid, it overrides the other locations.
    search_paths : str | os.PathLike | Sequence[str | os.PathLike], optional
        Extra directories to search (a single path or a sequence of paths), e.g.
        the directory an uploaded screen came from when the file itself was
        staged elsewhere.

    Returns
    -------
    Optional[str]
        The full path to the found 'calc.list' file if it exists; otherwise, None.
    """
    if cli_calc_file and os.path.isfile(cli_calc_file):
        return cli_calc_file

    directory = os.path.dirname(file_path)
    candidates = [
        os.path.join(directory, "calc.list"),
        os.path.join(directory, "config", "calc.list"),
    ]
    for search_dir in normalize_search_paths(search_paths):
        candidates.append(os.path.join(search_dir, "calc.list"))
        candidates.append(os.path.join(search_dir, "config", "calc.list"))

    edmfiles = os.environ.get("EDMFILES", "")
    if edmfiles:
        candidates.append(os.path.join(edmfiles, "calc.list"))

    # A site colors.list usually lives in the EDM config dir, and calc.list
    # sits beside it — so EDMCOLORFILE localizes calc.list too.
    color_file = os.environ.get("EDMCOLORFILE", "")
    if color_file:
        candidates.append(os.path.join(os.path.dirname(color_file), "calc.list"))

    for candidate in candidates:
        if os.path.isfile(candidate):
            return candidate

    return None

search_color_list(cli_color_file=None)

Attempt to find the EDM color file by the following priority:

1. CLI argument (cli_color_file), if provided.
2. EDMCOLORFILE env variable (absolute path).
3. EDMFILES env variable + "colors.list".
4. Default path: "/etc/edm/colors.list".

Parameters

cli_color_file : str or None, optional A file path passed via command line argument. If this is provided and valid, it overrides other checks.

Returns

str or None The path to the EDM color file if found, else None.

Source code in pydmconverter/edm/parser_helpers.py

def search_color_list(cli_color_file=None) -> str | None:
    """
    Attempt to find the EDM color file by the following priority:

    1. CLI argument (cli_color_file), if provided.
    2. EDMCOLORFILE env variable (absolute path).
    3. EDMFILES env variable + "colors.list".
    4. Default path: "/etc/edm/colors.list".

    Parameters
    ----------
    cli_color_file : str or None, optional
        A file path passed via command line argument.
        If this is provided and valid, it overrides other checks.

    Returns
    -------
    str or None
        The path to the EDM color file if found, else None.
    """
    if cli_color_file and os.path.isfile(cli_color_file):
        return cli_color_file

    edmc = os.environ.get("EDMCOLORFILE")
    if edmc and os.path.isfile(edmc):
        return edmc

    edmfiles = os.environ.get("EDMFILES")
    if edmfiles:
        candidate = os.path.join(edmfiles, "colors.list")
        if os.path.isfile(candidate):
            return candidate

    default_path = "/etc/edm/colors.list"
    if os.path.isfile(default_path):
        return default_path

    return None

split_edm_path_list(value)

Split an EDM path list such as EDMDATAFILES into its directories.

EDM separates directories with :, as in /opt/edm/display:/opt/edm/shared. ; separates them too, and a Windows drive (a single letter before :\ or :/, as in C:\edm) stays one entry. Empty entries are dropped.

As in EDM, a leading = (its mark for the default directory) is not part of the directory, and the : of an http:// or https:// entry does not split it. Such a URL entry is left out: EDM reads it over the network, the converter reads local files only.

Source code in pydmconverter/edm/parser_helpers.py

def split_edm_path_list(value: str) -> List[str]:
    """
    Split an EDM path list such as ``EDMDATAFILES`` into its directories.

    EDM separates directories with ``:``, as in ``/opt/edm/display:/opt/edm/shared``.
    ``;`` separates them too, and a Windows drive (a single letter before ``:\\`` or ``:/``,
    as in ``C:\\edm``) stays one entry. Empty entries are dropped.

    As in EDM, a leading ``=`` (its mark for the default directory) is not part of the
    directory, and the ``:`` of an ``http://`` or ``https://`` entry does not split it.
    Such a URL entry is left out: EDM reads it over the network, the converter reads
    local files only.
    """
    directories: List[str] = []
    for chunk in value.split(";"):
        parts = chunk.split(":")
        i = 0
        while i < len(parts):
            part = parts[i]
            # app_pkg.cc: "= means use this a default"; the "=" is stripped and the
            # directory is still searched.
            if part.startswith("="):
                part = part[1:]
            # app_pkg.cc fixupHttpPart keeps these four spellings of a URL scheme whole.
            if part in ("http", "HTTP", "https", "HTTPS") and i + 1 < len(parts) and parts[i + 1].startswith("//"):
                i += 2
                continue
            if len(part) == 1 and part.isalpha() and i + 1 < len(parts) and parts[i + 1][:1] in ("\\", "/"):
                part = f"{part}:{parts[i + 1]}"
                i += 1
            if part:
                directories.append(part)
            i += 1
    return directories

static_color_by_name(color_data, name)

The static colour called name (EDM resolves rule results by name, statics only).

Source code in pydmconverter/edm/parser_helpers.py

def static_color_by_name(color_data: Dict[str, Any], name: str) -> Optional[Dict[str, Any]]:
    """The static colour called ``name`` (EDM resolves rule results by name, statics only)."""
    for color in (color_data or {}).get("static", {}).values():
        if color.get("name") == name:
            return color
    return None

translate_calc_pv_to_pydm(edm_pv, calc_dict=None, default_prefix='ca://')

Translate an EDM-style CALC PV (e.g., 'CALC\sum(pv1, pv2)') into a PyDM calc plugin address, e.g.:

calc://my_variable_name?A=channel://pv1&B=channel://pv2&expr=A+B

Parameters

edm_pv : str The CALC PV in EDM syntax. For instance, "CALC\sum(pv1, pv2)" or "CALC{A-B}(myPv, 10.5)". calc_dict : dict, optional A dictionary mapping calculation names to (rewrite_rule, expression). Typically from parse_calc_list(). This is required if the CALC PV references a named calc (e.g. 'sum') that is defined in a calc.list file. If the CALC PV uses an inline expression ({A+B}), this dictionary may be omitted. default_prefix : str, optional A prefix to apply to each argument if it doesn't already include a protocol. Defaults to 'channel://'.

Returns

str A PyDM calc plugin address string in the format: 'calc://?A=channel://pv1&B=channel://pv2&expr=A+B'.

Raises

ValueError If the named calculation does not exist in the provided calc_dict.

Source code in pydmconverter/edm/parser_helpers.py

def translate_calc_pv_to_pydm(
    edm_pv: str,
    calc_dict: Optional[Dict[str, Tuple[Optional[str], Optional[str]]]] = None,
    default_prefix: str = "ca://",
) -> str:
    """
    Translate an EDM-style CALC PV (e.g., 'CALC\\sum(pv1, pv2)') into
    a PyDM calc plugin address, e.g.:

      calc://my_variable_name?A=channel://pv1&B=channel://pv2&expr=A+B

    Parameters
    ----------
    edm_pv : str
        The CALC PV in EDM syntax. For instance, "CALC\\sum(pv1, pv2)"
        or "CALC\\{A-B}(myPv, 10.5)".
    calc_dict : dict, optional
        A dictionary mapping calculation names to (rewrite_rule, expression).
        Typically from `parse_calc_list()`. This is required if the CALC PV
        references a named calc (e.g. 'sum') that is defined in a calc.list file.
        If the CALC PV uses an inline expression ({A+B}), this dictionary
        may be omitted.
    default_prefix : str, optional
        A prefix to apply to each argument if it doesn't already include a protocol.
        Defaults to 'channel://'.

    Returns
    -------
    str
        A PyDM calc plugin address string in the format:
        'calc://<identifier>?A=channel://pv1&B=channel://pv2&expr=A+B'.

    Raises
    ------
    ValueError
        If the named calculation does not exist in the provided `calc_dict`.
    """
    if calc_dict is None:
        calc_dict = {}
    name_or_expr, arg_list, is_inline_expr = parse_calc_pv(edm_pv)

    if is_inline_expr:
        expression = name_or_expr
        identifier = "calc"
    else:
        calc_name = name_or_expr
        if calc_name == "sum2":  # convert sum2 to sum (sum2 is not in calc_dict)
            calc_name = "sum"
        if calc_name not in calc_dict:
            logger.debug(f"calc_dict contents: {calc_dict}")
            raise ValueError(f"Calculation '{calc_name}' is not defined in calc_dict. {arg_list}")
            # logger.warning(f"Calculation '{calc_name}' is not defined in calc_dict. {arg_list}")
            # return "failed CALC"
        rewrite_rule, expression = calc_dict[calc_name]
        if expression is None:
            raise ValueError(f"Calculation '{calc_name}' in calc_dict has no expression defined.")

        if rewrite_rule:
            arg_list = apply_rewrite_rule(rewrite_rule, arg_list)

        identifier = calc_name

    expression = reformat_calc_expression(expression)
    letters = "ABCDEFGHIJKL"
    var_map = {}
    for i, arg in enumerate(arg_list):
        if i < len(letters):
            var_map[letters[i]] = arg

    # A numeric argument is a constant, not a PV (CALC_ProcessVariable,
    # calc_pv_factory.cc). PyDM would wait for a channel named "ca://15" to
    # connect and never evaluate, so the number goes into the expression.
    for letter, arg_val in list(var_map.items()):
        if _CALC_CONSTANT.match(arg_val):
            del var_map[letter]
            # strtod reads "08" as 8, but Python rejects a leading zero in an integer.
            value = re.sub(r"^([+-]?)0+(?=\d)", r"\1", arg_val)
            value = f"({value})" if value[0] in "+-" else value
            expression = re.sub(rf"(?<!\$\{{)\b{letter}\b", value, expression)

    query_pairs = []
    for letter, arg_val in var_map.items():
        if "://" not in arg_val:
            arg_val = f"{default_prefix}{arg_val}"
        query_pairs.append(f"{letter}={qs_escape(arg_val, plus=False)}")

    query_pairs.append(f"expr={qs_escape(expression, plus=False)}")

    query_str = "&".join(query_pairs)
    pydm_calc_address = f"calc://{_calc_identifier(identifier, query_str)}?{query_str}"

    return pydm_calc_address

vis_limit(attr, value, warnings)

One EDM visMin/visMax string -> the number EDM compares against.

EDM stores both as strings and evaluates them with atof() after macro substitution, so a missing or non-numeric value (a PV name, "MAJOR") counts as 0 and a numeric prefix ("1`", "0x80") counts as that number. A value that starts with a macro depends on the caller's substitution and cannot be evaluated at convert time: None (the caller drops that visibility rule).

Source code in pydmconverter/edm/parser_helpers.py

def vis_limit(attr: str, value: Any, warnings: list[str]) -> float | None:
    """One EDM ``visMin``/``visMax`` string -> the number EDM compares against.

    EDM stores both as strings and evaluates them with ``atof()`` after macro
    substitution, so a missing or non-numeric value (a PV name, "MAJOR") counts
    as 0 and a numeric prefix ("1`", "0x80") counts as that number. A value that
    *starts* with a macro depends on the caller's substitution and cannot be
    evaluated at convert time: ``None`` (the caller drops that visibility rule).
    """
    if value is None:
        return 0.0
    if isinstance(value, bool):
        text = ""  # a bare "visMin" line (no value) parses as True
    elif isinstance(value, (int, float)):
        return float(value)
    else:
        text = str(value)
    if text.lstrip().startswith(("${", "$(")):
        warnings.append(
            f"EDM {attr} '{text}' depends on a macro and cannot be evaluated at convert time; "
            "visibility rule dropped (widget always shown)"
        )
        return None
    number = edm_atof(text)
    if not math.isfinite(number):
        warnings.append(f"EDM {attr} '{text}' is not a finite number; visibility rule dropped (widget always shown)")
        return None
    try:
        exact = float(text)
    except ValueError:
        exact = None
    if exact != number:
        shown = int(number) if number.is_integer() else number
        warnings.append(f"EDM {attr} '{text}' is not a plain number; evaluated as {shown} (EDM atof semantics)")
    return number

vis_range(properties, warnings)

An EDM object's (visMin, visMax) as the numbers EDM compares against (see :func:vis_limit), or None when a limit cannot be evaluated at convert time: the caller drops the visibility rule, and warnings says why.

EDM shows the object while visMin <= value < visMax. A missing limit is 0, so a visPv without limits never shows ([0, 0) holds no value), or always with visInvert.

Source code in pydmconverter/edm/parser_helpers.py

def vis_range(properties: Dict[str, Any], warnings: List[str]) -> tuple[float, float] | None:
    """An EDM object's ``(visMin, visMax)`` as the numbers EDM compares against (see
    :func:`vis_limit`), or None when a limit cannot be evaluated at convert time:
    the caller drops the visibility rule, and ``warnings`` says why.

    EDM shows the object while ``visMin <= value < visMax``. A missing limit is 0,
    so a visPv without limits never shows ([0, 0) holds no value), or always with
    visInvert.
    """
    low = vis_limit("visMin", properties.get("visMin"), warnings)
    high = vis_limit("visMax", properties.get("visMax"), warnings) if low is not None else None
    if low is None or high is None:
        return None
    return low, high