merger.py

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

Introduction

The merger.py file implements the bulk of logic needed to perform YAML, JSON, and compatible document merging. An instance of this class effectively wraps a document along with caller-specified custom merging configuration rules, enabling merge operations against the wrapped document. You do not need a Processor to merge documents.

See yaml-merge for a deep dive into using this class' capabilities via a reference implementation command-line tool.

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

Public API

Initialization

This class' constructor has the following signature and documentation:

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

        Parameters:
        1. logger (ConsolePrinter) Instance of ConsoleWriter or subclass
        2. lhs (Any) The prime left-hand-side parsed YAML data
        3. config (MergerConfig) User-defined document merging rules

        Returns:  N/A

        Raises:  N/A
        """

A logger is mandatory because document merging can encounter issues. Feedback about such issues are sent to the logging facility. 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 lhs (Left Hand Side) is the target YAML, JSON, or compatible document after it has already been parsed by the ruamel.yaml library. This is the document into which all further documents will be merged. 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].

A config -- an instance of MergerConfig -- must be provided. This dictates how the document merge is to be performed.

Properties

Instances of Merger support the following properties:

• data: Access or mutate the document being merged into (the LHS document).

Public Instance Methods

The Merger class exposes these capabilities against the wrapped LHS document:

• merge_with:

    def merge_with(self, rhs: Any) -> None:
        """
        Merge this document with another.

        Parameters:
        1. rhs (Any) The document to merge into this one.

        Returns:  N/A

        Raises:
        - `MergeException` when a clean merge is impossible.
        """

• prepare_for_dump:

    def prepare_for_dump(
        self, yaml_writer: Any, output_file: str = ""
    ) -> OutputDocTypes:
        """
        Prepare this merged document and its writer for final rendering.

        This coalesces the YAML writer's settings to, in particular,
        distinguish between YAML and JSON.  It will also force demarcation of
        every String key and value within the document when the output will be
        JSON.

        Parameters:
        1. yaml_writer (ruamel.yaml.YAML) The YAML document writer

        Returns:  (OutputDocTypes) One of:
          * OutputDocTypes.JSON:  The document and yaml_writer are JSON format.
          * OutputDocTypes.YAML:  The document and yaml_writer are YAML format.
        """