UpsilonConf

UpsilonConf is a simple configuration library written in Python.

A few features that you might find interesting/useful:

dict-like configuration object with attribute access (cf. attrdict)
hierarchical indexing by means of tuples or dot-strings (cf. omegaconf)
read from/write to various file formats
use hierarchical configs with options (cf. config groups in hydra)
retrieve and manipulate config using CLI (cf. omegaconf)
minimal dependencies (cf. attrdict)
configs with overwriting protection to prevent unexplainable bugs

How to install

Using pip to install from PyPI:

python -m pip install upsilonconf

Optional dependencies (e.g. pyyaml) can be included using

python -m pip install upsilonconf[YAML]

Using conda to install from Anaconda:

conda install hoedt::upsilonconf

Optional dependencies (e.g. pyyaml) have to be installed separately.

How to Use

>>> import upsilonconf
>>> from upsilonconf import PlainConfiguration as Configuration

Creation

load config from file

>>> conf = upsilonconf.load("my_config.yml")

or directly create config object

>>> conf = Configuration(key1="value1", sub={"key1": 1, "key2": 2})

Indexing

Access values the way you like

>>> assert conf["key1"] == conf.key1
>>> assert conf.sub.key2 == conf["sub", "key2"]
>>> assert conf["sub", "key1"] == conf["sub.key1"]
>>> assert conf["sub.key2"] == conf.sub.key2

Cool Tricks

unpack configurations to function arguments

>>> def test(key1, key2):
...    return key1 + key2
>>> test(**conf.sub)
3

convert config to flat dict

>>> conf.to_dict(flat=True)
{'key1': 'value1', 'sub.key1': 1, 'sub.key2': 2}

merge configurations with |

>>> merged = conf | {"sub.key2": 3, "sub.key3": 2}
>>> merged.sub.key2
3
>>> merged.sub.key3
2

More details can be found in the documentation

flexible I/O

support for different file formats

>>> conf = upsilonconf.load("config.yaml")  # with patched float parsing
>>> upsilonconf.save(conf, "config.json")  # with indentation by default

transform non-identifier keys in files on-the-fly

>>> conf = upsilonconf.load("config.yaml", key_mods={" ": "_"})
>>> upsilonconf.save(conf, "config.json", key_mods={"_": " "})

organise hierarchical configs in directories

>>> upsilonconf.save({"key": "option1"}, "config_dir/config.json")
>>> upsilonconf.save({"foo": 1, "bar": 2}, "config_dir/key/option1.json")
>>> upsilonconf.save({"foo": 2, "baz": 3}, "config_dir/key/option2.json")

load arbitrary parts of hierarchy

>>> conf = upsilonconf.load("config_dir/key")
>>> conf == Configuration(
...     option1={"foo": 1, "bar": 2},
...     option2={"foo": 2, "baz": 3}
... )

hierarchies enable option feature

>>> conf = upsilonconf.load("config_dir")
>>> conf == Configuration(key={"foo": 1, "bar": 2})

store hierarchy to directory with a default file format

>>> upsilonconf.save(conf, "backup")

CLI helper

read command-line arguments

>>> conf = upsilonconf.from_cli()

parse arbitrary arguments to construct config

>>> conf = upsilonconf.from_cli(["key=1", "sub.test=2"])
>>> assert conf == Configuration(key=1, sub={"test": 2})

use file as base config

>>> conf = upsilonconf.from_cli(["--config", "config.yaml", "key=1", "sub.test=2"])
>>> result = upsilonconf.load("config.yaml")
>>> result.overwrite_all(key=1, sub={"test": 2})
>>> assert conf == result

enhance existing argparser

>>> from argparse import ArgumentParser
>>> parser = ArgumentParser()
>>> # add other arguments...
>>> conf, args = upsilonconf.from_cli(parser=parser)

Feedback

This library is very much a work in progress. I welcome any feedback, especially in shaping the interface. Of course, also bug reports and feature requests are very useful feedback. Just create an issue on github.

hoedt / upsilonconf

readme