yamlpath.py

1. Introduction
2. Public API
   1. Initialization
   2. Supported Operators
   3. Properties
   4. Other Public Instance Methods
   5. Public Static Methods

Introduction

The yamlpath.py file implements YAML Path parsing pursuant to the YAML Path standard. YAML Paths can be compared to each other, queried for certain details, and modified in various ways.

The parsing of a YAML Path string is lazy; it is not performed until the segments of the YAML Path are queried. This parsing occurs only once.

This class is found in the following name-space: yamlpath.YAMLPath

Public API

Initialization

This class' constructor has the following signature and documentation:

    def __init__(self, yaml_path: Union["YAMLPath", str, None] = "",
                 pathsep: PathSeperators = PathSeperators.AUTO) -> None:
        """
        Instantiate this class into an object.

        Parameters:
        1. yaml_path (Union["YAMLPath", str, None]) The YAML Path to parse or
           copy
        2. pathsep (PathSeperators) Forced YAML Path segment separator; set
           only when automatic inference fails

        Returns:  N/A

        Raises:  N/A
        """

A YAMLPath instance is initialized as follows:

• From a String: my_path = YAMLPath("some.yaml.path")
• From another YAMLPath: path_copy = YAMLPath(my_path)
• From nothing: null_path = YAMLPath(None)

The optional pathsep positional argument is not required unless the parser infers the wrong segment separator, which is extremely rare and usually due to malformed or irregular YAML Paths, like a dot-separated path for which the first segment happens to start with an unescaped forward-slash or a forward-slash separated YAML Path for which the first character is not a forward-slash.

Supported Operators

Instances of YAMLPath support the following operators:

• LHS == RHS: Indicate whether the left- and right-hand terms are the same path, ignoring differences in their segment separator
• not LHS == RHS: Indicate whether the left- and right-hand terms are not the same path, ignoring differences in their segment separator
• +: NON-MUTATING addition of a new -- pre-escaped -- segment to the LHS YAMLPath; the new YAMLPath is returned, as in: new_yaml_path = LHS + pre_escaped_path_segment; use YAMLPath.escape_path_section(...) to pre-escape the entire new segment or a user-controlled part (section) of it

Properties

Instances of YAMLPath support the following properties:

• original: Access or mutate the String representation of this YAMLPath; parsing of any new value will not occur until needed
• seperator [sic]: Access or mutate the path separator used whenever the YAML Path is "stringified" (usually for printing)
• escaped: (READ-ONLY) Access the parsed, processor-ready segments of the YAML Path
• unescaped: (READ-ONLY) Access the parsed, print-ready segments of the YAML Path
• is_root: (READ-ONLY) Indicates whether the YAML Path points to the document root

Other Public Instance Methods

Instances of YAMLPath support these additional publicly-accessible methods:

• append: (MUTATING) Append a new, pre-escaped YAML Path segment to the present YAML Path, changing it in-place; use YAMLPath.escape_path_section(...) to pre-escape the entire new segment or a user-controlled part (section) of it. This method's signature and documentation follow:

    def append(self, segment: str) -> "YAMLPath":
        """
        Append a new -- pre-escaped -- segment to this YAML Path.

        Parameters:
        1. segment (str) The new -- pre-escaped -- segment to append to this
           YAML Path.  Do NOT include any seperator with this value; it will be
           added for you.

        Returns:  (YAMLPath) The adjusted YAMLPath
        """

• pop: (MUTATING) Remove and access the last segment of the present YAML Path. This method's signature and documentation include:

    def pop(self) -> PathSegment:
        """
        Pop the last segment off this YAML Path.

        This mutates the YAML Path and returns the removed segment PathSegment.

        Returns:  (PathSegment) The removed segment
        """

Public Static Methods

The YAMLPath class provides the following public static methods:

• ensure_escaped: A general utility method which performs simple String substitution to replace every occurrence of a set of characters with their escaped-variant. This method's signature and documentation are:

    @staticmethod
    def ensure_escaped(value: str, *symbols: str) -> str:
        r"""
        Escape all instances of a symbol within a value.

        Ensures all instances of a symbol are escaped (via \) within a value.
        Multiple symbols can be processed at once.

        Parameters:
        1. value (str) The String in which to escape special characters
        2. *symbols (str) List of special characters to escape

        Returns:  (str) `value` with all `symbols` escaped
        """

• escape_path_section: Another utility method which is used against sections of a YAML Path segment -- like the portion of a segment before or between [] characters but excluding the [] pair -- by employing ensure_escaped to escape every character that has a special meaning to the YAML Path parser. In other words, if you needed to add a new segment to a YAML Path via + or .append(...), you'd use this utility method to pre-escape the sections of the new segment which could contain special characters. Take for example: new_path = my_path + "[{}]".format(YAMLPath.escape_path_section(my_search_expression, my_path.seperator)). Had you attempted new_path = my_path + YAMLPath.escape_path_section("[{}]".format(my_search_expression), my_path.seperator), you would incorrectly escape the required [] pair, which would break the Search Expression. The signature and documentation for this method include:

    @staticmethod
    def escape_path_section(section: str, pathsep: PathSeperators) -> str:
        """
        Escape all special symbols present within a YAML Path segment.

        Renders inert via escaping all symbols within a string which have
        special meaning to YAML Path.  The resulting string can be consumed as
        a YAML Path section without triggering unwanted additional processing.

        Parameters:
        1. section (str) The portion of a YAML Path segment to escape
        2. pathsep (PathSeperators) The YAML Path segment seperator symbol to
           also escape, when present

        Returns:  (str) `section` with all special symbols escaped
        """

• strip_path_prefix: A utility method which removes a given YAML Path prefix from another YAML Path. This is helpful whenever you need to do something with the tail end of a YAML Path, having removed a known prefix. This method has the following signature and documentation:

    @staticmethod
    def strip_path_prefix(path: "YAMLPath", prefix: "YAMLPath") -> "YAMLPath":
        """
        Remove a prefix from a YAML Path.

        Parameters:
        1. path (YAMLPath) The path from which to remove the prefix.
        2. prefix (YAMLPath) The prefix to remove (except "/").

        Returns:  (YAMLPath) The trimmed YAML Path.
        """