<a id="api-utils"></a>

# Utils

This section describes the [`utils`](#module-esmvalcore.experimental.utils) submodule of the API (`esmvalcore.experimental`).

## Finding recipes

One of the first thing we may want to do, is to simply get one of the recipes available in `ESMValTool`

If you already know which recipe you want to load, call [`get_recipe()`](#esmvalcore.experimental.utils.get_recipe).

```python
from esmvalcore.experimental import get_recipe
>>> get_recipe('examples/recipe_python')
Recipe('Recipe python')
```

Call the [`get_all_recipes()`](#esmvalcore.experimental.utils.get_all_recipes) function to get a list of all available recipes.

```python
>>> from esmvalcore.experimental import get_all_recipes
>>> recipes = get_all_recipes()
>>> recipes
[Recipe('Recipe perfmetrics cmip5 4cds'),
 Recipe('Recipe martin18grl'),
 ...
 Recipe('Recipe wflow'),
 Recipe('Recipe pcrglobwb')]
```

To search for a specific recipe, you can use the [`find()`](#esmvalcore.experimental.utils.RecipeList.find) method. This takes a search query that looks through the recipe metadata and returns any matches. The query can be a regex pattern, so you can make it as complex as you like.

```python
>>> results = recipes.find('climwip')
[Recipe('Recipe climwip')]
```

The recipes are loaded in a [`Recipe`](esmvalcore.experimental.recipe.html.md#esmvalcore.experimental.recipe.Recipe) object, which knows about the documentation, authors, project, and related references of the recipe. It resolves all the tags, so that it knows which institute an author belongs to and which references are associated with the recipe.

This means you can search for something like this:

```python
>>> recipes.find('Geophysical Research Letters')
[Recipe('Recipe martin18grl'),
 Recipe('Recipe climwip'),
 Recipe('Recipe ecs constraints'),
 Recipe('Recipe ecs scatter'),
 Recipe('Recipe ecs'),
 Recipe('Recipe seaice')]
```

## API reference

ESMValCore utilities.

**Classes:**

| [`RecipeList`](#esmvalcore.experimental.utils.RecipeList)([iterable])   | Container for recipes.   |
|---------------------------------------------------------------------------|--------------------------|

**Functions:**

| [`get_all_recipes`](#esmvalcore.experimental.utils.get_all_recipes)([subdir])   | Return a list of all available recipes.   |
|------------------------------------------------------------------------------|-------------------------------------------|
| [`get_recipe`](#esmvalcore.experimental.utils.get_recipe)(name)            | Get a recipe by its name.                 |

### *class* esmvalcore.experimental.utils.RecipeList(iterable=(),)

Container for recipes.

**Methods:**

| [`find`](#esmvalcore.experimental.utils.RecipeList.find)(query)   | Search for recipes matching the search query or pattern.   |
|----------------------------------------------------------------|------------------------------------------------------------|

#### find(query: Pattern[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]) → [RecipeList](#esmvalcore.experimental.utils.RecipeList)

Search for recipes matching the search query or pattern.

Searches in the description, authors and project information fields.
All matches are returned.

* **Parameters:**
  **query** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *Pattern*) – String to search for, e.g. `find_recipes('righi')` will return
  all matching that author. Can be a regex pattern.
* **Returns:**
  List of recipes matching the search query.
* **Return type:**
  [RecipeList](#esmvalcore.experimental.utils.RecipeList)

### esmvalcore.experimental.utils.get_all_recipes(subdir: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None) = None) → [list](https://docs.python.org/3/builtins/stdtypes.html#list)

Return a list of all available recipes.

* **Parameters:**
  **subdir** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Sub-directory of the `DIAGNOSTICS.path` to look for
  recipes, e.g. `get_all_recipes(subdir='examples')`.
* **Returns:**
  List of available recipes
* **Return type:**
  [RecipeList](#esmvalcore.experimental.utils.RecipeList)

### esmvalcore.experimental.utils.get_recipe(name: [os.PathLike](https://docs.python.org/3/library/os.html#os.PathLike) | [str](https://docs.python.org/3/builtins/stdtypes.html#str)) → [Recipe](esmvalcore.experimental.recipe.html.md#esmvalcore.experimental.recipe.Recipe)

Get a recipe by its name.

The function looks first in the local directory, and second in the
repository defined by the diagnostic path. The recipe name can be
specified with or without extension. The first match will be returned.

* **Parameters:**
  **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *pathlike*) – Name of the recipe file, i.e. `examples/recipe_python.yml`
* **Returns:**
  Instance of `Recipe` which can be used to inspect and run
  the recipe.
* **Return type:**
  [Recipe](esmvalcore.experimental.recipe.html.md#esmvalcore.experimental.recipe.Recipe)
* **Raises:**
  [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError) – If the name cannot be resolved to a recipe file.