Configuration

from earthkit.data import config

Config basics

“The Configuration object is loaded from the ~/.config/earthkit/data/config.yaml file. Changes are immediately saved back into this file unless we explicitly disable it with config.autosave or use a temporary configuration.”

For the rest of this notebook we disable the configuration autosave so the changes will not be written into our configuration file.

config.autosave = False

We can display the current configuration and the default values with:

config

Name	Value	Default
cache-policy	'user'	'off'
check-out-of-date-urls	True	True
download-out-of-date-urls	False	False
grib-file-serialisation-policy	'path'	'path'
grib-handle-cache-size	1	1
grib-handle-policy	'cache'	'cache'
maximum-cache-disk-usage	'98%'	'98%'
maximum-cache-size	None	None
number-of-download-threads	5	5
reader-type-check-bytes	64	64
temporary-cache-directory-root	None	None
temporary-directory-root	None	None
url-download-timeout	'30s'	'30s'
use-grib-metadata-cache	True	True
use-message-position-index-cache	False	False
use-standalone-mars-client-when-available	True	True
user-cache-directory	'/var/folders/93/w0p869rx17q98wxk83gn9ys40000gn/T/earthkit-data-cgr'	'/var/folders/93/w0p869rx17q98wxk83gn9ys40000gn/T/earthkit-data-cgr'
version	'0.19.2.dev25+g34e3518fd.d20260302'	''

We can use get() to access the config values.

config.get("url-download-timeout")

30

We can use set() to change the values.

config.set("url-download-timeout", 5)
config.get("url-download-timeout")

5

Multiple values can be set together. The argument list can be a dictionary:

config.set({"url-download-timeout": 10, "check-out-of-date-urls": True})
print(config.get("url-download-timeout"))
print(config.get("check-out-of-date-urls"))

10
True

Alternatively, we can use keyword arguments. However, because the “-” character is not allowed in variable names in Python we have to replace “-” with “_” in all the keyword arguments:

config.set(url_download_timeout=10, check_out_of_date_urls=True)
print(config.get("url-download-timeout"))
print(config.get("check-out-of-date-urls"))

10
True

Temporary configuration

We can create a temporary configuration (as a context manager) as a copy of the original configuration. We will still refer to it as “config”, but it is completely independent from the original object and changes are not saved into the yaml file (even when config.auto_save is True).

with config.temporary():
    print(config.get("url-download-timeout"))
    config.set("url-download-timeout", 12)
    print(config.get("url-download-timeout"))

10
12

When we leave the context the config is reverted to the original one:

config.get("url-download-timeout")

10

A temporary configuration can also be created with arguments:

with config.temporary("url-download-timeout", 12):
    print(config.get("url-download-timeout"))

print(config.get("url-download-timeout"))

12
10

Resetting to defaults

The reset() method resets the config to the defaults. We demonstrate it on a temporary configuration:

with config.temporary("url-download-timeout", 12):
    print(config.get("url-download-timeout"))

print(config.get("url-download-timeout"))

12
10