Skip to main content

Hierarchical Yaml Python Config

Project description

pylint test gpl

hiyapyco

HiYaPyCo - A Hierarchical Yaml Python Config

Description

A simple python lib allowing hierarchical overlay of config files in YAML syntax, offering different merge methods and variable interpolation based on jinja2.

The goal was to have something similar to puppets hiera merge_behavior: deeper for python.

Key Features

  • hierarchical overlay of multiple YAML files

  • multiple merge methods for hierarchical YAML files

  • variable interpolation using jinja2

Requirements

  • PyYAML aka. python3-yaml

  • Jinja2 aka. python3-jinja2

Python Version

HiYaPyCo was designed to run on current major python versions without changes. Tested versions:

  • 3.9

  • 3.11

Usage

A simple example:

import hiyapyco
conf = hiyapyco.load('yamlfile1' [,'yamlfile2' [,'yamlfile3' [...]]] [,kwargs])
print(hiyapyco.dump(conf, default_flow_style=False))

real life example:

yaml1.yaml:

---
first: first element
second: xxx
deep:
    k1:
        - 1
        - 2

yaml2.yaml:

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

load …

>>> import pprint
>>> import hiyapyco
>>> conf = hiyapyco.load('yaml1.yaml', 'yaml2.yaml', method=hiyapyco.METHOD_MERGE, interpolate=True, failonmissingfiles=True)
>>> pprint.PrettyPrinter(indent=4).pprint(conf)
{   'deep': {   'k1': [1, 2, 4, 6], 'k2': [3, 6]},
    'first': u'first element',
    'ma': {   'ones': u'12', 'sum': u'22'},
    'second': u'again first element'}

real life example using yaml documents as strings

>>> import hiyapyco
>>> y1="""
... yaml: 1
... y:
...   y1: abc
...   y2: xyz
... """
>>> y2="""
... yaml: 2
... y:
...   y2: def
...   y3: XYZ
... """
>>> conf = hiyapyco.load([y1, y2], method=hiyapyco.METHOD_MERGE)
>>> print (conf)
OrderedDict([('yaml', 2), ('y', OrderedDict([('y1', 'abc'), ('y2', 'def'), ('y3', 'XYZ')]))])
>>> hiyapyco.dump(conf, default_flow_style=True)
'{yaml: 2, y: {y1: abc, y2: def, y3: XYZ}}\n'

args

All args are handled as file names or yaml documents. They may be strings or list of strings.

kwargs

  • method: bit (one of the listed below):

    • hiyapyco.METHOD_SIMPLE: replace values (except for lists a simple merge is performed) (default method)

    • hiyapyco.METHOD_MERGE: perform a deep merge

    • hiyapyco.METHOD_SUBSTITUTE: perform a merge w/ lists substituted (unsupported)

  • mergelists: boolean try to merge lists of dict (default: True)

  • none_behavior: bit (one of the listed below):

    • hiyapyco.NONE_BEHAVIOR_DEFAULT: attempt to merge the value with None and fail if this is not possible (default method)

    • hiyapyco.NONE_BEHAVIOR_OVERRIDE: None always overrides any other value.

  • interpolate: boolean : perform interpolation after the merge (default: False)

  • castinterpolated: boolean : try to perform a best possible match cast for interpolated strings (default: False)

  • usedefaultyamlloader: boolean : force the usage of the default PyYAML loader/dumper instead of HiYaPyCos implementation of a OrderedDict loader/dumper (see: Ordered Dict Yaml Loader / Dumper aka. ODYLDo) (default: False)

  • dereferenceyamlanchors: boolean : dereference yaml anchors and use a copy (default: True)

  • encoding: string : encoding used to read yaml files (default: utf-8)

  • failonmissingfiles: boolean : fail if a supplied YAML file can not be found (default: True)

  • loglevel: int : loglevel for the hiyapyco logger; should be one of the valid levels from logging: ‘WARN’, ‘ERROR’, ‘DEBUG’, ‘I NFO’, ‘WARNING’, ‘CRITICAL’, ‘NOTSET’ (default: default of logging)

  • loglevelmissingfiles: int : one of the valid levels from logging: ‘WARN’, ‘ERROR’, ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘CRITICAL’, ‘NOTSET’ (default: logging.ERROR if failonmissingfiles = True, else logging.WARN)

  • mergeoverride: optional function to customize merge for primitive values (see PR #76.)

  • loader_callback: optional custom callback function to load yaml files.

    The callback function shall behave like yaml.load_all from PyYAML, taking a IO stream as input and returning a list of objects. Using this method, for example ruamel can be used instead of PyYAML etc.

interpolation

For using interpolation, I strongly recomend not to use the default PyYAML loader, as it sorts the dict entrys alphabetically, a fact that may break interpolation in some cases (see test/odict.yaml and test/test_odict.py for an example). See Ordered Dict Yaml Loader / Dumper aka. ODYLDo

default

The default jinja2.Environment for the interpolation is

hiyapyco.jinja2env = Environment(undefined=Undefined)

This means that undefined vars will be ignored and replaced with a empty string.

change the jinja2 Environment

If you like to change the jinja2 Environment used for the interpolation, set hiyapyco.jinja2env before calling hiyapyco.load!

use jinja2 DebugUndefined

If you like to keep the undefined var as string but raise no error, use

from jinja2 import Environment, Undefined, DebugUndefined, StrictUndefined
hiyapyco.jinja2env = Environment(undefined=DebugUndefined)
use jinja2 StrictUndefined

If you like to raise a error on undefined vars, use

from jinja2 import Environment, Undefined, DebugUndefined, StrictUndefined
hiyapyco.jinja2env = Environment(undefined=StrictUndefined)

This will raise a hiyapyco.HiYaPyCoImplementationException wrapped arround the jinja2.UndefinedError pointing at the string causing the error.

more informations

See: jinja2.Environment

cast interpolated strings

As you must use interpolation as strings (PyYAML will weep if you try to start a value with {{), you can set castinterpolated to True in order to try to get a best match cast for the interpolated values. The ``best match`` cast is currently only a q&d implementation and may not give you the expected results!

Ordered Dict Yaml Loader / Dumper aka. ODYLDo

This is a simple implementation of a PyYAML loader / dumper using OrderedDict from collections. Because chaos is fun but order matters on loading dicts from a yaml file.

Install

From Source

GitHub

https://github.com/zerwes/hiyapyco

git clone https://github.com/zerwes/hiyapyco
cd hiyapyco
sudo python setup.py install
PyPi

Download the latest or desired version of the source package from https://pypi.python.org/pypi/HiYaPyCo. Unpack the archive and install by executing:

sudo python setup.py install

pip

Install the latest wheel package using:

pip install HiYaPyCo

debian packages

install the latest debian packages from http://repo.zero-sys.net/hiyapyco:

# create the sources list file:
sudo echo "deb http://repo.zero-sys.net/hiyapyco/deb ./" > /etc/apt/sources.list.d/hiyapyco.list

# import the key:
gpg --keyserver keys.gnupg.net --recv-key 77DE7FB4
# or use:
wget https://repo.zero-sys.net/77DE7FB4.asc -O - | gpg --import -

# apt tasks:
gpg --armor --export 77DE7FB4 | sudo tee /etc/apt/trusted.gpg.d/hiyapyco.asc
sudo apt-get update
sudo apt-get install python3-hiyapyco

a ansible playbook exists: https://github.com/zerwes/ansible-role-hiyapyco

rpm packages

use http://repo.zero-sys.net/hiyapyco/rpm as URL for the yum repo and https://repo.zero-sys.net/77DE7FB4.asc as the URL for the key.

Arch Linux

An AUR package is available (provided by Pete Crighton and not always up to date).

License

Copyright © 2014 - 2024 Klaus Zerwes zero-sys.net

This package is free software. This software is licensed under the terms of the GNU GENERAL PUBLIC LICENSE version 3 or later, as published by the Free Software Foundation. See https://www.gnu.org/licenses/gpl.html

Changelog

0.7.0

MERGED: allow custom yaml loaders as callback functions by @grst (PR #77)

MERGED: implement none-behavior strategies by @grst (PR #78)

MERGED: update markupsafe requirement from <3 to <4 (#80)

IMPROVED: added some example how to use ruamel

0.6.1

MERGED: #76 Override mechanism for primitive value merge by malachib

IMPROVED: added link to ansible playbook

0.6.0

FIXED: #69 (weird merge behavior with anchors)

MERGED: #71 (dereference anchors)

0.5.6

MERGED: #70 by itachi-cracker

FIXED: #61 (removed deprecated distutils)

0.5.5

FIXED: #67 cosmetic changes

0.5.4

FIXED: #60 recursive calls to _substmerge

IMPROVED: testing and python support (3.11)

0.5.1

MERGED: #52 by ryanfaircloth

0.5.0

MERGED: #41 Jinja2 dependency increased to include Jinja2 3.x.x

REMOVED: Support for Python 2

0.4.16

MERGED: #37 alex-ber

0.4.15

MERGED: #30 lesiak:issue-30-utf

MERGED: #28 lesiak:issue-28

0.4.14

FIXED: issue #33

MERGED: issue #32

0.4.13

IMPLEMENTED: [issue #27] support multiple yaml documents in one file

0.4.12

FIXED: logging by Regev Golan

0.4.11

IMPLEMENTED: mergelists (see issue #25)

0.4.10

FIXED: issue #24 repo signing

0.4.9

FIXED: issue #23 loglevelonmissingfiles

0.4.8

Fixed pypi doc

0.4.7

Reverted: logger settings to initial state

Improved: dump

Merged:

0.4.6

MERGED: fixes from mmariani

0.4.5

FIXED: issues #9 and #11

0.4.4

deb packages:

  • removed support for python 2.6

  • include examples as doc

0.4.3

FIXED: issue #6 import of hiyapyco **version* in setup.py causes pip install failures*

0.4.2

Changed: moved to GPL

Improvements: missing files handling, doc

0.4.1

Implemented: castinterpolated

0.4.0

Implemented: loading yaml docs from string

0.3.2

Improved tests and bool args checks

0.3.0 / 0.3.1

Implemented a Ordered Dict Yaml Loader

0.2.0

Fixed unicode handling

0.1.0 / 0.1.1

Initial release

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

HiYaPyCo-0.7.0.tar.gz (33.4 kB view details)

Uploaded Source

Built Distribution

HiYaPyCo-0.7.0-py2.py3-none-any.whl (24.7 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file HiYaPyCo-0.7.0.tar.gz.

File metadata

  • Download URL: HiYaPyCo-0.7.0.tar.gz
  • Upload date:
  • Size: 33.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.2

File hashes

Hashes for HiYaPyCo-0.7.0.tar.gz
Algorithm Hash digest
SHA256 83387c217e109956af61a23884cf8cc9ba5f19241b3ac68141e3ad1153fc4597
MD5 427a8b2c79297c626e41c34368745bff
BLAKE2b-256 4a4c48999f3383f99a4bb49723983147b2b4ef62f29fdeca81ec87cb0cc70d8c

See more details on using hashes here.

File details

Details for the file HiYaPyCo-0.7.0-py2.py3-none-any.whl.

File metadata

  • Download URL: HiYaPyCo-0.7.0-py2.py3-none-any.whl
  • Upload date:
  • Size: 24.7 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.2

File hashes

Hashes for HiYaPyCo-0.7.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 d56ae0f746506955c6b0072f7338f1cd50661bfd07c7ee9b49175a085fcbaf41
MD5 6687d43b0b7e01e630166e5b11cd5118
BLAKE2b-256 033d3f847839e28e354873c81ebc3d3322d6e73d0d386971e84c178b45e82ff4

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page