esm_rcfile package

Top-level package for ESM RCFile.


esm_rcfile.esm_rcfile module


This package contains functions to set, get, and use entries stored in the esmtoolsrc file.

To use ESM RCFile in a project:

import esm_rcfile

You can set specific values in the ~/.esmtoolsrc with:

set_rc_entry(key, value)

For example:

>>> set_rc_entry("SCOPE_CONFIG", "/pf/a/a270077/Code/scope/configs/")

Retriving an entry:

>>> fpath = get_rc_entry("FUNCTION_PATH")
>>> print(fpath)

With a default value for a non-existing key:

>>> scope_config = get_rc_entry("SCOPE_CONFIG", "/dev/null")
>>> print(scope_config)

Without a default value, you get EsmRcfileError:

>>> echam_namelist = get_rc_entry("ECHAM_NMLDIR")
EsmRcFileError: No value for ECHAM_NMLDIR found in esmtoolsrc file!!

This error is also raised if there is no ~/.esmtoolsrc file, and no default is provided.

You can also get the entire rcfile as a dict:

>>> rcdict = import_rc_file()

API Documentation

exception esm_rcfile.esm_rcfile.EsmRcfileError[source]

Bases: Exception

class esm_rcfile.esm_rcfile.EsmToolsDir(path_type)[source]

Bases: str

A string subclass whose instances provide the paths to esm_tools folders (configs, namelists and runscripts) when evaluated as a string (i.e. str(<your_instance>) or <your_instance> + <a_string>).

This class is thought as a generalised solution for the problem of removing the FUNCTION_PATH, NAMELIST_PATH and RUNSCRIPT_PATH from the .esmtoolsrc file, and intends to provide those paths correctly, both for virtual environment and open runs, right at the time where the variable containing the instance is evaluated by the esm_parser, as a string.

This should solve issues with, for example, preprocessing and postprocessing scripts called during runtime with a NONE_YET/<path_to_the_script>.


This method returns the path of the esm_tools folder required.


<esm_tools_folder_type_PATH> – The path to the required folder.

Return type


esm_rcfile.esm_rcfile.get_rc_entry(key, default=None)[source]

Gets a specific entry

  • key (str) –

  • default (str) –


Value for key, or default if provided

Return type




  • Raised if key cannot be found in the rcfile and no default is provided * Raised if the esmtoolsrc file cannot be found and no default is provided.


Gets current values of the esmtoolsrc file


A dictionary representation of the rcfile

Return type


esm_rcfile.esm_rcfile.set_rc_entry(key, value)[source]

Sets values in esmtoolsrc

  • key (str) –

  • value (str) –


Using this functions modifies the rcfile; which is stored in the current user’s home directory.