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.get_esm_tools_root_dir()[source]
Get the root directory of esm_tools installation.
This function finds the actual root directory of the esm_tools installation, which is useful for providing upgrade instructions or accessing the git repository.
For editable installs (pip install -e), this returns the git repository directory. For normal installs, this returns the site-packages location.
- Returns
The root directory of esm_tools, or None if it cannot be determined.
- Return type
pathlib.Path or None
Notes
This function is more reliable than _get_real_dir_from_pth_file(“”) because it: - Works regardless of virtual environment configuration - Doesn’t depend on finding .egg-link files - Uses Python’s standard __file__ attribute - Handles both editable and normal installations
- 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 anException.- 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