envwrap

Override parameter defaults via environment variables & config files.

import envwrap

@envwrap.envwrap("name", "app")
def func(a=1):
    ...

Lookup precedence

In descending order:

• call (func(a=3))
• environment (NAME_APP_FUNC_A=2, NAME_FUNC_A=2, NAME_APP_A=2, NAME_A=2)
  • UPPER_CASE env vars -> lower_case param names
  • other cases aren't supported because Windows ignores case
• config file:
  • ./{name}.{toml,yaml,yml,json,ini,cfg}::{app.func.a,func.a,app.a,a}
  • platformdirs.{user,site}_config_path(name, False)/
    • {app}.{toml,yaml,yml,json,ini,cfg}::{func.a,a}
    • {name}.{toml,yaml,yml,json,ini,cfg}::{app.func.a,func.a,app.a,a}
  • ./pyproject.toml::tool.name.{app.func.a,func.a,app.a,a}
• signature (def foo(a=1))

Typecasting precedence

In descending order:

• if envwrap.envwrap(convert_config=False): unconverted config file value,
• if convert_config=False: unconverted config file value
• signature value's typehint
• signature default value's type
• envwrap.envwrap(types={'param_name': type})
• unconverted

[!TIP] Containers (list, dict, ...) aren't parsed to avoid mangling strings; use e.g. types={'param_name': ast.literal_eval} instead.

Installation

Any one of:

• pip install envwrap
• conda install -c conda-forge envwrap
• pip install "git+https://github.com/tqdm/envwrap@main"

[!TIP] Note that tqdm ships with a basic tqdm.utils.envwrap, which falls back to the original env-var-only (no config file support) implementation if import envwrap fails.

Advanced Usage

CLI integration

"""CLI example program using envwrap for configuration management.

Usage:
  myapp.py [options] <arg1> [<arg2>]

Options:
  -h, --help    Show this help message and exit.
  -o=<value>, --option=<value>  An option [default: foo].

Arguments:
  <arg1>         An argument.
  <arg2>         An integer argument [default: 2:int].

Defaults above may be overridden by environment variables or config files:
- `MYAPP[_CLI]_*`
- `{.,~/.config/myapp,/etc/xdg/myapp}/myapp[/cli].{toml,yml,json,ini}::[cli.]*`
- `pyproject.toml::tool.myapp[.cli]*`
"""
import argopt, shtab, envwrap

ONLY_PASS_VALID = True # trim envwrap defaults based on parser's valid actions

if __name__ == "__main__":
    parser = argopt.argopt(__doc__)
    shtab.add_argument_to(parser)

    defaults = envwrap.get_defaults("myapp", "", "cli")
    if ONLY_PASS_VALID:
        valid = {i.dest for i in parser._actions}
        defaults = {k: defaults[k] for k in defaults.keys() & valid}

    parser.set_defaults(**defaults)
    args = parser.parse_args()
    print(args)

Live-reload

To force re-reading config files & environment variables without restarting the process:

envwrap.get_defaults.cache_clear()

Debugging

A CLI tool can print defaults. For example, with this config:

# config file: foo.toml
[test]
a = 1337
b = 2

python -m envwrap --help
FOO_A=42 python -m envwrap foo test

will print:

>>> @envwrap.envwrap('foo', '')
>>> def test(...):
...    ...
will use defaults:
{'a': '42', 'b': 2, ...}