datastores.Client#

class datastores.Client#

ECMWF Data Stores Service (DSS) API Python client.

Parameters:

  • url (str or None, default: None) – API URL. If None, infer from ECMWF_DATASTORES_URL or ECMWF_DATASTORES_RC_FILE.

  • key (str or None, default: None) – API Key. If None, infer from ECMWF_DATASTORES_KEY or ECMWF_DATASTORES_RC_FILE.

  • verify (bool, default: True) – Whether to verify the TLS certificate at the remote end.

  • timeout (float or tuple[float,float], default: 60) – How many seconds to wait for the server to send data, as a float, or a (connect, read) tuple.

  • progress (bool, default: True) – Whether to display the progress bar during download.

  • cleanup (bool, default: False) – Whether to delete requests after completion.

  • sleep_max (float, default: 120) – Maximum time to wait (in seconds) while checking for a status change.

  • retry_after (float, default: 120) – Time to wait (in seconds) between retries.

  • maximum_tries (int, default: 500) – Maximum number of retries.

  • session (requests.Session) – Requests session.

apply_constraints(collection_id, request)#

Apply constraints to the parameters in a request.

Parameters:

  • collection_id (str) – Collection ID (e.g., "projections-cmip6").

  • request (dict[str,Any]) – Request parameters.

Returns:

Dictionary of valid values.

Return type:

dict[str,Any]

check_authentication()#

Verify authentication.

Returns:

Content of the response.

Return type:

dict[str,Any]

Raises:

requests.HTTPError – If the authentication fails.

delete(*request_ids)#

Delete requests.

Parameters:

*request_ids (str) – Request IDs.

Returns:

Content of the response.

Return type:

dict[str,Any]

download_results(request_id, target=None)#

Download the results of a request.

Parameters:

  • request_id (str) – Request ID.

  • target (str or None) – Target path. If None, download to the working directory.

Returns:

Path to the retrieved file.

Return type:

str

get_collection(collection_id)#

Retrieve a catalogue collection.

Parameters:

collection_id (str) – Collection ID (e.g., "projections-cmip6").

Return type:

datastores.Collection

get_collections(limit=None, sortby=None, query=None, keywords=None)#

Retrieve catalogue collections.

Parameters:

  • limit (int | None) – Number of collections per page.

  • sortby ({None, 'id', 'relevance', 'title', 'update'}) – Field to sort results by.

  • query (str or None) – Full-text search query.

  • keywords (list[str] or None) – Filter by keywords.

Return type:

datastores.Collections

get_jobs(limit=None, sortby=None, status=None)#

Retrieve submitted jobs.

Parameters:

  • limit (int or None) – Number of jobs per page.

  • sortby ({None, 'created', '-created'}) – Field to sort results by.

  • status (None or {'accepted', 'running', 'successful', 'failed', 'rejected'} or list) – Status of the results.

Return type:

datastores.Jobs

get_remote(request_id)#

Retrieve the remote object of a request.

Parameters:

request_id (str) – Request ID.

Return type:

datastores.Remote

get_results(request_id)#

Retrieve the results of a request.

Parameters:

request_id (str) – Request ID.

Return type:

datastores.Results

retrieve(collection_id, request, target=None)#

Submit a request and retrieve the results.

Parameters:

  • collection_id (str) – Collection ID (e.g., "projections-cmip6").

  • request (dict[str,Any]) – Request parameters.

  • target (str or None) – Target path. If None, download to the working directory.

Returns:

Path to the retrieved file.

Return type:

str

submit(collection_id, request)#

Submit a request.

Parameters:

  • collection_id (str) – Collection ID (e.g., "projections-cmip6").

  • request (dict[str,Any]) – Request parameters.

Return type:

datastores.Remote

submit_and_wait_on_results(collection_id, request)#

Submit a request and wait for the results to be ready.

Parameters:

  • collection_id (str) – Collection ID (e.g., "projections-cmip6").

  • request (dict[str,Any]) – Request parameters.

Return type:

datastores.Results