improve README and deprecate collection.submit

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:

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)
 
 

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"

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 == [