# esmvalcore.io.protocol

Protocols for accessing data.

This module defines the [`DataSource`](#esmvalcore.io.protocol.DataSource) and [`DataElement`](#esmvalcore.io.protocol.DataElement) protocols
for finding and loading data. A data source can be used to find data elements
matching specific facets. A data element represents some data that can be
loaded as Iris cubes.

To add support for a new data source, write two classes that implement these
protocols and configure the tool to use the newly implemented data source as
described in [`esmvalcore.io`](esmvalcore.io.html.md#module-esmvalcore.io).

**Classes:**

| [`DataElement`](#esmvalcore.io.protocol.DataElement)(\*args, \*\*kwargs)   | A data element represents some data that can be loaded.   |
|------------------------------------------------------------------------------------|-----------------------------------------------------------|
| [`DataSource`](#esmvalcore.io.protocol.DataSource)(\*args, \*\*kwargs)    | A data source can be used to find data.                   |

### *class* esmvalcore.io.protocol.DataElement(\*args, \*\*kwargs)

Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol)

A data element represents some data that can be loaded.

An [`esmvalcore.io.local.LocalFile`](esmvalcore.io.local.html.md#esmvalcore.io.local.LocalFile) is an example of a data element.

**Attributes:**

| [`attributes`](#esmvalcore.io.protocol.DataElement.attributes)   | Attributes are key-value pairs describing the data.                 |
|---------------------------------------------------------------|---------------------------------------------------------------------|
| [`facets`](#esmvalcore.io.protocol.DataElement.facets)       | Facets are key-value pairs that can be used for searching the data. |
| [`name`](#esmvalcore.io.protocol.DataElement.name)         | A unique name identifying the data.                                 |

**Methods:**

| [`prepare`](#esmvalcore.io.protocol.DataElement.prepare)()   | Prepare the data for access.   |
|--------------------------------------------------------------|--------------------------------|
| [`to_iris`](#esmvalcore.io.protocol.DataElement.to_iris)()   | Load the data as Iris cubes.   |

#### attributes *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), Any]*

Attributes are key-value pairs describing the data.

#### facets *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), FacetValue]*

Facets are key-value pairs that can be used for searching the data.

#### name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

A unique name identifying the data.

#### prepare() → [None](https://docs.python.org/3/builtins/constants.html#None)

Prepare the data for access.

* **Return type:**
  None

#### to_iris() → [iris.cube.CubeList](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList)

Load the data as Iris cubes.

* **Returns:**
  The loaded data.
* **Return type:**
  [iris.cube.CubeList](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList)

### *class* esmvalcore.io.protocol.DataSource(\*args, \*\*kwargs)

Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol)

A data source can be used to find data.

**Attributes:**

| [`debug_info`](#esmvalcore.io.protocol.DataSource.debug_info)   | A string containing debug information when no data is found.   |
|---------------------------------------------------------------|----------------------------------------------------------------|
| [`name`](#esmvalcore.io.protocol.DataSource.name)         | A name identifying the data source.                            |
| [`priority`](#esmvalcore.io.protocol.DataSource.priority)     | The priority of the data source.                               |
| [`project`](#esmvalcore.io.protocol.DataSource.project)      | The project that the data source provides data for.            |

**Methods:**

| [`find_data`](#esmvalcore.io.protocol.DataSource.find_data)(\*\*facets)   | Find data.   |
|--------------------------------------------------------------------------|--------------|

#### debug_info *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

A string containing debug information when no data is found.

#### find_data(\*\*facets: FacetValue) → Iterable[[DataElement](#esmvalcore.io.protocol.DataElement)]

Find data.

* **Parameters:**
  **\*\*facets** (*FacetValue*) – Find data matching these facets.
* **Returns:**
  The data elements that have been found.
* **Return type:**
  [`typing.Iterable`](https://docs.python.org/3/library/typing.html#typing.Iterable) of `esmvalcore.io.base.DataElement`

#### name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

A name identifying the data source.

#### priority *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The priority of the data source. Lower values have priority.

#### project *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

The project that the data source provides data for.