From 03acb03c076edf00d2c1d428b1b9fd4a7b091bdf Mon Sep 17 00:00:00 2001 From: malmans2 Date: Fri, 18 Oct 2024 09:54:24 +0200 Subject: [PATCH] improve README --- README.md | 36 +++++++++++++++++++++++--- cads_api_client/catalogue.py | 17 +++++------- tests/integration_test_10_catalogue.py | 9 +------ tests/test_10_processing.py | 8 +++--- 4 files changed, 43 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index c1ae33a..1c0faf4 100644 --- a/README.md +++ b/README.md @@ -13,18 +13,30 @@ $ cat $HOME/.cads-api-client.json It is possible (though not recommended) to use the API key of one of the test users, `00112233-4455-6677-c899-aabbccddeeff`. This key is used for anonymous tests and is designed to be the least performant option for accessing the system. -Draft Python API: +## Quick Start + +Configure the logging level to display INFO messages: ```python >>> import logging ->>> import os +>>> logging.basicConfig(level="INFO") + +``` + +Instantiate the API client and verify the authentication: +```python +>>> import os >>> from cads_api_client import ApiClient ->>> logging.basicConfig(level="INFO") >>> client = ApiClient(url=os.getenv("CADS_API_URL"), key=os.getenv("CADS_API_KEY")) >>> client.check_authentication() {...} +``` + +Explore a collection: + +```python >>> collection_id = "reanalysis-era5-pressure-levels" >>> collection = client.get_collection(collection_id) >>> collection.end_datetime @@ -36,9 +48,17 @@ datetime.datetime(...) ... "year": "2022", ... "month": "01", ... "day": "01", -... "level": "1000", +... "pressure_level": "1000", ... "time": "00:00", ... } +>>> collection.process.apply_constraints(**request) +{...} + +``` + +Retrieve data: + +```python >>> client.retrieve(collection_id, **request, target="tmp1-era5.grib") # blocks 'tmp1-era5.grib' @@ -52,6 +72,14 @@ datetime.datetime(...) ``` +Interact with a previously submitted job: + +```python +>>> client.get_remote(remote.request_uid) +Remote(...) + +``` + ## Workflow for developers/contributors For best experience create a new conda environment (e.g. DEVELOP) with Python 3.11: diff --git a/cads_api_client/catalogue.py b/cads_api_client/catalogue.py index 13c816d..a826cf7 100644 --- a/cads_api_client/catalogue.py +++ b/cads_api_client/catalogue.py @@ -1,6 +1,7 @@ from __future__ import annotations import datetime +import warnings from typing import Any, Callable import attrs @@ -88,17 +89,11 @@ def process(self) -> cads_api_client.Process: return cads_api_client.Process.from_request("get", url, **self._request_kwargs) def submit(self, **request: Any) -> cads_api_client.Remote: - """Submit a request. - - Parameters - ---------- - **request: Any - Request parameters. - - Returns - ------- - cads_api_client.Remote - """ + warnings.warn( + "`.submit` has been deprecated, and in the future will raise an error." + " Please use `.process.submit` from now on.", + DeprecationWarning, + ) return self.process.submit(**request) diff --git a/tests/integration_test_10_catalogue.py b/tests/integration_test_10_catalogue.py index d4fb48a..f8300a2 100644 --- a/tests/integration_test_10_catalogue.py +++ b/tests/integration_test_10_catalogue.py @@ -1,6 +1,6 @@ import pytest -from cads_api_client import ApiClient, Collection, Remote, processing +from cads_api_client import ApiClient, Collection, processing @pytest.fixture @@ -41,13 +41,6 @@ def test_catalogue_collections_keywords(api_anon_client: ApiClient) -> None: assert collections.collection_ids -def test_catalogue_collection_submit(collection: Collection) -> None: - remote = collection.submit(date="1990-01-01") - assert isinstance(remote, Remote) - assert remote.collection_id == "test-adaptor-mars" - assert remote.request == {"date": "1990-01-01"} - - def test_catalogue_collection_begin_datetime(collection: Collection) -> None: assert collection.begin_datetime is not None assert collection.begin_datetime.isoformat() == "1959-01-01T00:00:00+00:00" diff --git a/tests/test_10_processing.py b/tests/test_10_processing.py index dd2a75e..bb85594 100644 --- a/tests/test_10_processing.py +++ b/tests/test_10_processing.py @@ -376,7 +376,7 @@ def test_submit(cat: catalogue.Catalogue) -> None: remote = collection.process.submit(variable="temperature", year="2022") assert remote.json == JOB_SUCCESSFUL_JSON - remote = collection.submit(variable="temperature", year="2022") + remote = collection.process.submit(variable="temperature", year="2022") assert remote.url == JOB_SUCCESSFUL_URL assert remote.status == "successful" assert remote.results_ready is True @@ -393,7 +393,7 @@ def test_wait_on_result(cat: catalogue.Catalogue) -> None: responses_add() collection = cat.get_collection(COLLECTION_ID) - remote = collection.submit(variable="temperature", year="2022") + remote = collection.process.submit(variable="temperature", year="2022") remote._wait_on_results() @@ -402,7 +402,7 @@ def test_wait_on_result_failed(cat: catalogue.Catalogue) -> None: responses_add() collection = cat.get_collection(COLLECTION_ID) - remote = collection.submit(variable="temperature", year="0000") + remote = collection.process.submit(variable="temperature", year="0000") with pytest.raises( processing.ProcessingFailedError, match="job failed\nThis is a traceback", @@ -425,7 +425,7 @@ def test_remote_logs( collection = cat.get_collection(COLLECTION_ID) with caplog.at_level(logging.DEBUG, logger="cads_api_client.processing"): - remote = collection.submit(variable="temperature", year="2022") + remote = collection.process.submit(variable="temperature", year="2022") remote._wait_on_results() assert caplog.record_tuples == [