:py:mod:`yaml`
==============

.. py:module:: yaml

.. autoapi-nested-parse::

   Modification of the yaml loader for E3.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   yaml.OrderedDictYAMLLoader
   yaml.CaseParser



Functions
~~~~~~~~~

.. autoapisummary::

   yaml.load_ordered
   yaml.load_with_config
   yaml.load_with_regexp_table



.. py:exception:: YamlError


   Bases: :py:obj:`Exception`

   Exception raised for YAML operations errors.


.. py:class:: OrderedDictYAMLLoader(stream: IO[str])


   Bases: :py:obj:`Loader`

   A YAML loader that loads mappings into ordered dictionaries.

   The loader also support the !include constructor that allows
   inclusion of yaml files into another yaml

   .. py:method:: yaml_include(node: nodes.Node) -> collections.OrderedDict

      Include another YAML file.

      :param node: YAML node containing the filename


   .. py:method:: construct_yaml_map(node: nodes.Node) -> collections.abc.Generator[collections.OrderedDict, None, None]

      Construct YAML map as OrderedDict.

      :param node: YAML node


   .. py:method:: construct_mapping(node: nodes.Node, deep: bool = False) -> collections.OrderedDict

      Construct mapping preserving order.

      :param node: YAML node
      :param deep: whether to perform deep construction



.. py:function:: load_ordered(filename: str) -> collections.OrderedDict

   Load a .yaml file, keep the file order.

   :param filename: path to YAML file


.. py:class:: CaseParser(initial_config: dict, case_prefix: str = 'case_')


   Parse case statements in an OrderedDict.

   Each time a key starting with ``case_`` (or the prefix you choose) if
   found, in a block mapping, the value of the sub block matching the key
   value is added to the result dictionary.

   For instance: with an initial config
   ``{'param1': 'full', 'param2': 'short'}``, the result of the parsing of:

   .. code-block:: yaml

       {'case_param1': {
           'full': {
               'case_param2': {
                   'full': {'a': 2, 'b': 1, 'c': 'content'},
                   'short': {'y': 0, 'c': ''}}},
           'short': {
               'case_param2': {
                   'full': {'a': 9, 'b': 5, 'c': 'default'},
                   'short': {'y': 3, 'c': ''}}}},
        'value1': 10,
        'value2': '%(c)s',
        'case_param2' : {
               'f.*l': {'value3': 30, 'a': 42}}}

   is ``{'y': 0, 'c': '', 'value2': '', 'value1': 10}``

   and with ``{'param1': 'short', 'param2': 'full'}`` we get:

   .. code-block:: yaml

         {'a': 42, 'c': 'default', 'b': 5, 'value3': 30,
          'value2': 'default', 'value1': 10}

   Note that values can be redefined and that you can add a python regexp, as
   supported by the `re` module, in your case values.

   .. py:method:: __parse_case(case_key: str, data: dict) -> Any

      Parse a case statement.

      :param case_key: the variable on which the case is evaluated
      :param data: the dictionary of case conditions

      :return: the value of the matched element or None


   .. py:method:: __format_value(value: Any) -> Any

      Format a value.

      :param value: the value to be formatted

      :return: the result of the expansion


   .. py:method:: __update_state(key: str, value: Any, cursor: Any, prefix: tuple) -> None

      Update state.

      :param key: the key to modify. Leading or trailing '+' in the key name
          are interpreted respectively as append and prepend operators.
          For dictionaries these operators are interpreted as an update
          on the original value.
      :param value: the new value
      :param cursor: the object to be updated
      :param prefix: a tuple of string that gives the position of cursor in
          self.__state. This is used only for debugging purposes


   .. py:method:: parse(data: Any) -> Any

      Parse.

      :param data: a python object. Note that dictionaries in that structure
          should be OrderedDict.

      :return: a new python object after expansion of case statements and
          formatting of values


   .. py:method:: __parse(data: Any, cursor: Any, prefix: tuple) -> Any

      Parse (internal).

      :param data: a python object. Note that dictionaries in that structure
          should be OrderedDict.
      :param cursor: a ref to a substructure of self.__state
      :param prefix: the current location in self.__state (a tuple of keys)

      :return: the new cursor object



.. py:function:: load_with_config(filename: str | list[str], config: dict) -> Any

   Load yaml config files with case statement handling.

   :param filename: a path or list of path. When a list of path
       is given, config files are loaded in order each one
       updating the result of the previous parsing.
   :param config: initial state

   :return: the final object


.. py:function:: load_with_regexp_table(filename: str, selectors: list[str], data: dict) -> dict

   Load a yaml file using regexp tables.

   :param filename: the yaml file to load
   :param selectors: a list of string that will be used to match the regexps
       in table
   :param data: a dictionary used to replace part of value content

   This function expect a yaml file that has the following format::

       key1:
           [['regexp1_1', ..., 'regexp1_n', value],
            ['regexp2_1', ..., 'regexp2_n', value],...

       key2:
           ...

   The returned dictionary will have key1, key2, ... as keys. For each key
   the value is the last element of the first sublist for which the n first
   first regexp do match, strings in selectors list. So in the yaml file each
   sublist associated with each key should have exactly ``len(selectors) + 1``
   elements.