deprecate request UID in favour of ID (#15)

Author: malmans2

README.md

@@ -90,7 +90,7 @@ Retrieve data:
 'tmp1-era5.grib'
 
 >>> remote = client.submit(collection_id, request)  # doesn't block
->>> remote.request_uid
+>>> remote.request_id
 '...'
 >>> remote.status
 '...'
@@ -102,7 +102,7 @@ Retrieve data:
 Interact with a previously submitted job:
 
 ```python
->>> remote = client.get_remote(remote.request_uid)
+>>> remote = client.get_remote(remote.request_id)
 >>> remote.delete()
 {...}
 

datapi/api_client.py

@@ -181,13 +181,13 @@ def check_authentication(self) -> dict[str, Any]:
         """
         return self._profile_api.check_authentication()
 
-    def download_results(self, request_uid: str, target: str | None = None) -> str:
+    def download_results(self, request_id: str, target: str | None = None) -> str:
         """Download the results of a request.
 
         Parameters
         ----------
-        request_uid: str
-            Request UID.
+        request_id: str
+            Request ID.
         target: str or None
             Target path. If None, download to the working directory.
 
@@ -196,7 +196,7 @@ def download_results(self, request_uid: str, target: str | None = None) -> str:
         str
             Path to the retrieved file.
         """
-        return self.get_remote(request_uid).download(target)
+        return self.get_remote(request_id).download(target)
 
     def estimate_costs(self, collection_id: str, request: Any) -> dict[str, Any]:
         """Estimate costs of the parameters in a request.
@@ -321,35 +321,35 @@ def get_processes(
         }
         return self._retrieve_api.get_processes(**params)
 
-    def get_remote(self, request_uid: str) -> datapi.Remote:
+    def get_remote(self, request_id: str) -> datapi.Remote:
         """
         Retrieve the remote object of a request.
 
         Parameters
         ----------
-        request_uid: str
-            Request UID.
+        request_id: str
+            Request ID.
 
         Returns
         -------
         datapi.Remote
         """
-        return self._retrieve_api.get_job(request_uid).make_remote()
+        return self._retrieve_api.get_job(request_id).make_remote()
 
-    def get_results(self, request_uid: str) -> datapi.Results:
+    def get_results(self, request_id: str) -> datapi.Results:
         """
         Retrieve the results of a request.
 
         Parameters
         ----------
-        request_uid: str
-            Request UID.
+        request_id: str
+            Request ID.
 
         Returns
         -------
         datapi.Results
         """
-        return self.get_remote(request_uid).make_results()
+        return self.get_remote(request_id).make_results()
 
     def retrieve(
         self,

datapi/processing.py

@@ -384,7 +384,7 @@ class Remote:
     def __attrs_post_init__(self) -> None:
         self.log_start_time = None
         self.last_status = None
-        self.info(f"Request ID is {self.request_uid}")
+        self.info(f"Request ID is {self.request_id}")
 
     @property
     def _request_kwargs(self) -> RequestKwargs:
@@ -411,10 +411,20 @@ def _get_api_response(self, method: str, **kwargs: Any) -> ApiResponse:
         )
 
     @property
-    def request_uid(self) -> str:
-        """Request UID."""
+    def request_id(self) -> str:
+        """Request ID."""
         return self.url.rpartition("/")[2]
 
+    @property
+    def request_uid(self) -> str:
+        warnings.warn(
+            "`request_uid` has been deprecated, and in the future will raise an error."
+            "Please use `request_id` from now on.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.request_id
+
     @property
     def json(self) -> dict[str, Any]:
         """Content of the response."""
@@ -533,7 +543,7 @@ def _warn(self) -> None:
     def update(self, request_id: str | None = None) -> None:
         self._warn()
         if request_id:
-            assert request_id == self.request_uid
+            assert request_id == self.request_id
         try:
             del self.reply
         except AttributeError:
@@ -558,7 +568,7 @@ def reply(self) -> dict[str, Any]:
             except Exception as exc:
                 reply["error"].setdefault("message", str(exc))
 
-        reply.setdefault("request_id", self.request_uid)
+        reply.setdefault("request_id", self.request_id)
         return reply
 
     def log(self, *args: Any, **kwargs: Any) -> None:
@@ -599,10 +609,20 @@ class Jobs(ApiResponsePaginated):
     """A class to interact with submitted jobs."""
 
     @property
-    def request_uids(self) -> list[str]:
-        """List of request UIDs."""
+    def request_ids(self) -> list[str]:
+        """List of request IDs."""
         return [job["jobID"] for job in self._json_dict["jobs"]]
 
+    @property
+    def request_uids(self) -> list[str]:
+        warnings.warn(
+            "`request_uids` has been deprecated, and in the future will raise an error."
+            "Please use `request_ids` from now on.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.request_ids
+
 
 @attrs.define
 class Results(ApiResponse):

tests/integration_test_20_processing.py

@@ -60,16 +60,24 @@ def test_processing_estimate_costs(api_anon_client: ApiClient) -> None:
 
 def test_processing_get_jobs_status(api_anon_client: ApiClient) -> None:
     remote = api_anon_client.submit("test-adaptor-dummy", {"format": "foo"})
-    request_uid = remote.request_uid
+    request_id = remote.request_id
     with pytest.raises(HTTPError, match="400 Client Error: Bad Request"):
         remote.make_results()
-    assert request_uid in api_anon_client.get_jobs(status="failed").request_uids
-    assert request_uid not in api_anon_client.get_jobs(status="successful").request_uids
+    assert request_id in api_anon_client.get_jobs(status="failed").request_ids
+    assert request_id not in api_anon_client.get_jobs(status="successful").request_ids
 
 
 def test_processing_get_jobs_sortby(api_anon_client: ApiClient) -> None:
-    uid1 = api_anon_client.submit("test-adaptor-dummy", {}).request_uid
-    uid2 = api_anon_client.submit("test-adaptor-dummy", {}).request_uid
-    uids = api_anon_client.get_jobs(sortby="-created").request_uids
-    assert uids.index(uid2) < uids.index(uid1)
-    assert [uid2] != api_anon_client.get_jobs(sortby="created", limit=1).request_uids
+    id1 = api_anon_client.submit("test-adaptor-dummy", {}).request_id
+    id2 = api_anon_client.submit("test-adaptor-dummy", {}).request_id
+    ids = api_anon_client.get_jobs(sortby="-created").request_ids
+    assert ids.index(id2) < ids.index(id1)
+    assert [id2] != api_anon_client.get_jobs(sortby="created", limit=1).request_ids
+
+
+def test_deprecation_warnings(api_anon_client: ApiClient) -> None:
+    with pytest.warns(DeprecationWarning):
+        api_anon_client.submit("test-adaptor-dummy", {}).request_uid
+
+    with pytest.warns(DeprecationWarning):
+        api_anon_client.get_jobs().request_uids

tests/integration_test_30_remote.py

@@ -53,8 +53,8 @@ def test_remote_request(remote: Remote) -> None:
     }
 
 
-def test_remote_request_uid(remote: Remote) -> None:
-    assert uuid.UUID(remote.request_uid)
+def test_remote_request_id(remote: Remote) -> None:
+    assert uuid.UUID(remote.request_id)
 
 
 def test_remote_status(remote: Remote) -> None:
@@ -85,13 +85,13 @@ def test_remote_cleanup(
         url=api_root_url, key=api_anon_key, cleanup=cleanup, maximum_tries=0
     )
     remote = client.submit("test-adaptor-dummy", {})
-    request_uid = remote.request_uid
+    request_id = remote.request_id
     del remote
     time.sleep(1)
 
     client = ApiClient(url=api_root_url, key=api_anon_key, maximum_tries=0)
     with raises:
-        client.get_remote(request_uid)
+        client.get_remote(request_id)
 
 
 def test_remote_datetimes(api_anon_client: ApiClient) -> None:

tests/integration_test_60_api_client.py

@@ -15,7 +15,7 @@ def test_api_client_download_results(
     remote = api_anon_client.submit("test-adaptor-dummy", {})
     target = str(tmp_path / "test.grib")
 
-    result = api_anon_client.download_results(remote.request_uid, target)
+    result = api_anon_client.download_results(remote.request_id, target)
     assert result == target
     assert os.path.exists(result)
 
@@ -28,15 +28,15 @@ def test_api_client_get_process(api_anon_client: ApiClient) -> None:
 
 
 def test_api_client_get_remote(api_anon_client: ApiClient) -> None:
-    request_uid = api_anon_client.submit("test-adaptor-dummy", {}).request_uid
-    remote = api_anon_client.get_remote(request_uid)
-    assert remote.request_uid == request_uid
+    request_id = api_anon_client.submit("test-adaptor-dummy", {}).request_id
+    remote = api_anon_client.get_remote(request_id)
+    assert remote.request_id == request_id
     assert set(remote.headers) == {"User-Agent", "PRIVATE-TOKEN"}
 
 
 def test_api_client_get_results(api_anon_client: ApiClient) -> None:
-    request_uid = api_anon_client.submit("test-adaptor-dummy", {}).request_uid
-    results = api_anon_client.get_results(request_uid)
+    request_id = api_anon_client.submit("test-adaptor-dummy", {}).request_id
+    results = api_anon_client.get_results(request_id)
     assert isinstance(results, Results)