EasyConf
Easy file-based and environment configuration.
Usage
First create a Config
object:
config = easyconf.Config('config.yaml')
Then reference a configuration variable as an attribute of this object:
some_variable = config.SOME_VARIABLE()
At runtime, EasyConf will try to each variable from the following sources in order:
- A matching environment variable
- A matching variable within the configuration file
- The
default
attribute (if no attribute is provided, aneasyconf.config.RequiredConfigVarMissing
exception will be raised)
Config file generation
If the Config
file doesn't exist yet and the file location is writable,
EasyConf will generate it using the initial
values and commented
default
values defined in each configuration variable.
If the configuration file is within a git repository it will also be added to
the .gitignore
file.
Don't hide configuration variables within conditional statements, load them at the top of a module so they can be generated regardless.
If you don't want file generation for non-existant configuration, use
generate=False
when instantiating the Config
object.
Example Django configuration
import easyconf
config = easyconf.Config('myproject.yaml')
DEBUG = config.DEBUG(default=False)
DATABASES = {'default': config.DATABASE(
default='postgres:///myproject',
cast=easyconf.dict_or_url,
)}
SECRET_KEY = config.SECRET_KEY(initial=easyconf.random_text_generator(60))
Configuration Variable options
default
- The default value for the variable if it is not provided in the environment or in the configuration file.
initial
- A value or callable used to set the initial value of a variable in the configuration file.
help
- Help text to use in the configuration file for this variable.
cast
-
A callable to convert an incoming value (from the environment or default value) to the correct Python type.
Set the
cast_from_config
attribute of this callable toTrue
if it is safe to cast from the configuration file as well.
Config
Object options
default_files
-
A file or list of files to attempt to read configuration variables from. If multiple files are provided, only the first one found will be used.
If none of the provided files are found, the first one in a writable location will be created and populated automatically.
file_env_var
-
An environment variable which could be used to specify the configuration file path.
If provided and an environment variable matches, this overrides any
default_files
specified. generate
- Whether to generate a new config file if none of the default_files can be
loaded. Defaults to
True
.
Helper Modules
easyconf.dict_or_url
Expand url strings defined in django-environ into dictionaries. For example:
>>> import easyconf
>>> easyconf.dict_or_url('mysql:///abc')
{'NAME': 'abc', 'USER': '', 'PASSWORD': '', 'HOST': '', 'PORT': '', 'ENGINE': 'django.db.backends.mysql'}
This will also cast url strings coming from the configuration file.
easyconf.random_text_generator
Creates a function that can be called to securely generate a random text string of a predefined length (containing base64 characters).
Useful for the initial
configuration variable option.
>>> import easyconf
>>> gen = easyconf.random_text_generator(20)
>>> gen()
'sYw0D/7xjXqxfCyUdHqr'
>>> gen()
'ig1Z1n+mFLt+qYNOmD6I'