pyscfg 0.2.1

simple handling of user configuration

pyscfg - Python Simple Configuration

A simple solution to store/load/modify configurations for your Python project.

version: 0.2.0
contributors: suppetia

Setup

installing via pip

pip install pyscfg

installing from source

git clone https://github.com/suppetia/pyscfg.git
cd pyscfg
python setup.py install

Getting started

This library allows to work with configurations which are supposed to endure a restart of a program (nearly) as simple as working with dictionaries. Access/update/remove configurations stored in a file using the "bracket-syntax" like using a dictionary and the library will handle all the I/O and keep the configs-file up to date.
At this state of development YAML and JSON files are supported to store the configurations.
! All configuration keys must be strings and if they contain a dot (".") they are interpreted as multilevel keys.

To get started initialize a SimpleConfigs instance:

from pyscfg import SimpleConfigs

# uses file 'configs.yml' (default) to store the configurations
cfg = SimpleConfigs()
# To store the configs in a specific file, pass the path to configuration file.
cfg = SimpleConfigs("data/configs.yml")

If data/configs.yml looks like

a:
    b: value
    c: value2
d: value3

'value' can be accessed using any of the following ways

cfg["a.b"]
cfg["a"]["b"]
cfg.get("a.b")
cfg["a"].get("b")
cfg.get("a").get("b")
cfg.get("a")["b"]

Calling

cfg["a.d"]

will raise a KeyError while

cfg["a"].get("d")                # returns None
cfg["a"].get("d", default=None)  # returns None
cfg["a"].get("d", default="foo") # returns "foo"

returns the default value if the key is not stored in the configs.

To extract a group of configs (a layer in the configs file) as a dictionary use

cfg["a"].as_dict()  # or
dict(cfg["a"])

In the same way updating or adding new configuration keys works:

cfg["a.b"] = "new_value"
cfg["a"]["b"] = "new_value"
...
cfg["e"] = "another new value"
...

# to add a group of parameters use a dict:
cfg["f"] = {"g": 1, "h": 1e10}

After these changes the data/configs.yml file will look like this:

a:
    b: new value
    c: value2
d: value3
e: another new value

To remove a key use one of the following ways:

cfg.remove("e")
del cfg["e"]

# to retrieve the item to be removed or to safely remove a key use dict-like pop-method
cfg.pop("e")                             # returns "another new value"
cfg.pop("non existing key")              # returns None
cfg.pop("non existing key", default=42)  # returns 42

Default values stored in a dictionary can be passed to the constructor. These values will be assigned if the keys aren't in the configurations already. The configurations file is updated.
This might be useful to create a configurations file for an app for the first time and these configs might be changed by the user later.

from pyscfg import SimpleConfigs


defaults = {
    "foo": "John",
    "bar": "Doe",
    "num": 0
}

# uses file 'configs.yml' (default) to store the user configurations
cfg = SimpleConfigs(defaults=defaults)

print(cfg["num"]) # prints 0

if user_chooses_this_option:
    cfg["num"] = 1
else:
    cfg["num"] = -1

print(cfg["num"]) # prints 1 or -1

You can also write your defaults into a configuration file (supported: YAML, JSON) and pass it to the constructor.

# uses file 'default_cfg.yml' in subdirectory 'data' to load the default configuration values
cfg = SimpleConfigs(defaults="data/default_cfg.yml")