Hierarchical Yaml Python Config

Common errors

• ImportError: No module named 'yaml' (or ImportError: No module named yaml)

  cause The underlying YAML parsing library, PyYAML, is a required dependency but was not installed in the environment. This often occurs when `hiyapyco` is installed without its dependencies being correctly resolved. [8]
  fix Ensure PyYAML is installed by running `pip install PyYAML` or simply reinstalling `hiyapyco` to allow pip to resolve dependencies: `pip install hiyapyco`.

• hiyapyco.HiYaPyCoImplementationException: '{{ my_undefined_var }}' - UndefinedError: 'my_undefined_var' is undefined

  cause This error occurs during Jinja2 interpolation when a variable referenced in the YAML (e.g., `{{ my_undefined_var }}`) does not exist in the provided context, and the Jinja2 environment is configured for strict undefined variable handling. [1]
  fix Provide a value for the missing variable or configure `hiyapyco`'s Jinja2 environment to handle undefined variables gracefully, e.g., by setting `hiyapyco.jinja2env = Environment(undefined=DebugUndefined)` before loading YAML. [1]

• Lists are replaced instead of being merged when loading multiple YAML files.

  cause By default, hiyapyco's load operation replaces entire lists from earlier files with lists from later files, rather than merging their contents. [7]
  fix To achieve list merging (concatenation for simple lists, deep merge for lists of dicts), use `method=hiyapyco.METHOD_MERGE` and/or `mergelists=True` in your `hiyapyco.load` call. For example: `hiyapyco.load('file1.yaml', 'file2.yaml', method=hiyapyco.METHOD_MERGE, mergelists=True)`.

Warnings

• breaking Python 2 support was officially dropped in version 0.5.0. Projects still using Python 2 must use an older version of hiyapyco (pre-0.5.0). [4]
  Fix: Upgrade to Python 3 or pin hiyapyco version to <0.5.0.
• gotcha When using Jinja2 interpolation, if `StrictUndefined` is configured for the Jinja2 environment (either explicitly or via default settings for certain operations), referencing an undefined variable in the YAML will raise a `hiyapyco.HiYaPyCoImplementationException` wrapped around a `jinja2.UndefinedError`. [1]
  Fix: Ensure all interpolated variables are defined, or set `hiyapyco.jinja2env = Environment(undefined=DebugUndefined)` before loading to make undefined variables appear as empty strings without errors. [1]
• gotcha By default, lists are replaced rather than merged when combining YAML files. To merge lists of dictionaries, you must explicitly set `mergelists=True` or use `method=hiyapyco.METHOD_MERGE`. Simple lists are concatenated with `METHOD_MERGE`. [1, 3, 7]
  Fix: Pass `mergelists=True` or `method=hiyapyco.METHOD_MERGE` to the `hiyapyco.load()` function to enable list merging behavior. Example: `hiyapyco.load('file1.yaml', 'file2.yaml', method=hiyapyco.METHOD_MERGE, mergelists=True)`.
• gotcha The `none_behavior` parameter (introduced in 0.7.0) defaults to `NONE_BEHAVIOR_DEFAULT`, which attempts to merge `None` and may fail. If `None` values should override or be ignored, this needs to be explicitly set. [3]
  Fix: Specify `none_behavior=hiyapyco.NONE_BEHAVIOR_OVERRIDE` (None overrides other values) or `none_behavior=hiyapyco.NONE_BEHAVIOR_IGNORE` (None is ignored) when calling `hiyapyco.load()`. [3]

Install

• pip install hiyapyco Install stable release

Imports

• hiyapyco

  import hiyapyco

Quickstart

This quickstart demonstrates loading and merging two YAML documents provided as strings. It uses `hiyapyco.METHOD_MERGE` for a deep merge and enables Jinja2 interpolation to resolve variables like `{{ first }}`. The resulting merged configuration is then pretty-printed. [1, 3]

import hiyapyco
import pprint

yaml1_str = """
first: first element
second: xxx
deep:
  k1:
    - 1
    - 2
"""

yaml2_str = """
second: again {{ first }}
deep:
  k1:
    - 4
    - 6
  k2:
    - 3
    - 6
"""

# Load and merge YAML documents from strings
# METHOD_MERGE performs a deep merge.
# interpolate=True enables Jinja2 variable substitution.
conf = hiyapyco.load(
    [yaml1_str, yaml2_str],
    method=hiyapyco.METHOD_MERGE,
    interpolate=True
)

pprint.pprint(conf)

# Example of dumping the merged configuration back to YAML
# print(hiyapyco.dump(conf, default_flow_style=False))