Skip to content
Configuration with env variables for Python
Python
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src/environ Start new development cycle Sep 2, 2019
tests hasattr test rewritten to getattr + default sentinel value test Sep 1, 2019
.coveragerc
.gitignore
.pre-commit-config.yaml
.travis.yml
AUTHORS.rst Initial Jan 11, 2017
CHANGELOG.rst Prepare 19.1.0 Sep 2, 2019
LICENSE
MANIFEST.in test 3.8 Jun 7, 2019
NOTICE Relicense under ASLv2 before someone contributes Mar 21, 2019
README.rst Minor README polish Sep 2, 2019
codecov.yml
conftest.py Prepare for public release Dec 14, 2017
pyproject.toml Relicense under ASLv2 before someone contributes Mar 21, 2019
setup.cfg Adds support for a help kwarg on environ.var, environ.bool_var, enivr… Mar 10, 2019
setup.py
tox.ini test 3.8 Jun 7, 2019

README.rst

environ-config: Configuration with env variables for Python.

CI status Test Coverage Code style: black

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.

@environ.config(from_environ="different_name_for_from_environ", generatef_help="different_name_for_generate_help") allows to rename generated classmethods or to prevent it's creation by passing None instead of a name.

Features

  • Declarative & boilerplate-free.
  • Nested config from flat env 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:
  • Pass any dict into environ.to_config(AppConfig, {"your": "config"}) instead of loading from the environment.
  • Built in dynamic help documentation generation via environ.generate_help.
>>> import environ
>>> @environ.config(prefix="APP")
... class AppConfig:
...     @environ.config
...     class SubConfig:
...         sit = environ.var(help="Another example message.")
...         amet = environ.var()
...     lorem = environ.var('ipsum')
...     dolor = environ.bool_var(True, help="An example message.")
...     subconfig = environ.group(SubConfig)
...
>>> print(environ.generate_help(AppConfig))
APP_LOREM (Optional)
APP_DOLOR (Optional): An example message.
APP_SUBCONFIG_SIT (Required): Another example message.
APP_SUBCONFIG_AMET (Required)
>>> print(environ.generate_help(AppConfig, display_defaults=True))
APP_LOREM (Optional, Default=ipsum)
APP_DOLOR (Optional, Default=True): An example message.
APP_SUBCONFIG_SIT (Required): Another example message.
APP_SUBCONFIG_AMET (Required)

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

Project Information

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

You can’t perform that action at this time.