Adapter

class Adapter(creds: Optional[eratos.creds.BaseCreds] = None, ignore_certs=False)

Bases: object

A class used to interact with Eratos’ adapter functionality.

creds

Required Eratos Token key ID and secret, wrapped in an BaseCreds object. (Default value is None)

Type: BaseCreds

ignore_certs

Optional argument to ignore or accept certificates. (Default value is False)

Type: bool

Data(*args, **kwargs)

Interacts with the underlying data in a Resource.

Data() returns a Data object with the ability to interact with the data that a Resource contains.

Parameters

args (args) – Optional non-keyworded arguments.
kwargs (args) – Optional keyword arguments. Arguments can include any of: | id = String to fetch an Eratos dataset. (Default value is None) | content = Dictionary object to set data content. (Default value is None)

Returns

An Eratos Data object to interact with.

Return type

Data

Policy(*args, **kwargs)

Interacts with a Policy.

Policy() returns a Policy object with the ability to interact with the policy for a given Resource or Node.

Parameters

args (args) – Optional non-keyworded arguments.
kwargs (args) – Optional keyword arguments. Arguments can include any of: | ern = String or Eratos Resource Name (ERN) of an existing Policy object in Eratos to retrieve. (Default value is None) | yaml = Yaml object to set policy content. (Default value is None) | json = JSON object to set policy content. (Default value is None) | content = Dictionary object to set policy content. (Default value is None)

Returns

An Eratos Policy object to interact with.

Return type

Policy

Resource(*args, **kwargs)

Interacts with an Eratos Resource.

Resource() returns a Resource that corresponds to the provided arguments. If the ern argument is set, it will fetch the corresponding Resource, else it will create a resource based on yaml, json or dictionary content.

Parameters

args (args) – Optional non-keyworded arguments.
kwargs (args) – Optional keyword arguments. Arguments can include any of: | ern = String or Eratos Resource Name (ERN) of an existing object in Eratos to retrieve. (Default value is None) | yaml = Yaml object to create an Eratos Resource object. (Default value is None) | json = JSON object to create an Eratos Resource object. (Default value is None) | content = Dictionary object to create an Eratos Resource object. (Default value is None)

Returns

An Eratos resource object.

Return type

Resource

dnbasicrequest(method: str, ep: str, headers={}, **kwargs)

Send a datanode basic HTTP request.

dnbasicrequest() sends a basic HTTP request to the adapter’s datanode to perform a given action.

Parameters

method (str) – A string to define the type of the request. (ex. ‘GET’)
ep (str) – A string to define the parameters of the request.
headers (dict) – Includes any headers to add to the request. (Default value is an empty dictionary)
kwargs (args) – Optional keyword arguments to add to the request object. Arguments can include any of the following: | params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None

Raises

CommError – If the request fails.

Returns

The response content.

Return type

Response

dnrequest(dnurl: str, method: str, path: str, headers={}, **kwargs)

Send a datanode request.

dnrequest() sends a request to the adapter’s datanode to perform a given action.

Parameters

dnurl (str) – The url for the datanode. It is set to a default if an empty string is provided.
method (str) – A string to define the type of the request. (ex. ‘GET’)
path (str) – A string to define the path of the request.
headers (dict) – Includes any headers to add to the request. (Default value is an empty dictionary)
kwargs (args) – Optional keyword arguments to add to the request object. Arguments can include any of the following: | params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None

Raises

ValueError – If the response cannot be decoded.
CommError – If the request fails.

Returns

The decoded response content.

Return type

dict | str

dnstreamrequest(method: str, ep: str, headers={}, **kwargs)

Send a datanode stream request.

dnstreamrequest() sends a stream request to the adapter’s datanode to perform a given action.

Parameters

method (str) – A string to define the type of the request. (ex. ‘GET’)
ep (str) – A string to define the parameters of the request.
headers (dict) – Includes any headers to add to the request. (Default value is an empty dictionary)
kwargs (args) – Optional keyword arguments to add to the request object. Arguments can include any of the following: | params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None

Returns

The streamed response content.

Return type

stream

get_data_node_token()

Retrieves the authentication token for the current adapter’s data node.

get_data_node_token() calls the RequestTokenInserter. The method retrieves the token for authentication purposes and gives the ability to attach the token as an authorization header.

Returns: Returns the authentication token inserter class.
Return type: RequestTokenInserter

master_pn()

Retrieves the master primary node.

master_pn() fetches the Eratos Resource Name (ERN) of the master primary node for the given adapter.

Returns: The unique Eratos Resource Name (ERN) of the master primary node.
Return type: Ern

request(target_ern: eratos.ern.Ern, method: str, path: str, headers={}, retRequest=False, **kwargs)

Send a request to a specific ERN.

request() sends a request to a specific Eratos Resource Name (ERN) to perform a given action.

Parameters

target_ern (Ern) – A string defining the target Eratos Resource Name (ERN) to send the request to.
method (str) – A string to define the method of the request. (ex. ‘GET’)
path (str) – A string to define the path of the request.
headers (dict) – Includes any headers to add to the request. (Default value is an empty dictionary)
retRequest (bool) – True or False to return the request as well as the response. (Default is False)
kwargs (args) – Optional keyword arguments to add to the request object. Arguments can include any of the following: | params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None

Raises

ValueError – If the response cannot be decoded.
CommError – If the request fails.

Returns

The decoded response content.

Return type

dict | str

search_adapter(return_limit=- 1, **kwargs)

Searches the current adapter according to a given query.

search_adapter() returns a SearchAdapter object according to a set of given parameters. Must run with an initialized adapter with valid credentials.

Parameters

return_limit (int) – A set return limit on the search. (Default value is -1)
kwargs (args) – Optional keyword arguments to search against. Arguments can include any of: | query = A string to query (ex. ‘*’) | limit = An integer depicting the number of resources to limit the return (ex. 20) | start = An integer depicting the start index (ex. 0) | exclude = A list of ERNs to exclude. | type = A list of types to search for. | excludeType = A list of types to exclude from the search. | owner = A list of owner ERN’s to search against. | collections = A list of collection ERN’s to search against. | facets = A list of facets to search against. | geom = A geospatial geometry to search within.

Returns

An Eratos SearchAdapter object to interact with.

Return type

SearchAdapter

search_resources(return_limit=- 1, **kwargs)

Searches resources according to a specific query.

search_resources() returns a list of matching ERNs (can be empty) according to specific query parameters. Must run with an initialized adapter with valid credentials.

Parameters

return_limit (int) – A set return limit on the search. (Default value is -1)
kwargs (args) – Optional keyword arguments to search against. Arguments can include any of: | query = A string to query (ex. ‘*’) | limit = An integer depicting the number of resources to limit the return (ex. 20) | start = An integer depicting the start index (ex. 0) | exclude = A list of ERNs to exclude. | type = A list of types to search for. | excludeType = A list of types to exclude from the search. | owner = A list of owner ERN’s to search against. | collections = A list of collection ERN’s to search against. | facets = A list of facets to search against. | geom = A geospatial geometry to search within.

Returns

An empty list or a list of unique Eratos Resource Name (ERN) strings.

Return type

list[str]

session()

Retrieves the current HTTP session object.

Returns: HTTP Session object.
Return type: Session

class CachedPoolAdapter(adapter: eratos.adapter.Adapter, cacheTime=3600.0)

Bases: object

Data(*args, **kwargs)

Policy(*args, **kwargs)

Resource(*args, **kwargs)

dnbasicrequest(method: str, ep: str, headers={}, **kwargs)

dnrequest(dnurl: str, method: str, path: str, headers={}, **kwargs)

dnstreamrequest(method: str, ep: str, headers={}, **kwargs)

get_data_node_token()

master_pn()

request(target_ern: eratos.ern.Ern, method: str, path: str, headers={}, retRequest=False, **kwargs)

search_adapter(return_limit=- 1, **kwargs)

search_resources(return_limit=- 1, **kwargs)

session()

decode_jwt_claims(token)

A small decoder utility function.

Parameters: token (str) – A string defining the token for authentication.

Credentials

class AccessTokenCreds(id: str, secret: str, tracker: str = 'https://e-tr.io')

Bases: eratos.creds.BaseCreds

A class to interact with access credentials. Inherits from the BaseCreds class.

auth_query_params()

Gets the authentication query parameter for a user/account.

Returns: A dictionary containing the key ‘user_sig’ and the encoded JSON web token value.
Return type: dict

class BaseCreds(tracker: str = 'https://e-tr.io')

Bases: object

A base credentials class to interact with the tracker node.

auth_query_params()

tracker()

Retrieves the tracker.

Returns: The string for the tracker node.
Return type: str

tracker_url()

Retrieves the tracker url.

Returns: The string for the tracker url.
Return type: str

class JobKeyCreds(key: str, tracker: str = 'https://e-tr.io')

Bases: eratos.creds.BaseCreds

A class to interact with job key authentication. Inherits from the BaseCreds class.

auth_query_params()

Gets the authentication query parameter for a job.

Returns: A dictionary containing the key ‘user_sig’ and the job key.
Return type: dict

class RequestTokenInserter(token: str)

Bases: object

A class to interact with the authorization token.

class TrackerExchange(session: requests.sessions.Session, creds: Optional[eratos.creds.AccessTokenCreds] = None, ignore_certs=False)

Bases: object

A class to interact with the Eratos tracker exchange node.

fetch_target_host(target_ern: eratos.ern.Ern)

Retrieves the host for a given ERN.

Parameters: target_ern (Ern) – The unique Eratos Resource Name (ERN).
Returns: The URL or ID string (ERN) for the host location.
Return type: str

get_auth_token(target_ern: eratos.ern.Ern)

Retrieves the authentication token for a given ERN.

Parameters: target_ern (Ern) – The unique Eratos Resource Name (ERN).
Returns: Returns the authentication token inserter class for a given ERN.
Return type: RequestTokenInserter

master_pn()

Retrieves the Eratos Resource Name (ERN) for the master primary node.

Returns: The unique Eratos Resource Name (ERN) of the master primary node.
Return type: Ern

ERN

class Ern(ern: Optional[str] = None, node: Optional[str] = None, type: Optional[str] = None, id: Optional[str] = None, path: str = '', query: dict = {})

Bases: object

A class to interact with Eratos’ unique Eratos Resource Names (ERNs).

id()

Retrieves the unique Eratos Resource Name (ERN) string ID.

Returns: The unique Eratos Resource Name (ERN) ID of the current ERN object.
Return type: str

node()

Retrieves the node for a given Eratos Resource Name (ERN).

Returns: The node ID for a given ERN.
Return type: str

node_ern()

Retrieves the node’s ERN object.

Returns: The node ERN object for a given ERN.
Return type: Ern | None

path()

Retrieves the path related to the ERN object.

Returns: The path of the ERN object.
Return type: str

query()

Retrieves the query of the ERN object.

Returns: The dictionary of the ERN object.
Return type: dict

root()

Retrieves the root ERN object.

Returns: The root ERN object.
Return type: Ern

type()

Retrieves the type for the unique Eratos Resource Name (ERN).

Returns: The type of the ERN object.
Return type: str

Resource

class Resource(adapter, ern=None, yaml=None, json=None, content=None)

Bases: object

A class used to interact with Eratos’ Resource objects.

authactions()

Gets the authorized actions available for a resource.

Raises: ResourceError – If authorized actions cannot be retrieved for the given resource.
Returns: The json response object from the performed action.
Return type: json

data()

Retrieves the underlying data of a resource.

Returns: The unique Eratos Resource Name (ERN) for the underlying data of a resource or the resource for the data if it exists.
Return type: Resource | Data | None

date()

Retrieves the date a resource was created.

Returns: Date string.
Return type: str

ern()

Retrieves the unique Eratos Resource Name (ERN) for a resource.

Returns: The unique Eratos Resource Name (ERN).
Return type: Ern

fetch()

Gets a resource.

Raises: ResourceError – If the @id has not been set for the resource. (The resource is missing it’s unique Eratos Resource Name (ERN).)
Returns: The Eratos Resource object.
Return type: Resource

get_geo(detail='max', asVec=False)

Retrieves the geospatial geometry specified for a resource.

Parameters

detail (str) – The detail level of a geospatial geometry. The value can be one of ‘point’, ‘box’ or ‘max’. (Default value is ‘max’)
asVec (bool) – Returns the geometry as a vector/array if set to True. (Default value is False)

Raises

ValueError – If detail is not set to one of ‘point’, ‘box’ or ‘max’.

Returns

The vector/array of coordinates if asVec is True, or the Well-Known Text formatted geometry string.

Return type

arr | str

has_geo()

static is_resource(v)

A utility function to determine that the object is of type Resource.

Returns: True or False depending on the type of the object.
Return type: bool

is_valid()

A utility function to determine the validity of a resource’s fields.

Returns: True or False depending on the validity of a field.
Return type: bool

json(for_push=False, **kwargs)

Creates a resource’s properties in json.

Parameters

for_push (bool) – A bool to set whether the object is to be pushed. (Default value is False)
kwargs (args) – Optional keyword property arguments to add to the Resource object.

Returns

The json dictionary object containing the Resource properties.

Return type

dict

json_set(obj, merge=False)

Set a resource’s properties via json.

Parameters

obj (dict) – The json object containing the resource’s properties.
merge (bool) – True to merge the content with an existing Resource, or False to overwrite. (Default value is False)

owner()

Retrieves the owner of a resource.

Returns: The unique Eratos Resource Name (ERN) for the owner of a resource.
Return type: Ern

perform_action(action, params)

Performs an action on a resource.

Parameters

action (str) – The action to perform.
params (str) – Parameters for the action to perform.

Raises

ResourceError – If the resource cannot be acted upon.

Returns

The json response object from the performed action.

Return type

json

policy()

Retrieves the policy of a resource.

Returns: The unique Eratos Resource Name (ERN) for the policy of a resource.
Return type: Ern

prop(key, default=None)

Retrieves a property of a given resource corresponding to a key name.

Parameters

key (str) – The property name/key.
default (str) – A default to return if the property is not found. (Default value is None)

Returns

The value of a given property for a resource.

Return type

Any

prop_path(propPath, default=None, sep=None)

Gets the value of a property for a given resource.

Parameters

propPath (str) – The key/name of the property to get.
default (str) – A default to return if the property is not found. (Default value is None)
sep (str) – A separator to use in returning the property’s values if more than one is found. (Default value is None)

Returns

The value(s) found for of a given property in a resource.

Return type

vals

props()

Retrieves the properties of a given resource.

Returns: A dictionary of the properties.
Return type: dict

public()

Retrieves whether a given resource is public or not.

Returns: True or False.
Return type: bool

remove()

Deletes a resource.

Raises: ResourceError – If the resource cannot be removed.
Returns: The Eratos Resource object.
Return type: Resource

save(target_node: Optional[eratos.ern.Ern] = None)

Posts a resource.

Parameters: target_node (Ern) – The unique Eratos Resource Name (ERN) for the node to post to. (Default value is None)
Returns: The Eratos Resource object.
Return type: Resource

set_geo(wkt)

Sets the geospatial geometry for a given resource.

Parameters: wkt (str) – Well-Known Text formatted geometry string.

set_prop(key, value)

Adds a property to a given resource.

Parameters

key (str) – The key/name of the property to set.
value (str) – The value of the property to set.

type()

Retrieves the type of a resource.

Returns: The unique Eratos Resource Name (ERN) for the type of a resource.
Return type: Ern

yaml(**kwargs)

Creates a resource’s properties in yaml.

Parameters: kwargs (args) – Optional keyword property arguments to add to the Resource object.
Returns: The yaml string object containing the Resource properties.
Return type: str

yaml_set(yaml, merge=False)

Set a resource’s properties via yaml.

Parameters

yaml (str) – The yaml str object containing the resource’s properties.
merge (bool) – True to merge the content with an existing Resource, or False to overwrite. (Default value is False)

Policy

class Policy(adapter, ern=None, yaml=None, json=None, content=None)

Bases: object

A class used to interact with the Policy attached to Eratos’ Resources and Nodes.

TYPE_NODE = 'Node'

TYPE_RESOURCE = 'Resource'

date()

Retrieves the date a policy was created.

Returns: Date string.
Return type: str

ern()

Retrieves the unique Eratos Resource Name (ERN) for a policy.

Returns: The unique Eratos Resource Name (ERN).
Return type: Ern

fetch()

Gets a policy.

Raises: ResourceError – If the @id has not been set for the policy. (The policy is missing it’s unique Eratos Resource Name (ERN).)
Returns: The Eratos Policy object.
Return type: Policy

for_entity()

Retrieves the unique Eratos Resource Name (ERN) of the entity a policy applies to.

Returns: The unique Eratos Resource Name (ERN) of the entity if exists.
Return type: Ern | None

is_valid()

A utility function to determine the validity of a policy’s fields.

Returns: True or False depending on the validity of a field.
Return type: bool

json(for_push=False, **kwargs)

Creates a policy’s properties in json.

Parameters

for_push (bool) – A bool to set whether the object is to be pushed. (Default value is False)
kwargs (args) – Optional keyword property arguments to add to the Policy object.

Returns

The json dictionary object containing the Policy properties.

Return type

dict

json_set(obj, merge=False)

Set a policy’s properties via json.

Parameters

obj (dict) – The json object containing the policy’s properties.
merge (bool) – True to merge the content with an existing Policy, or False to overwrite. (Default value is False)

rules()

Retrieves the set of rules that apply to a policy.

Returns: The policy rules. (Can be an empty list)
Return type: list[dict]

save()

Posts a policy.

Raises: PolicyError – If the user does not have permission to create a policy.
Returns: The Eratos Policy object.
Return type: Policy

type()

Retrieves the type of entities a policy adheres to.

Returns: The policy type if exists.
Return type: str | None

yaml(**kwargs)

Creates a policy’s properties in yaml.

Parameters: kwargs (args) – Optional keyword property arguments to add to the Policy object.
Returns: The yaml string object containing the Policy properties.
Return type: str

yaml_set(yaml, merge=False)

Set a policy’s properties via yaml.

Parameters

yaml (str) – The yaml str object containing the policy’s properties.
merge (bool) – True to merge the content with an existing Policy, or False to overwrite. (Default value is False)

Data

class Data(adapter, resource, id=None, content=None)

Bases: object

A class to interact with Eratos’ Resource Data.

content_available(allow_partial=False)

Retrieves the key of data with content available.

Parameters: allow_partial (bool) – Allow content that has a status of ‘Partial’. (Default value is False)
Returns: The string key of data with content available if exists.
Return type: str | None

fetch()

Fetches the data object.

Returns: The data object resource.
Return type: Resource

fetch_object(key, dest='.', version=None)

Downloads data according to a specific key into a destination.

Parameters

key (str) – The key of the data to fetch.
dest (str) – The location to store the data. (Default is “.”)
version (str) – A specific version of the data to pull. (Default value is None)

Raises

AttributeError – If invalid values exist.

gapi()

Retrieves the gridded API for a gridded geospatial dataset.

Returns: The gridded API object for the dataset if exists.
Return type: GSData | None

id()

Retrieves the unique Eratos Resource Name (ERN) ID.

Returns: The unique Eratos Resource Name (ERN) ID of the current Resource.
Return type: str

static is_data(v)

A utility function to determine that the object is of type Data.

Returns: True or False depending on the type of the object.
Return type: bool

is_valid()

A utility function to determine the validity of a Data resource’s fields.

Returns: True or False depending on the validity of a field.
Return type: bool

list_objects(version=None)

Gets the lists of objects for a Data resource.

Parameters: version (str) – A specified version of the data to pull. (Default value is None)
Raises: AttributeError – If invalid values exist.
Returns: A list of data items including their path, mime type and size.
Return type: arr

pull_files(dest, version=None)

Pulls the dataset files into a given storage location.

Parameters

dest (str) – The destination path to store the pulled data files.
version (str) – A specified version of the data to pull. (Default value is None)

Raises

AttributeError – If invalid values exist.

pull_objects(dest, version=None)

Runs the pull_files() method to pull the dataset files into a given storage location.

Parameters

dest (str) – The destination path to store the pulled data files.
version (str) – A specified version of the data to pull. (Default value is None)

push_objects(node, files, connector='Objects:Files:v1', connectorProps=None, chunkSize=None)

Pushes data to a node.

Parameters

node (str) – The node to push the data to.
files (arr) – The data filepaths to push.
connector (str) – A specific type of connector to use on the data. This is specific to the file type. (Default value is ‘Objects:Files:v1’)
connectorProps (dict) – The properties for the connector. (Default value is None)
chunkSize (int64) – The size to chunk the data by. (Default value is None)

sync_objects(node, files, connector='Objects:Files:v1', connectorProps=None, chunkSize=None)

Sync files on a given node (Creating a new dataset if required).

Parameters

node (str) – The node to sync the data to.
files (arr) – The data filepaths to sync.
connector (str) – A specific type of connector to use on the data. This is specific to the file type. (Default value is ‘Objects:Files:v1’)
connectorProps (dict) – The properties for the connector. (Default value is None)
chunkSize (int64) – The size to chunk the data by. (Default value is None)

version()

Retrieves the version of the data.

Returns: The version of the data object.
Return type: str

versions()

Retrieves the data versions if exists.

Returns: The versions that exist for a data object.
Return type: list[str]

Operator

class Operator(adapter, ern=None, yaml=None, json=None, content=None)

Bases: object

A class used to interact with Eratos’ Operators.

conv_r_inputs(inputs)

conv_r_outputs(outputs)

ern()

Retrieves the unique Eratos Resource Name (ERN) for an operator.

Returns: The unique Eratos Resource Name (ERN).
Return type: Ern

examples()

Retrieves examples for an operator.

Raises: AssertionError – If the operator is not valid.
Returns: String examples.
Return type: str

find_input(name)

Retrieves an input’s properties in an operator based on a provided name.

Parameters: name (str) – Name of the input.
Returns: Object containing an input’s properties.
Return type: dict

help()

Retrieves a help message for an operator.

Raises: AssertionError – If the operator is not valid.
Returns: Help message.
Return type: str

is_valid()

Utility function to determine the validity of an operator’s fields.

Returns: True or False depending on the validity of a field.
Return type: bool

resource()

Retrieves the resource for an operator.

Returns: The underlying resource for the operator.
Return type: Resource

operator(ern)

A wrapper to define an Eratos Operator function.

Parameters: ern (str) – The Eratos Resource Name (ERN) string.
Returns: Wrapper or function.
Return type: Any

GeoSpatial Data

class GSData(adapter, resource, data)

Bases: object

A class to handle geospatial data.

decode_streaming_slices(req, dt, shp): Utility function to decode streaming slices.

dimensions()

Retrieves the dimensions for a given dataset.

Returns: The list of dimension dictionaries including a key, spacing, variable (is) and unit.
Return type: dict[]

get_3d_subset_as_array(var, startDate, endDate, bottomLeftPoint, topRightPoint, time_stride=1, lat_stride=1, lon_stride=1, verbose=True)

Extract a desired 3D subset for a given time range at a given location from an Eratos gridded dataset.

Parameters

var (str) – The variable key of the variable to fetch.
startDate (str) – The start date for the fetched timeseries. (ex. “2021-01-01” following the Eratos Date-Time Data Standards)
endDate (str) – The end date for the fetched timeseries. (ex. “2021-01-01” following the Eratos Date-Time Data Standards)
bottomLeftPoint (str) – The bottom left point for the fetched geospatial grid in Well-Known Text format. (ex. “POINT(147, -44)”)
topRightPoint (str) – The top right point for the fetched geospatial grid in Well-Known Text format. (ex. “POINT(147, -44)”)
time_stride (int) – The stride in the time dimension. (Default value is 1)
lat_stride (int) – The stride in the latitude dimension. (Default value is 1)
lon_stride (int) – The stride in the longitude dimension. (Default value is 1)
verbose (bool) – Prints statement that details the specifics of the output. (Default value is True)

Raises

TypeError – If invalid parameter types are present.
ValueError – If the location points are not in WKT format.

Returns

An array of the variable’s data for a given time range at a given location.

Return type

arr

get_geospatial_slice_at_times_as_array(var, time_list, bottomLeftPoint, topRightPoint, lat_stride=1, lon_stride=1, verbose=True)

Extract data for a given point at given times from an Eratos gridded dataset.

Parameters

var (str) – The variable key of the variable to fetch.
time_list (str[]) – An array of datetimes in Eratos Date-Times Data Standards (ex. “2021-01-01”), with a minimum of 1.
bottomLeftPoint (str) – The bottom left point for the fetched geospatial grid in Well-Known Text format. (ex. “POINT(147, -44)”)
topRightPoint (str) – The top right point for the fetched geospatial grid in Well-Known Text format. (ex. “POINT(147, -44)”)
lat_stride (int) – The stride in the latitude dimension. (Default value is 1)
lon_stride (int) – The stride in the longitude dimension. (Default value is 1)
verbose (bool) – Prints statement that details the specifics of the output. (Default value is True)

Raises

TypeError – If invalid parameter types are present.
Exception – If no location points are given.
ValueError – If the location points are not in WKT format.

Returns

An array of the variable’s data at given times in a given location.

Return type

arr

get_key_variables()

Get the keys for an Eratos gridded dataset’s variable(s).

Returns: A list of the dataset’s variable key(s).
Return type: arr

get_point_slices(var, mask, pts, starts=None, ends=None, strides=None, indexed=False)

Extract a desired subset of a given point from an Eratos gridded dataset.

Parameters

var (str) – The variable key of the variable to fetch.
mask (str) – The mask to apply to fetch.
pts (int[] or float[]) – A list of points to fetch.
starts (int[] or float[]) – A list of start numbers. (Default value is None)
ends (int[] or float[]) – A list of end numbers. (Default value is None)
strides (int[] or float[]) – A list of stride numbers. (Default value is None)
indexed (bool) – Set whether the points are indexed. (Default value is False)

Raises

Exception – Starts, ends, strides are invalid.

Returns

An array of the variable’s data.

Return type

arr

get_subset_as_array(var, starts=None, ends=None, strides=None)

Extract a desired subset from an Eratos gridded dataset.

Parameters

var (str) – The variable key of the variable to fetch.
starts (int[] or float[]) – A list of start numbers. (Default value is None)
ends (int[] or float[]) – A list of end numbers. (Default value is None)
strides (int[] or float[]) – A list of stride numbers. (Default value is None)

Raises

Exception – Starts, ends, strides are invalid.

Returns

An array of the variable’s data.

Return type

arr

get_timeseries_at_points(var, point_list, startDate, endDate, time_stride=1)

Extract desired timeseries data at given point(s) from an Eratos gridded dataset for a given time range.

Parameters

var (str) – The variable key of the variable to fetch.
point_list (str[]) – A list of Well-Known Text (WKT) formatted string points. (Minimum of 1)
startDate (str) – The start date for the fetched timeseries. (ex. “2021-01-01” following the Eratos Date-Time Data Standards)
endDate (str) – The end date for the fetched timeseries. (ex. “2021-01-01” following the Eratos Date-Time Data Standards)
time_stride (int) – The stride in the time dimension. Note: for a dataset with a daily temporal frequency ‘time_stride’ of 2, it would extract every second day. (Default value is 1)

Raises

TypeError – If invalid parameter types are present.
Exception – If no location points are given.
ValueError – If the location points are not in WKT format.

Returns

An array of the variable’s data at given location(s) for a given time range.

Return type

arr

perform_sapi_command_with_numpyres(params): Utility function.

spaces()

Retrieves the spaces for a given dataset.

Returns: The list of spaces.
Return type: str[]

variables()

Retrieves the variables.

Returns: The list of variables and their data types and spaces. The dictionary keys are the variable keys.
Return type: dict[]

datatype_to_bytesize(dt): Utility function to get the bytesize of a given data type.

Climate

list_dataset_block_facets(adapter, query='*', scenario=None, experiment=None, model=None, variable=None, region=None, temporalFrequency=None, lat=None, lon=None, location=None, cordexVariable=None, cordexModelId=None, cordexDrivingModelId=None, cordexExperimentId=None, cordexFrequency=None, cordexDrivingModelEnsembleMember=None, cordexDomain=None)

Lists the facets available.

list_dataset_block_facets() returns a list of facets (can be empty) for a dataset block according to specific query parameters for a given adapter.

Parameters

adapter (Adapter) – The Eratos adpater to query.
query (str) – String to query. (Default value is ‘*’)
scenario (str) – A specific scenario to search on. (Default value is None)
experiment (str) – A specific experiment to search on. (Default value is None)
model (str) – A specific model to search on. (Default value is None)
variable (str) – A specific variable to search on. (Default value is None)
region (str) – A specific region to search within. (Default value is None)
temporalFrequency (str) – A specific temporalFrequency to search on. (Default value is None)
lat (str) – A specific latitude to search on. (Default value is None)
lon (str) – A specific longitude to search on. (Default value is None)
location (str) – A specific location to search within. (Default value is None)
cordexVariable (str) – A specific CORDEX variable to search on. (Default value is None)
cordexModelId (str) – A specific CORDEX model ID to search on. (Default value is None)
cordexDrivingModelId (str) – A specific CORDEX driving model ID to search on. (Default value is None)
cordexExperimentId (str) – A specific CORDEX experiment ID to search on. (Default value is None)
cordexFrequency (str) – A specific CORDEX frequency to search on. (Default value is None)
cordexDrivingModelEnsembleMember (str) – A specific CORDEX driving model ensemble member to search on. (Default value is None)
cordexDomain (str) – A specific CORDEX domain to search on. (Default value is None)

Returns

An empty list or a list of facets.

Return type

arr

list_dataset_blocks(adapter, query='*', scenario=None, experiment=None, model=None, variable=None, region=None, temporalFrequency=None, lat=None, lon=None, location=None, cordexVariable=None, cordexModelId=None, cordexDrivingModelId=None, cordexExperimentId=None, cordexFrequency=None, cordexDrivingModelEnsembleMember=None, cordexDomain=None)

Lists the available dataset blocks.

list_dataset_blocks() returns a list of matching dataset block ERNs (can be empty) according to specific query parameters for a given adapter.

Parameters

adapter (Adapter) – The Eratos adpater to query.
query (str) – String to query. (Default value is ‘*’)
scenario (str) – A specific scenario to search on. (Default value is None)
experiment (str) – A specific experiment to search on. (Default value is None)
model (str) – A specific model to search on. (Default value is None)
variable (str) – A specific variable to search on. (Default value is None)
region (str) – A specific region to search within. (Default value is None)
temporalFrequency (str) – A specific temporalFrequency to search on. (Default value is None)
lat (str) – A specific latitude to search on. (Default value is None)
lon (str) – A specific longitude to search on. (Default value is None)
location (str) – A specific location to search within. (Default value is None)
cordexVariable (str) – A specific CORDEX variable to search on. (Default value is None)
cordexModelId (str) – A specific CORDEX model ID to search on. (Default value is None)
cordexDrivingModelId (str) – A specific CORDEX driving model ID to search on. (Default value is None)
cordexExperimentId (str) – A specific CORDEX experiment ID to search on. (Default value is None)
cordexFrequency (str) – A specific CORDEX frequency to search on. (Default value is None)
cordexDrivingModelEnsembleMember (str) – A specific CORDEX driving model ensemble member to search on. (Default value is None)
cordexDomain (str) – A specific CORDEX domain to search on. (Default value is None)

Returns

An empty list or a list of unique Eratos Resource Name (ERN) strings of type Block, containing datasets.

Return type

arr

list_experiments(adapter, query='*', cordexExperimentId=None)

Lists the experiments available.

list_experiments() returns a list of matching scenario ERNs (can be empty) according to specific query parameters for a given adapter.

Parameters

adapter (Adapter) – The Eratos adpater to query.
query (str) – String to query. (Default value is ‘*’)
cordexExperimentId (str) – A CORDEX specific string to search on. (Default value is None)

Returns

An empty list or a list of unique Eratos Resource Name (ERN) strings of type Scenario, containing climate experiments.

Return type

arr

list_models(adapter, query='*', cordexDrivingModelId=None)

Lists the models available.

list_models() returns a list of matching model ERNs (can be empty) according to specific query parameters for a given adapter.

Parameters

adapter (Adapter) – The Eratos adpater to query.
query (str) – String to query. (Default value is ‘*’)
cordexDrivingModelId (str) – A CORDEX specific string to search on. (Default value is None)

Returns

An empty list or a list of unique Eratos Resource Name (ERN) strings of type Model.

Return type

arr

list_regions(adapter, query='*', regionSet=None, cordexDomain=None, lat=None, lon=None, location=None)

Lists the regions available.

list_regions() returns a list of matching regions (can be empty) according to specific query parameters for a given adapter.

Parameters

adapter (Adapter) – The Eratos adpater to query.
query (str) – String to query. (Default value is ‘*’)
regionSet (str) – A specific regions string to search on. (Default value is None)
cordexDomain (str) – A CORDEX specific domain string to search on. (Default value is None)
lat (str) – A specific latitude to search on. (Default value is None)
lon (str) – A specific longitude to search on. (Default value is None)
location (str) – A specific location to search within. Can be an ERN or a WKT location string. (Default value is None)

Returns

An empty list or a list of unique region Eratos Resource Names (ERNs).

Return type

arr

list_variables(adapter, query='*', cordexVariable=None)

Lists the variables available.

list_variables() returns a list of matching variable ERNs (can be empty) according to specific query parameters for a given adapter.

Parameters

adapter (Adapter) – The Eratos adpater to query.
query (str) – String to query. (Default value is ‘*’)
cordexVariable (str) – A CORDEX specific string to search on. (Default value is None)

Returns

An empty list or a list of unique Eratos Resource Name (ERN) strings of type Variable.

Return type

arr

push_grid_timeseries_dataset(adapter, datasetId, dsName, varName, lat, lon, times, data): Pushes a gridded timeseries dataset for the Thin Plate Spine Interpolation (TPSI) model. (TBC)

Search

class SearchAdapter(adapter, return_limit=- 1, **kwargs)

Bases: object

A Search Adapter class for use with Eratos.

count()

Retrieves the number of items found in a search.

Returns: The number of items found.
Return type: int | None

facets()

Retrieves the facets in a search.

Returns: The facets if exists.
Return type: Any | dict | None

reset(return_limit=- 1, **kwargs)

Resets the search adapter object to certain parameters.

Parameters

return_limit (int) – A set return limit. (Default value is -1)
kwargs (args) – Optional keyword arguments for a search. Arguments can include any of: | query = A string to query (ex. ‘*’) | limit = An integer depicting the number of resources to limit the return (ex. 20) | start = An integer depicting the start index (ex. 0) | exclude = A list of ERNs to exclude. | type = A list of types to search for. | excludeType = A list of types to exclude from the search. | owner = A list of owner ERN’s to search against. | collections = A list of collection ERN’s to search against. | facets = A list of facets to search against. | geom = A geospatial geometry to search within.

Raises

TypeError – If an unexpected type is set.
ValueError – If the value returned is not within an expected range.

search(): Performs the search.

Utility Functions

class Merkle(hashes)

Bases: object

Generate a Merkle tree using the passed hashes.

build()

pprint()

root()

root_b64()

root_hex()

calc_best_chunk_size(files)

calc_chunksize_from_filesize(file_size): Calculate the required chunk size from a given file size.

calc_filemap_from_chunk(manifest, chunk_idx)

dataset_chunks(files, chunk_size): Output the chunks for a given dataset.

decode_request_content_response(req)

extract_pn_and_did(id)

fill_chunk_hash(content, chunk_size)

get_meta_items(files)

hash_dataset_chunks(files, chunk_size): Output the hashlist based on the files and chunk size.

move_prefix_to_new_format(content)

Errors

exception CommError(status_code, pdata)

Bases: BaseException

Comms errors class

exception DataError(msg)

Bases: BaseException

Data errors class

exception PolicyError(msg)

Bases: BaseException

Policy errors class

exception ResourceError(msg)

Bases: BaseException

Resource errors class

exception SearchError(msg)

Bases: BaseException

Search errors class

exception SliceError(msg)

Bases: BaseException

Slice errors class

Helpers

get_ncdf_dims(grp, d)

get_ncdf_vars(grp, d)

get_ncdf_varsex(grp, d)

guess_netcdf_api(file, dims={})

join_pfx(pfx, name)

print_gridded_dataset_meta_data(adapter, block_ERN)

Prints the metadata for a given gridded dataset within Eratos.

Parameters

adapter (Adapter) – The adapter with valid credentials to interact with the gridded dataset.
block_ERN (Ern) – The unique Eratos Resource Name (ERN) to the block containing the gridded dataset.

write_dataset_block_meta(fpath, resIter, propMap, verbose=False)