esm_tools package

ESM Tools (Package Documentation)

This package contains almost no code, but instead is where most of the YAML configurations files are distributed. Default namelists are included as well as example runscripts. This section only documents the code contained in the module, please refer to the handbook for user documentation as well as API documentation for the various sub-modules of the project.

Accessing Configuration

To access a particular configuration, you can use:

>>> from esm_tools import read_config_file
>>> ollie_config = read_config_file("machines/ollie")

Important note here is that the configuration file has not yet been parsed, so it’s just the dictionary representation of the YAML.

esm_tools.EDITABLE_INSTALL = False

Shows if the installation is installed in editable mode or not.

Type: bool

esm_tools.caller_wrapper(func)[source]

esm_tools.copy_config_folder(dest_path)[source]

esm_tools.copy_namelist_folder(dest_path)[source]

esm_tools.copy_runscript_folder(dest_path)[source]

esm_tools.get_config_as_str(config)[source]

esm_tools.get_config_filepath(config='')[source]

esm_tools.get_coupling_filepath(coupling='')[source]

esm_tools.get_namelist_filepath(namelist='')[source]

esm_tools.get_runscript_filepath(runscript='')[source]

esm_tools.list_config_dir(dirpath)[source]

esm_tools.read_config_file(config)[source]

Reads a configuration file, which should be seperated by “/”. For example, “machines/ollie” will retrieve the (unparsed) configuration of the Ollie supercomputer.

Parameters: config (str) – Configuration to get, e.g. machines/ollie.yaml, or echam/echam. You may omit the “.yaml” ending if you want, it will be appended automatically if not already there.
Returns: A dictionary representation of the config.
Return type: dict

esm_tools.read_namelist_file(nml)[source]

Reads a namelist file from a path, seperated by “/”. Similar to read_config_file

Parameters: nml (str) – The namelist to load
Returns: A string of the namelist file
Return type: str

Submodules

esm_tools.cli module

esm_tools.error_handling module

esm_tools.error_handling.user_error(error_type, error_text, exit_code=1, dsymbols=['``'], hints=[])[source]

User-friendly error using sys.exit() instead of an Exception.

Parameters

error_type (str) – Error type used for the error heading.
text (str) – Text clarifying the error.
exit_code (int) – The exit code to send back to the parent process (default to 1)

esm_tools.error_handling.user_note(note_heading, note_text, color='\x1b[33m', dsymbols=['``'], hints=[])[source]

Notify the user about something. In the future this should also write in the log.

Parameters

note_heading (str) – Note type used for the heading.
text (str) – Text clarifying the note.

esm_tools.error_handling.user_note_hints(note_text, hints)[source]

Add hints to the note text. The hints are added to the note text by replacing the placeholders “@HINT_#@” with the actual hints from the hints list.

Parameters

note_text (str) – The note text with placeholders for the hints. The placeholders are in the form “@HINT_#@”, where # is the index of the hint in the hints list.
hints (list) –
A list of hints to be added to the note text. Each hint is a dictionary with the following keys: - type: The type of the hint (e.g., “prov” for provenance) - text: The text of the hint. This text can contain a placeholder “@HINT@”

which will be replaced with the actual hint corresponding to its index.
- object: The object to which the hint applies

Returns

note_text – The note text with the placeholders replaced with the hints.

Return type

str