Skip to main content

A minimalistic application configuration library for Python

Project description

License Versions PyPI Version Package Status CI Status Coverage Black


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[""] 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.


$ pip install resconfig


Let us first create an ResConfig object with a simple default configuration for your application,

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}},

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[""]
host = config.get("")  # similar to dict.get

The “.”-style can be used elsewhere, e.g.,

config = ResConfig({"": "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({"": "localhost", "db.port": 5432},

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 app with the DB_HOST and/or DB_PORT environment variables set, their values override the default:

$ DB_HOST=remotehost DB_PORT=3306 python

That is, config[""] 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

# --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()

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"")
def act_on_nested_key(action, old, new):
    if action == Action.ADDED:
        # added
    elif action == Action.MODIFIED:
        # modified
    elif action == Action.RELOADED:
        # reloaded
    elif action == Action.REMOVED:
        # removed

Here, the act_on_nested_key function is called whenever configuration changes occur at and can decide what to do with the old and/or new values.


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

Running Tests

$ python tests


Apache License, Version 2.0

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

resconfig-20.4.3a0.tar.gz (21.2 kB view hashes)

Uploaded source

Built Distribution

resconfig-20.4.3a0-py3-none-any.whl (21.9 kB view hashes)

Uploaded py3

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