Settings

Contents

Settings#

Overview#

Wetterdienst holds core settings in its Settings class. Settings have four layers from which to be sourced:

  • Settings arguments e.g. Settings(ts_shape=”long”)

  • environment variables e.g. WD_TS_SHAPE="wide"

  • local .env file in the same folder (same as above)

  • default arguments set by wetterdienst

The arguments are overruled in the above order meaning:

  • Settings argument overrules environmental variable

  • environment variable overrules .env file

  • .env file overrules default argument

As from the environment, only the WD_ variables that name a setting are read from .env. Its other keys, such as another program’s, or a WD_ key that names no setting, such as the misspelt WD_CACHE_DIABLE, are ignored. A key within a setting, such as WD_TS_UNIT_TARGETS__TEMPERATURE, is read as part of that setting. A keyword to Settings(...) that names no setting is refused.

The following settings are available:

General

name

description

default

cache_disable

switch off caching

False

cache_dir

set the directory where the cache is stored; where no home directory resolves, the default is a temporary directory per process, removed at exit

platform specific / “wetterdienst”

fsspec_client_kwargs

pass arguments to fsspec, especially for querying data behind a proxy

User-Agent header, timeout 30

use_certifi

use certifi certificate bundle instead of system certificates

False

read_bufr

parse DWD radar BUFR products into RadarResult.df (needs the bufr extra)

False

restapi_sql

let REST API and MCP clients filter with sql / sql_values (refused with a 403 otherwise); the clause runs in DuckDB on the server, see REST API

False

Timeseries

name

description

default

ts_humanize

rename parameters to more meaningful names

True

ts_shape

reshape the returned data to a long/tidy format, one of “long”, “wide”; a wide row is one timestamp of one resolution, so resolutions get their own rows while datasets recorded at the same resolution share one, with their parameter names prefixed by the dataset name and the dataset column of that shared row left null

“long”

ts_convert_units

convert values to target units

True

ts_unit_targets

dictionary of overwrite target units e.g. {"temperature": "degree_fahrenheit", "fraction": "percent"}

{}

ts_skip_empty

skip a station whose requested parameters are covered too sparsely to be worth returning, where too sparsely is defined via ts_skip_threshold and ts_skip_criteria. The coverage of a parameter is the share of the readings the requested window can hold at its resolution that the station actually delivered; a request naming no window is measured against the span of the station’s own series instead

False

ts_skip_threshold

use with skip_empty to define when a station is empty, with 1.0 meaning no values per parameter should be missing and e.g. 0.9 meaning 10 per cent of values can be missing; above 0 and at most 1

0.95

ts_skip_criteria

statistical criteria on which the percentage of actual values is calculated with options “min”, “mean”, “max”, where “min” means the percentage of the lowest available parameter is taken, while “mean” takes the average percentage of all parameters and “max” does so for the parameter with the most percentage

“min”

ts_drop_nulls

drop all empty entries thus reducing the workload, requires setting ts_shape="long": the wide shape keeps them but leaves this setting as given, and settings.ts_drop_nulls_effective tells whether they are dropped

True

ts_geo_station_distance_homogeneous

maximum distance (in km) to a station used for interpolation of a homogeneous parameter, one that varies slowly across a region such as air temperature or air pressure

40.0

ts_geo_station_distance_heterogeneous

the same for a heterogeneous parameter, one that decorrelates within a few tens of kilometres such as precipitation, fresh snow or visibility

20.0

ts_geo_station_distance

dictionary of per-parameter overrides of the two distances above, e.g. {"precipitation_amount": 25.0}, keyed by canonical parameter name. Used exactly as given, at every resolution, while the two distances above are the radius at hourly resolution

{}

ts_geo_station_distance_resolution_factors

dictionary of factors the heterogeneous distance is multiplied by, keyed by resolution, e.g. {"10_minutes": 1.0} to search the full hourly radius at ten minutes. Resolutions left out keep their default factor: 0.75 for the minute resolutions, 1.0 hourly, 1.5 for 6_hour and subdaily, 2.0 from daily upwards, where terrain rather than correlation is what bounds the search

{}

ts_geo_use_nearby_station_distance

distance to the nearest station which decides whether the data is used directly from this station or if data is being interpolated

1

ts_geo_min_gain_of_value_pairs

minimum gain of value pairs which decides whether to stop looking for further stations

0.1

ts_geo_num_additional_stations

number of additional stations to take into account besides gain of value pairs

3

For more on units see the chapter Units, and for the two search radii and their per-parameter overrides the chapter Interpolation & Summary.

Python#

You can import and show Settings like

1from wetterdienst import Settings
2
3settings = Settings()
4settings

{"cache_disable": false, "cache_dir": "/home/docs/.cache/wetterdienst", "fsspec_client_kwargs": {"headers": {"User-Agent": "wetterdienst/0.145.0 (Linux)"}, "timeout": 30}, "auth": {"aemet": null, "knmi": null, "metno_frost": null, "ceda": null}, "use_certifi": false, "read_bufr": false, "restapi_sql": false, "ts_humanize": true, "ts_shape": "long", "ts_convert_units": true, "ts_unit_targets": {}, "ts_skip_empty": false, "ts_skip_threshold": 0.95, "ts_skip_criteria": "min", "ts_drop_nulls": true, "ts_geo_station_distance_homogeneous": 40.0, "ts_geo_station_distance_heterogeneous": 20.0, "ts_geo_station_distance": {}, "ts_geo_station_distance_resolution_factors": {}, "ts_geo_use_nearby_station_distance": 1.0, "ts_geo_min_gain_of_value_pairs": 0.1, "ts_geo_num_additional_stations": 3}

or modify them for your very own request like

1from wetterdienst import Settings
2
3settings = Settings(ts_shape="wide")
4settings

{"cache_disable": false, "cache_dir": "/home/docs/.cache/wetterdienst", "fsspec_client_kwargs": {"headers": {"User-Agent": "wetterdienst/0.145.0 (Linux)"}, "timeout": 30}, "auth": {"aemet": null, "knmi": null, "metno_frost": null, "ceda": null}, "use_certifi": false, "read_bufr": false, "restapi_sql": false, "ts_humanize": true, "ts_shape": "wide", "ts_convert_units": true, "ts_unit_targets": {}, "ts_skip_empty": false, "ts_skip_threshold": 0.95, "ts_skip_criteria": "min", "ts_drop_nulls": true, "ts_geo_station_distance_homogeneous": 40.0, "ts_geo_station_distance_heterogeneous": 20.0, "ts_geo_station_distance": {}, "ts_geo_station_distance_resolution_factors": {}, "ts_geo_use_nearby_station_distance": 1.0, "ts_geo_min_gain_of_value_pairs": 0.1, "ts_geo_num_additional_stations": 3}

If your system is running behind a proxy e.g., like here you may want to use the trust_env setting like

1from wetterdienst import Settings
2
3settings = Settings(fsspec_client_kwargs={"trust_env": True})
4settings

{"cache_disable": false, "cache_dir": "/home/docs/.cache/wetterdienst", "fsspec_client_kwargs": {"headers": {"User-Agent": "wetterdienst/0.145.0 (Linux)"}, "timeout": 30, "trust_env": true}, "auth": {"aemet": null, "knmi": null, "metno_frost": null, "ceda": null}, "use_certifi": false, "read_bufr": false, "restapi_sql": false, "ts_humanize": true, "ts_shape": "long", "ts_convert_units": true, "ts_unit_targets": {}, "ts_skip_empty": false, "ts_skip_threshold": 0.95, "ts_skip_criteria": "min", "ts_drop_nulls": true, "ts_geo_station_distance_homogeneous": 40.0, "ts_geo_station_distance_heterogeneous": 20.0, "ts_geo_station_distance": {}, "ts_geo_station_distance_resolution_factors": {}, "ts_geo_use_nearby_station_distance": 1.0, "ts_geo_min_gain_of_value_pairs": 0.1, "ts_geo_num_additional_stations": 3}

to allow requesting through a proxy.

A dict given as fsspec_client_kwargs, as an argument or as WD_FSSPEC_CLIENT_KWARGS, is merged into the defaults rather than replacing them: the example above keeps the User-Agent header and the timeout of 30. A key you give wins over the default of the same name, and headers, given as a dict, is merged the same way, so a header of your own is sent alongside the User-Agent, and a User-Agent of your own (in any capitalisation) replaces it. Give "timeout": None (null in the environment variable) to use aiohttp’s own default instead: five minutes for the whole request, 30 seconds to connect. A dict assigned to fsspec_client_kwargs on a Settings object that already exists is merged the same way.

A number given as timeout in fsspec_client_kwargs (30 by default) is how many seconds a request may wait before it fails: for a connection (including a free one from the pool), for the first byte of the answer, or between two bytes of it. It does not limit the request as a whole, so a download that keeps arriving is not cut off, however long it takes. Eaufrance Hub’Eau ignores whatever timeout is given and uses 120 seconds, as its service can take longer than 30 seconds to answer.

If you’re experiencing SSL certificate verification issues, especially in corporate environments or when system certificates are outdated, you can enable the certifi certificate bundle:

1from wetterdienst import Settings
2
3settings = Settings(use_certifi=True)
4settings

{"cache_disable": false, "cache_dir": "/home/docs/.cache/wetterdienst", "fsspec_client_kwargs": {"headers": {"User-Agent": "wetterdienst/0.145.0 (Linux)"}, "timeout": 30}, "auth": {"aemet": null, "knmi": null, "metno_frost": null, "ceda": null}, "use_certifi": true, "read_bufr": false, "restapi_sql": false, "ts_humanize": true, "ts_shape": "long", "ts_convert_units": true, "ts_unit_targets": {}, "ts_skip_empty": false, "ts_skip_threshold": 0.95, "ts_skip_criteria": "min", "ts_drop_nulls": true, "ts_geo_station_distance_homogeneous": 40.0, "ts_geo_station_distance_heterogeneous": 20.0, "ts_geo_station_distance": {}, "ts_geo_station_distance_resolution_factors": {}, "ts_geo_use_nearby_station_distance": 1.0, "ts_geo_min_gain_of_value_pairs": 0.1, "ts_geo_num_additional_stations": 3}

This uses the certifi package which provides Mozilla’s carefully curated collection of Root Certificates for validating the trustworthiness of SSL certificates while verifying the identity of TLS hosts.

Contents