Easy file-based and environment configuration.
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)
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.
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))
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.
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
.
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.
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'