resconfig 20.4.3a0

Description:

resconfig 20.4.3a0

resconfig
resconfig is a minimalistic application configuration library for
Python. It is a thin wrapper around nested dict objects with added
features that make it easy to deal with the data structure as a
centralized storage of application configuration.
ResConfig supports

multiple configuration file formats: INI, JSON, TOML, and YAML;
environment variables: Configuration can be easily overridden with
environment variables;
command-line arguments: Configuration can be easily overridden with
ArgumentParser command-line arguments.
“.”-delimited nested keys: config["foo.bar"] is equivalent to
config["foo"]["bar"].

The advanced usage of ResConfig allows:

Dynamic reloading of configuration at run time: Watch functions can
be attached to any keys within the configuration to trigger actions
to manage resources.

For the full documentation, visit documentation.

Installation
$ pip install resconfig


Quickstart
Let us first create an ResConfig object with a simple default
configuration for your application, myapp.py:
from resconfig ResConfig

config = ResConfig({"db": {"host": "localhost", "port": 5432}})
By default, ResConfig loads configuration immediately after its
initialization. To control the timing of load, use the
load_on_init flag:
config = ResConfig({"db": {"host": "localhost", "port": 5432}},
load_on_init=False)
config.load()
The following sections introduce you to the basic usage of
ResConfig object.

The “.”-Style Key Notation
ResConfig exposes dict-like interface for value access but
additionally allows the “.”-style notation for nested keys. The
following methods all return the same value, localhost:
host = config["db"]["host"]
host = config["db.host"]
host = config.get("db.host") # similar to dict.get
The “.”-style can be used elsewhere, e.g.,
config = ResConfig({"db.host": "localhost", "db.port": 5432})
This will be the same default configuration shown
earlier. ResConfig takes care of nesting the dict for you.


Use with Configuration Files
To read configuration from (multiple) files, supply a list of paths on
object initialization:
config = ResConfig({"db.host": "localhost", "db.port": 5432},
config_files=["myconf.yml",
"~/.myconf.yml,
"/etc/myconf.yml"])
If any of the files exists, they are read in the reverse order, i.e.,
/etc/myconf.yml, ~/.myconf.yml, and then myconf.yml, and the
configuration read from them get merged in that order, overriding the
default. This allows layered configuration based on specificity by
filesystem location.


Use with Environment Variables
Properly named environment variables can override default
configuration. When you run your myapp.py app with the DB_HOST
and/or DB_PORT environment variables set, their values override
the default:
$ DB_HOST=remotehost DB_PORT=3306 python myapp.py
That is, config["db.host"] and config["db.port"] will return
remotehost and 3306, respectively. As a rule of thumb, a
configuration key maps to an uppercased, “_”-delimited (when nested)
environment variable name.


Use with ArgumentParser
A ResConfig object can dynamically generate
argparse.ArgumentParser arguments from default configuration:
parser = argparse.ArgumentParser()
parser.add_argument(...) # Define other arguments

config.add_arguments_to_argparse(parser)
# --pg-host and --pg-port arguments are now available
After actually parsing the (command-line) arguments, pass the parse
result to ResConfig and then load the configuration:
args = parser.parse_args()
config.prepare_from_argparse(args)
config.load()


Adding Actions on Changes
A ResConfig object is aware of changes to its
configuration. Watch functions watch changes happening at any nested
key to act on them:
from resconfig import Action

@config.watch("db.host")
def act_on_nested_key(action, old, new):
if action == Action.ADDED:
# db.host added
elif action == Action.MODIFIED:
# db.host modified
elif action == Action.RELOADED:
# db.host reloaded
elif action == Action.REMOVED:
# db.host removed
Here, the act_on_nested_key function is called whenever
configuration changes occur at db.host and can decide what to do
with the old and/or new values.



Development
$ pip install -e .[dev]
$ pre-commit install


Running Tests
$ python setup.py tests


License
Apache License, Version 2.0