{"id":9037,"library":"hiyapyco","title":"Hierarchical Yaml Python Config","description":"HiYaPyCo is a Python library (current version 0.7.0) that facilitates hierarchical overlay and merging of configuration files written in YAML. It supports multiple merge methods, including deep merge, and features variable interpolation using Jinja2. The library is actively maintained with regular releases. [1, 2, 3]","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/zerwes/hiyapyco","tags":["yaml","config","configuration","merge","jinja2","hierarchical"],"install":[{"cmd":"pip install hiyapyco","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Required for parsing and dumping YAML files.","package":"PyYAML","optional":false},{"reason":"Required for variable interpolation within YAML configuration files.","package":"Jinja2","optional":false}],"imports":[{"symbol":"hiyapyco","correct":"import hiyapyco"}],"quickstart":{"code":"import hiyapyco\nimport pprint\n\nyaml1_str = \"\"\"\nfirst: first element\nsecond: xxx\ndeep:\n  k1:\n    - 1\n    - 2\n\"\"\"\n\nyaml2_str = \"\"\"\nsecond: again {{ first }}\ndeep:\n  k1:\n    - 4\n    - 6\n  k2:\n    - 3\n    - 6\n\"\"\"\n\n# Load and merge YAML documents from strings\n# METHOD_MERGE performs a deep merge.\n# interpolate=True enables Jinja2 variable substitution.\nconf = hiyapyco.load(\n    [yaml1_str, yaml2_str],\n    method=hiyapyco.METHOD_MERGE,\n    interpolate=True\n)\n\npprint.pprint(conf)\n\n# Example of dumping the merged configuration back to YAML\n# print(hiyapyco.dump(conf, default_flow_style=False))","lang":"python","description":"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]"},"warnings":[{"fix":"Upgrade to Python 3 or pin hiyapyco version to <0.5.0.","message":"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]","severity":"breaking","affected_versions":"< 0.5.0"},{"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]","message":"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]","severity":"gotcha","affected_versions":"All versions with Jinja2 interpolation"},{"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)`.","message":"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]","severity":"gotcha","affected_versions":"All versions"},{"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]","message":"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]","severity":"gotcha","affected_versions":">= 0.7.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure PyYAML is installed by running `pip install PyYAML` or simply reinstalling `hiyapyco` to allow pip to resolve dependencies: `pip install hiyapyco`.","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]","error":"ImportError: No module named 'yaml' (or ImportError: No module named yaml)"},{"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]","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]","error":"hiyapyco.HiYaPyCoImplementationException: '{{ my_undefined_var }}' - UndefinedError: 'my_undefined_var' is undefined"},{"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)`.","cause":"By default, hiyapyco's load operation replaces entire lists from earlier files with lists from later files, rather than merging their contents. [7]","error":"Lists are replaced instead of being merged when loading multiple YAML files."}]}