processor.py

1. Introduction
2. Public API
   1. Initialization
   2. Public Instance Methods

Introduction

The processor.py file implements the bulk of logic for accessing or manipulating YAML, JSON, and compatible data using YAML Paths. A Processor instance effectively wraps a YAML, JSON, or compatible document and provides for methods of accessing and mutating nodes within.

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

Public API

Initialization

This class' constructor has the following signature and documentation:

    def __init__(self, logger: ConsolePrinter, data: Any) -> None:
        """
        Instantiate this class into an object.

        Parameters:
        1. logger (ConsolePrinter) Instance of ConsoleWriter or subclass
        2. data (Any) Parsed YAML data

        Returns:  N/A

        Raises:  N/A
        """

A logger is mandatory because data processing can generate not only the desired data or outcome, but also very specific feedback as to why an operation either yielded nothing or crashed. If you really want to completely mute all such feedback, just subclass ConsolePrinter with a version having the same public API but for which the public methods are only stubs.

The data is the YAML, JSON, or compatible document after it has already been parsed by the ruamel.yaml library. The most convenient means of acquiring this data is to utilize the yamlpath.common.Parsers.get_yaml_data(...) or yamlpath.common.Parsers.get_yaml_multidoc_data(...) static methods [documentation link TBD].

Public Instance Methods

The Processor class exposes these capabilities against the wrapped data:

• alias_gathered_nodes:

    def alias_gathered_nodes(
        self, gathered_nodes: List[NodeCoords],
        anchor_path: Union[YAMLPath, str], **kwargs: Any
    ) -> None:
        """
        Assign a YAML Anchor to zero or more YAML Alias nodes.

        Parameters:
        1. gathered_nodes (List[NodeCoords]) The pre-gathered nodes to assign
        2. anchor_path (Union[YAMLPath, str]) YAML Path to the source Anchor

        Keyword Arguments:
        * pathsep (PathSeperators) Forced YAML Path segment seperator; set
          only when automatic inference fails;
          default = PathSeperators.AUTO
        * anchor_name (str) Override automatic anchor name; use this, instead

        Returns:  N/A

        Raises:  N/A
        """

• alias_nodes:

    def alias_nodes(
        self, yaml_path: Union[YAMLPath, str],
        anchor_path: Union[YAMLPath, str], **kwargs: Any
    ) -> None:
        """
        Gather and assign YAML Aliases to nodes at YAML Path in data.

        Parameters:
        1. yaml_path (Union[YAMLPath, str]) The YAML Path to all target nodes
           which will become Aliases to the Anchor node specified via
           `anchor_path`.
        2. anchor_path (Union[YAMLPath, str]) The YAML Path to a single source
           anchor node; specifying any path which points to more than one node
           will result in a YAMLPathException because YAML does not define
           Aliases for more than one Anchor.

        Keyword Arguments:
        * pathsep (PathSeperators) Forced YAML Path segment seperator; set
          only when automatic inference fails;
          default = PathSeperators.AUTO
        * anchor_name (str) Override the Alias name to any non-empty name you
          set; attempts to re-use an existing Anchor name will result in a
          YAMLPathException.

        Returns:  N/A

        Raises:
            - `YAMLPathException` when YAML Path is invalid
        """

• delete_gathered_nodes:

    def delete_gathered_nodes(self, gathered_nodes: List[NodeCoords]) -> None:
        """
        Delete pre-gathered nodes.

        Parameters:
        1. gathered_nodes (List[NodeCoords]) The pre-gathered nodes to delete.
        """

• delete_nodes:

    def delete_nodes(
        self, yaml_path: Union[YAMLPath, str], **kwargs: Any
    ) -> Generator[NodeCoords, None, None]:
        """
        Gather and delete nodes at YAML Path in data.

        Parameters:
        1. yaml_path (Union[YAMLPath, str]) The YAML Path to evaluate

        Keyword Arguments:
        * pathsep (PathSeperators) Forced YAML Path segment seperator; set
          only when automatic inference fails;
          default = PathSeperators.AUTO

        Returns:  (Generator) Affected NodeCoords before they are deleted

        Raises:
            - `YAMLPathException` when YAML Path is invalid
        """

• get_nodes:

    def get_nodes(
        self, yaml_path: Union[YAMLPath, str], **kwargs: Any
    ) -> Generator[Any, None, None]:
        """
        Get nodes at YAML Path in data.

        Parameters:
        1. yaml_path (Union[YAMLPath, str]) The YAML Path to evaluate

        Keyword Arguments:
        * mustexist (bool) Indicate whether yaml_path must exist
          in data prior to this query (lest an Exception be raised);
          default=False
        * default_value (Any) The value to set at yaml_path should
          it not already exist in data and mustexist is False;
          default=None
        * pathsep (PathSeperators) Forced YAML Path segment seperator; set
          only when automatic inference fails;
          default = PathSeperators.AUTO

        Returns:  (Generator) The requested YAML nodes as they are matched

        Raises:
            - `YAMLPathException` when YAML Path is invalid
        """

• set_value:

    def set_value(
        self, yaml_path: Union[YAMLPath, str], value: Any, **kwargs
    ) -> None:
        """
        Set the value of zero or more nodes at YAML Path in YAML data.

        Parameters:
        1. yaml_path (Union[Path, str]) The YAML Path to evaluate
        2. value (Any) The value to set

        Keyword Arguments:
        * mustexist (bool) Indicate whether yaml_path must exist
          in data prior to this query (lest an Exception be raised);
          default=False
        * value_format (YAMLValueFormats) The demarcation or visual
          representation to use when writing the data;
          default=YAMLValueFormats.DEFAULT
        * pathsep (PathSeperators) Forced YAML Path segment seperator; set
          only when automatic inference fails;
          default = PathSeperators.AUTO
        * tag (str) Custom data-type tag to assign

        Returns:  N/A

        Raises:
            - `YAMLPathException` when YAML Path is invalid
        """

• tag_gathered_nodes:

    def tag_gathered_nodes(
        self, gathered_nodes: List[NodeCoords], tag: str
    ) -> None:
        """
        Assign a data-type tag to a set of nodes.

        Parameters:
        1. gathered_nodes (List[NodeCoords]) The nodes to affect
        2. tag (str) The tag to assign

        Returns:  N/A
        """

• tag_nodes:

    def tag_nodes(
        self, yaml_path: Union[YAMLPath, str], tag: str, **kwargs: Any
    ) -> None:
        """
        Gather and assign a data-type tag to nodes at YAML Path in data.

        Parameters:
        1. yaml_path (Union[YAMLPath, str]) The YAML Path to evaluate
        2. tag (str) The tag to assign

        Keyword Arguments:
        * pathsep (PathSeperators) Forced YAML Path segment seperator; set
          only when automatic inference fails;
          default = PathSeperators.AUTO

        Returns:  N/A

        Raises:
        - `YAMLPathException` when YAML Path is invalid
        """