Merge configuration object from multiple files (instead of one single file)

[schlunma]

Description

This PR is the first step towards our new configuration system (see #2371). It allows reading the configuration from multiple files (and directories), similar to Dask's configuration. The different files are merged using dask.config.collect().

The following directories are considered (descending priority):

1. The directory specified via the --config_dir command line argument
2. User configuration directory (by default ~/.config/esmvaltool, but this can be changed with
   the ESMVALTOOL_CONFIG_DIR environment variable)
3. Default configuration in repository (esmvalcore/config/configurations/defaults)

Please note that these directories may only contain those files that we used to call "user configuration files". If an old "developer configuration file" (or any other YAML file with a different format) is present in this directory, this will lead to errors about invalid configuration options.

Detailed instructions on how to update your existing setup can be found in the deprecation warnings that you get from running the tool, or in the section on deprecations below.

Related to #2371
Closes #805
Closes #1433

Link to documentation:

• https://esmvaltool--2448.org.readthedocs.build/projects/ESMValCore/en/2448/quickstart/configure.html
• https://esmvaltool--2448.org.readthedocs.build/projects/ESMValCore/en/2448/api/esmvalcore.config.html

Deprecations (since v2.12.0, will be removed in v2.14.0)

Usage of single configuration file ~/.esmvaltool/config-user.yml

As mentioned above, ESMValTool will now read configuration directories (instead of one single file). By default, the directory ~/.config/esmvaltool will be considered (can be changed with command line argument --config_dir; see below). To switch to the new format, run

mkdir -p ~/.config/esmvaltool && mv ~/.esmvaltool/config-user.yml ~/.config/esmvaltool

Then you can run ESMValTool with

esmvaltool run <other optional command line options> <recipe>

Configuration option config_file / command line argument --config_file:

As mentioned above, ESMValTool will now read configuration directories (instead of one single file). Instead of specifying one file, specify a configuration directory with --config_dir. To switch to the new format, ensure that the directory that contains your old config file only contains this one YAML file (no other YAML files like old "developer" configuration files) and run ESMValTool with

esmvaltool run --config_dir=<path/to/your/old/config_dir> <other optional command line options> <recipe>

Config.load_from_file():

Please Config.load_from_dirs() instead, e.g.

from pathlib import Path
config_file = Path('path/to/my/config_file.yml')
CFG.load_from_dirs([config_file.parent])

Session.config_dir:

There is no replacement for this attribute.

Specify extra_facets_dir as tuple:

Please use a list instead. For example,

CFG['extra_facets_dir'] = ('path/1', 'path/2')  # deprecated, do not use anymore
CFG['extra_facets_dir'] = ['path/1', 'path/2']  # preferred syntax

Backwards-incompatible change

In some cases, simply copying the old configuration file (e.g., from ~/.esmvaltool/config-user-yml) to the new location might not be enough. In some cases, it might be necessary to adapt drs and rootpath settings. For example, on Levante, it might be necessary to change

drs:  # deprecated, do not use anymore
  CMIP3: DKRZ
  CMIP5: DKRZ
  CMIP6: DKRZ
  CORDEX: BADC

to

drs:  # preferred syntax
  CMIP3: DKRZ
  CMIP5: DKRZ
  CMIP6: DKRZ
  CORDEX: BADC
  obs4MIPS: default

Due to the new way settings are merged across configuration files, nested dictionaries are properly updated now.

Example:

The files

drs:  # default config
  CMIP5: ESGF
  obs4MIPS: ESGF

and

drs:  # user config
  CMIP5: DKRZ
  CMIP6: DKRZ

were previously merged to

drs:  # final config
  CMIP5: DKRZ
  CMIP6: DKRZ

In the new syntax, they are merged to

drs:  # final config
  CMIP5: DKRZ
  CMIP6: DKRZ
  obs4MIPS: ESGF

Thus, in the example above, it is necessary to explicitly specify obs4MIPS: default.

---

Before you get started

• ☝ Create an issue to discuss what you are going to do

Checklist

It is the responsibility of the author to make sure the pull request is ready to review. The icons indicate whether the item will be subject to the 🛠 Technical or 🧪 Scientific review.

• 🧪 The new functionality is relevant and scientifically sound
• 🛠 This pull request has a descriptive title and labels
• 🛠 Code is written according to the code quality guidelines
• 🧪 and 🛠 Documentation is available
• 🛠 Unit tests have been added
• 🛠 Changes are backward compatible see above
• 🛠 Any changed dependencies have been added or removed correctly
• 🛠 The list of authors is up to date
• 🛠 All checks below this pull request were successful

---

To help with the number pull requests:

• 🙏 We kindly ask you to review two other open pull requests in this repository

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 94.90%. Comparing base (4b0dd41) to head (82a1099).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2448      +/-   ##
==========================================
+ Coverage   94.83%   94.90%   +0.06%     
==========================================
  Files         251      251              
  Lines       14191    14295     +104     
==========================================
+ Hits        13458    13566     +108     
+ Misses        733      729       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[schlunma]

I added a warning in 82a1099, see https://esmvaltool--2448.org.readthedocs.build/projects/ESMValCore/en/2448/quickstart/configure.html#developer-configuration-file.

[schlunma]

Thanks for your helpful feedback @k-a-webb 👍 I think I addresses all your comments, please let me know if this is not the case!

If there are no further comments on this, I will merge this on Monday evening 🚀