导航|地址|刷新
ecmwf-datastores-client — ecmwf.datastor…


Skip to main content


Back to topCtrl+K





ecmwf.datastores 0.5.3 documentation






ecmwf-datastores-client

API Reference




SearchCtrl+K



System Settings

Light

Dark





SearchCtrl+K








ecmwf-datastores-client

API Reference






System Settings

Light

Dark






Collapse SidebarExpand Sidebar


Section Navigation




















ecmwf-datastores-client










Quick Start • Installation • Documentation


ecmwf-datastores-client#

ECMWF Data Stores Service (DSS) API Python client.


Important

This software is Graduated and subject to ECMWF’s guidelines on Software Maturity.


Technical documentation: https://ecmwf.github.io/ecmwf-datastores-client/


Installation#

Install with conda:


$ conda install -c conda-forge ecmwf-datastores-client


Install with pip:


$ pip install ecmwf-datastores-client




Configuration#

The Client requires the url to the API root and a valid API key. These can be provided in three ways, in order of precedence:


As keyword arguments when instantiating the Client.



Via the ECMWF_DATASTORES_URL and ECMWF_DATASTORES_KEY environment variables.



From a configuration file, which must be located at ~/.ecmwfdatastoresrc or at the path specified by the ECMWF_DATASTORES_RC_FILE environment variable.



$ cat $HOME/.ecmwfdatastoresrc url: https://cds.climate.copernicus.eu/api key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx




Quick Start#

Configure the logging level to display INFO messages:


>>> importlogging>>> logging.basicConfig(level="INFO")



Note

All Python code examples in this README are automatically tested as part of the unit test suite.


Instantiate the API client and optionally verify authentication:


>>> fromecmwf.datastoresimportClient>>> client=Client()>>> client.check_authentication()# optional check{...}


Retrieve data:


>>> collection_id="reanalysis-era5-pressure-levels">>> request={... "product_type":["reanalysis"],... "variable":["temperature"],... "year":["2022"],... "month":["01"],... "day":["01"],... "time":["00:00"],... "pressure_level":["1000"],... "data_format":"grib",... "download_format":"unarchived",... }>>> client.retrieve(collection_id,request,target="target_1.grib")# blocks'target_1.grib'


Alternative methods to retrieve data:


>>> remote=client.submit(collection_id,request)# doesn't block>>> remoteRemote(...)>>> remote.download("target_2.grib")# blocks'target_2.grib'>>> results=client.submit_and_wait_on_results(collection_id,request)# blocks>>> resultsResults(...)>>> results.download("target_3.grib")'target_3.grib'>>> client.download_results(remote.request_id,"target_4.grib")# blocks'target_4.grib'


List all collection IDs sorted by last update:


>>> collections=client.get_collections(sortby="update")>>> collection_ids=[]>>> whilecollectionsisnotNone:# Loop over pages... collection_ids.extend(collections.collection_ids)... collections=collections.next# Move to the next page...>>> collection_ids[...]>>> collection_idincollection_idsTrue


Explore a collection:


>>> collection=client.get_collection(collection_id)>>> collection.id==collection_idTrue>>> collection.title'...'>>> collection.description'...'>>> collection.published_atdatetime.datetime(...)>>> collection.updated_atdatetime.datetime(...)>>> collection.begin_datetimedatetime.datetime(...)>>> collection.end_datetimedatetime.datetime(...)>>> collection.bbox(...)>>> collection.submit(request)Remote(...)>>> collection.apply_constraints(request){...}


Interact with results:


>>> results=client.get_results(remote.request_id)>>> results.content_length>0True>>> results.content_type'application/x-grib'>>> results.location'...'>>> results.download("target_5.grib")'target_5.grib'


List all successful jobs, sorted by newest first:


>>> jobs=client.get_jobs(sortby="-created",status="successful")>>> request_ids=[]>>> whilejobsisnotNone:# Loop over pages... request_ids.extend(jobs.request_ids)... jobs=jobs.next# Move to the next page...>>> request_ids[...]>>> remote.request_idinrequest_idsTrue


Interact with a previously submitted job:


>>> remote=client.get_remote(remote.request_id)>>> remote.collection_id==collection_idTrue>>> remote.request{...}>>> remote.status'successful'>>> remote.results_readyTrue>>> remote.created_at# See also started_at, finished_at, updated_atdatetime.datetime(...)>>> remote.download("target_6.grib")'target_6.grib'>>> remote.get_receipt(){...}>>> remote.get_results()Results(...)>>> remote.delete(){...}


Apply constraints and find the number of available days in a given month:


>>> month={"year":"2000","month":"02"}>>> constrained_request=client.apply_constraints(collection_id,month)>>> len(constrained_request["day"])29




Developer Workflow#


1. Set Up the Environment#

Configure your virtual environment and pre-commit hooks:


makeinstall



Note

This project uses uv for dependency management. Commit the generated uv.lock file to version control.




2. Run Quality Assurance#

Check formatting, linting, and lockfile consistency:


makeqa




3. Commit and Push#

Save and push any automatically formatted changes:


gitadd. gitcommit-m"format codebase and sync lockfile" gitpushoriginHEAD


The CI/CD pipeline triggers on pull requests, merges to main/upstream, and new releases.




Using the Makefile#

All development tasks are exposed as self-documenting targets in the Makefile. To see a complete list of available targets and their descriptions, run:


makehelp


This displays all available utility commands, including:


Environment setup: makeinstall



Quality assurance: makeqa



Unit tests: makeunit-tests



Type checking: maketype-check


To run the full set of quality checks, tests, and build steps in a single command, use:


makeall




License#


Copyright2022,EuropeanUnion.LicensedundertheApacheLicense,Version2.0(the"License");youmaynotusethisfileexceptincompliancewiththeLicense.YoumayobtainacopyoftheLicenseathttp://www.apache.org/licenses/LICENSE-2.0Unlessrequiredbyapplicablelaworagreedtoinwriting,softwaredistributedundertheLicenseisdistributedonan"AS IS"BASIS,WITHOUTWARRANTIESORCONDITIONSOFANYKIND,eitherexpressorimplied.SeetheLicenseforthespecificlanguagegoverningpermissionsandlimitationsundertheLicense.







previous

Welcome to ecmwf-datastores-client’s documentation!



next

datastores







On this page

Installation

Configuration

Quick Start

Developer Workflow
1. Set Up the Environment

2. Run Quality Assurance

3. Commit and Push


Using the Makefile

License



Show Source










© Copyright 2022, European Union.




Created using Sphinx 9.1.0.






Built with the PyData Sphinx Theme 0.20.0.




------
导航页 打开网址