envwrap

CI coveralls codecov codacy

releases pypi/envwrap conda-forge::envwrap

Override parameter defaults via environment variables & config files.

import envwrap

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

Precedence (descending):

  • 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))

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

Project links

Data verified by PyPI on Jul 29, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for casper.dcl from gravatar.com casper.dcl

Credits

Maintainer: tqdm developers

GitHub Statistics

Data verified by PyPI on Jul 29, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MPL-2.0

Requires

Python >=3.8

Provides Extra

dev

Tags

config environment env defaults partial appdir appdirs platformdirs

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

envwrap-1.0.0.tar.gz (10.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

envwrap-1.0.0-py3-none-any.whl (7.0 kB view details)

Uploaded Python 3

File details

Details for the file envwrap-1.0.0.tar.gz.

File metadata

  • Download URL: envwrap-1.0.0.tar.gz
  • Upload date:
  • Size: 10.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.14.6

File hashes

Hashes for envwrap-1.0.0.tar.gz
Algorithm Hash digest
SHA256 e99dbba8ac3217d5a6dbb88437b26705782f6835054b80cbca511059a9bda29e
MD5 032dd5a531a1e756e99e5318b17e88bd
BLAKE2b-256 48e99f285adb1589d48e83c18ebeaa77af2a430ff2e4aa9173e969fa15da4afa

See more details on using hashes here.

Provenance

The following attestation bundles were made for envwrap-1.0.0.tar.gz:

Publisher: test.yml on tqdm/envwrap

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file envwrap-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: envwrap-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 7.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.14.6

File hashes

Hashes for envwrap-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 b1add7e2f63cb8d6146677504167861de010aff7d5ab18539ba2886be8e4b5f2
MD5 b07cbe7c316ae4a72e693b3ab13cc7c6
BLAKE2b-256 86959c47239eb4e544aaec3fe87fdd9513a98d0df72b3eefa740ca1daadb03ed

See more details on using hashes here.

Provenance

The following attestation bundles were made for envwrap-1.0.0-py3-none-any.whl:

Publisher: test.yml on tqdm/envwrap

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page