Boilerplate-free configuration with env variables.
Project description
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:
HashiCorp Vault support via envconsul.
INI files, because secrets in env variables are icky.
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.
Release Information
19.1.0 (2019-09-02)
Backward-incompatible changes:
Changed license from MIT to Apache License 2.
Deprecations:
none
Changes:
Added AppConfig.from_environ() to instantiate the config class. This is an alternative to environ.from_environ(AppConfig). #5
Added environ.generate_help(AppConfig) and AppConfig.generate_help() to create a help string based on the configuration.
environ.config(from_environ="fr_env", generate_help="gen_hlp") allows passing alternative names for class methods "from_environ" and "generate_help", or prevent their creation by pasing None. #7
If environ.var is passed an attr.Factory, the callable is used to generate the default value. #10
Credits
environ_config is written and maintained by Hynek Schlawack.
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for environ_config-19.1.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 539a1025aeaa015eb03fdd03201517172816ce32ace377c54cbc55c1e4f24739 |
|
MD5 | 5d33d5291176866c4901bb2dcad2a23e |
|
BLAKE2b-256 | 31481889a568b273137e9f8fc679730aaca842365d65c69495e9775a1f2a87eb |