environ-config 20.1.0

Boilerplate-free configuration with env variables.

environ-config allows you to configure your applications using environment variables – as recommended in The Twelve-Factor App methodology – with elegant, boilerplate-free, and declarative code:

>>> import environ
>>> # Extracts secrets from Vault-via-envconsul: 'secret/your-app':
>>> vault = environ.secrets.VaultEnvSecrets(vault_prefix="SECRET_YOUR_APP")
>>> @environ.config(prefix="APP")
... class AppConfig:
...    @environ.config
...    class DB:
...        name = environ.var("default_db")
...        host = environ.var("default.host")
...        port = environ.var(5432, converter=int)  # Use attrs's converters and validators!
...        user = environ.var("default_user")
...        password = vault.secret()
...
...    env = environ.var()
...    lang = environ.var(name="LANG")  # It's possible to overwrite the names of variables.
...    db = environ.group(DB)
...    awesome = environ.bool_var()
>>> cfg = environ.to_config(
...     AppConfig,
...     environ={
...         "APP_ENV": "dev",
...         "APP_DB_HOST": "localhost",
...         "LANG": "C",
...         "APP_AWESOME": "yes",  # true and 1 work too, everything else is False
...         # Vault-via-envconsul-style var name:
...         "SECRET_YOUR_APP_DB_PASSWORD": "s3kr3t",
... })  # Uses os.environ by default.
>>> cfg
AppConfig(env='dev', lang='C', db=AppConfig.DB(name='default_db', host='localhost', port=5432, user='default_user', password=<SECRET>), awesome=True)
>>> cfg.db.password
's3kr3t'

AppConfig.from_environ({...}) is equivalent to the code above, depending on your taste.

Features

• Declarative & boilerplate-free.

• Nested configuration from flat environment variable names.

• Default & mandatory values: enforce configuration structure without writing a line of code.

• Helpful debug logging that will tell you which variables are present and what environ-config is looking for.

• Built on top of attrs which gives you data validation and conversion for free.

• Pluggable secrets extraction. Ships with:

  • HashiCorp Vault support via envconsul.

  • INI files, because secrets in env variables are icky.

• Pass any dictionary into environ.to_config(AppConfig, {"your": "config"}) instead of loading from the environment.

• Built in dynamic help documentation generation via environ.generate_help.

You can find the full documentation including a step-by-step tutorial on Read the Docs.

Project Information

environ-config is released under the Apache License 2.0 license. It targets Python 2.7, 3.5 and newer, and PyPy. Development takes place on GitHub.

Release Information

20.1.0 (2020-03-23)

Backward-incompatible changes:

none

Deprecations:

none

Changes:

• Configurations can be immutable now. #12

Full changelog.

Credits

environ-config is written and maintained by Hynek Schlawack – why not buy him a coffee for all the years of maintenance?

The development is kindly supported by Variomedia AG.

A full list of contributors can be found in GitHub’s overview.

environ-config wouldn’t be possible without the attrs project.