ewatercycle.config package

Config

Configuration of eWaterCycle is done via the Config object. The global configuration can be imported from the eWaterCycle module as CFG:

>>> from ewatercycle import CFG
>>> CFG
Config({'container_engine': None,
        'grdc_location': None,
        'output_dir': None,
        'singularity_dir': None,
        'wflow.docker_image': None,
        'wflow.singularity_image': None})

By default all values are initialized as None.

CFG is essentially a python dictionary with a few extra functions, similar to matplotlib.rcParams. This means that values can be updated like this:

>>> CFG['output_dir'] = '~/output'
>>> CFG['output_dir']
PosixPath('/home/user/output')

Notice that CFG automatically converts the path to an instance of pathlib.Path and expands the home directory. All values entered into the config are validated to prevent mistakes, for example, it will warn you if you make a typo in the key:

>>> CFG['output_directory'] = '~/output'
InvalidConfigParameter: `output_directory` is not a valid config parameter.

Or, if the value entered cannot be converted to the expected type:

>>> CFG['output_dir'] = 123
InvalidConfigParameter: Key `output_dir`: Expected a path, but got 123

By default, the config is loaded from the default location (i.e. ~/.config/ewatercycle/ewatercycle.yaml). If it does not exist, it falls back to the default values. to load a different file:

>>> CFG.load_from_file('~/my-config.yml')

Or to reload the current config:

>>> CFG.reload()
ewatercycle.config.CFG

eWaterCycle configuration object.

The configuration is loaded from:

  1. ~/$XDG_CONFIG_HOME/ewatercycle/ewatercycle.yaml

  2. ~/.config/ewatercycle/ewatercycle.yaml

  3. /etc/ewatercycle.yaml

  4. Fall back to empty configuration

The ewatercycle.yaml is formatted in YAML and could for example look like:

grdc_location: /data/grdc
container_engine: singularity
singularity_dir: /data/singularity-images
output_dir: /scratch
# Created with cd  /data/singularity-images &&
# singularity pull docker://ewatercycle/wflow-grpc4bmi:2020.1.1
wflow.singularity_images: wflow-grpc4bmi_2020.1.1.sif
wflow.docker_images: ewatercycle/wflow-grpc4bmi:2020.1.1
class ewatercycle.config.Config(*args, **kwargs)

Bases: ValidatedConfig

Configuration object.

Do not instantiate this class directly, but use ewatercycle.CFG instead.

load_from_file(filename: Union[PathLike, str]) → None

Load user configuration from the given file.

reload() → None

Reload the config file.

dump_to_yaml() → str

Dumps YAML formatted string of Config object

save_to_file(config_file: Optional[Union[PathLike, str]] = None)

Write conf object to a file.

Parameters

config_file – File to write configuration object to. If not given then will try to use CFG[‘ewatercycle_config’] location and if CFG[‘ewatercycle_config’] is not set then will use the location in users home directory.