openairclim.utils.config_files

Helpers for creating and inspecting OpenAirClim config files.

openairclim.utils.config_files.list_nc_data_vars(filepath: Path | str) → list[str]

List data variable names in a NetCDF file.

Used e.g. to discover the available scenario names inside a background concentration file (e.g. “SSP2-4.5”), which are stored as data variables.

Parameters:

filepath (Path or str) – Path to the NetCDF file.

Returns:

Sorted list of data variable names. Empty list if the file doesn’t exist or can’t be opened.

Return type:

list

openairclim.utils.config_files.list_nc_files(directory_path: Path) → list[str]

List NetCDF filenames in a directory.

Parameters:

directory_path (Path) – Directory to scan.

Returns:

Sorted list of .nc filenames found, or an empty list if the directory does not exist.

Return type:

list

openairclim.utils.config_files.prepare_for_save(config: dict, working_dir: str) → dict

Return a copy of config with directory paths made relative.

Parameters:

• config (dict) – Configuration dictionary (absolute dir paths).

• working_dir (str) – Base directory the written TOML’s paths should be relative to.

Returns:

Deep copy of config with directory fields made relative

to working_dir where possible.

Return type:

dict

openairclim.utils.config_files.resolve_dir(working_dir: str, dir_str: str) → Path

Resolve a (possibly relative) directory string against working_dir.

Parameters:

• working_dir (str) – Base directory that relative paths resolve against.

• dir_str (str) – Directory path, absolute or relative.

Returns:

Resolved absolute path, with any “.” / “..” segments collapsed. Doesn’t require the path to exist.

Return type:

Path

openairclim.utils.config_files.to_relative(working_dir: str, absolute_path: str) → str

Convert an absolute path to one relative to working_dir.

Uses “..” segments where necessary, so that directories outside working_dir still resolve correctly on another machine or OS, as long as their position relative to working_dir is preserved. Falls back to the absolute path unchanged only when no relative path can be computed (e.g. paths on different drives on Windows).

Parameters:

• working_dir (str) – Base directory to make the path relative to.

• absolute_path (str) – Absolute path to convert.

Returns:

Relative path (forward-slash separated) if possible, otherwise the absolute path unchanged.

Return type:

str

openairclim.utils.config_files.to_toml_string(config: dict) → str

Format a configuration dictionary as TOML text.

Each top-level key becomes a [section] header; nested dicts within a section are flattened to dotted keys (e.g. CO2.file = "..."), matching OpenAirClim’s existing config style.

Parameters:

config (dict) – Configuration dictionary to format.

Returns:

TOML-formatted text.

Return type:

str

openairclim.utils.config_files.write_toml(config: dict, filepath: Path | str) → None

Write a configuration dictionary to a TOML file.

Parameters:

• config (dict) – Configuration dictionary to write.

• filepath (str or Path) – Destination file path.