Merge branch 'issue570-Deprecate-run_synchronous'

Author: soxofaan

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - `DataCube.save_result()` (and related methods) now return a `SaveResult`/`StacResource` object instead of another `DataCube` object to be more in line with the official `save_result` specification ([#402](https://github.com/Open-EO/openeo-python-client/issues/402), [#720](https://github.com/Open-EO/openeo-python-client/issues/720))
+- Deprecate `BatchJob.run_synchronous` in favor of `BatchJob.start_and_wait` ([#570](https://github.com/Open-EO/openeo-python-client/issues/570)).
 
 ### Removed
 

examples/vito_example.py

@@ -42,6 +42,8 @@
 job = datacube.create_job()
 if job:
     print(job.job_id)
-    print(job.run_synchronous("/tmp/testfile"))
+    job.start_and_wait()
+    job.download_result(target="/tmp/testfile")
+    print(job)
 else:
     print("Job ID is None")

openeo/rest/datacube.py

@@ -2607,13 +2607,15 @@ def execute_batch(
             log_level=log_level,
             **create_kwargs,
         )
-        return job.run_synchronous(
-            outputfile=outputfile,
+        job.start_and_wait(
             print=print,
             max_poll_interval=max_poll_interval,
             connection_retry_interval=connection_retry_interval,
             show_error_logs=show_error_logs,
         )
+        if outputfile is not None:
+            job.download_result(target=outputfile)
+        return job
 
     def create_job(
         self,

openeo/rest/job.py

@@ -222,6 +222,7 @@ def logs(self, offset: Optional[str] = None, level: Union[str, int, None] = None
         response_data = self.connection.get(url, params=params, expected_status=200).json()
         return LogsResponse(response_data=response_data, log_level=level)
 
+    @deprecated("Use start_and_wait instead", version="0.39.0")
     def run_synchronous(
         self,
         outputfile: Union[str, Path, None] = None,
@@ -272,6 +273,8 @@ def start_and_wait(
         :param soft_error_max: maximum number of soft errors (e.g. temporary connection glitches) to allow
         :param show_error_logs: whether to automatically print error logs when the batch job failed.
 
+        :return: Handle to the job created at the backend.
+
         .. versionchanged:: 0.37.0
             Added argument ``show_error_logs``.
         """

openeo/rest/mlmodel.py

@@ -131,14 +131,15 @@ def execute_batch(
             job_options=job_options,
             log_level=log_level,
         )
-        return job.run_synchronous(
-            # TODO #135 support multi file result sets too
-            outputfile=outputfile,
+        job.start_and_wait(
             print=print,
             max_poll_interval=max_poll_interval,
             connection_retry_interval=connection_retry_interval,
             show_error_logs=show_error_logs,
         )
+        if outputfile is not None:
+            job.download_result(target=outputfile)
+        return job
 
     def create_job(
         self,

openeo/rest/multiresult.py

@@ -112,4 +112,4 @@ def execute_batch(
             validate=validate,
             log_level=log_level,
         )
-        return job.run_synchronous()
+        return job.start_and_wait()

openeo/rest/stac_resource.py

@@ -207,10 +207,12 @@ def execute_batch(
             validate=validate,
             log_level=log_level,
         )
-        return job.run_synchronous(
-            outputfile=outputfile,
+        job.start_and_wait(
             print=print,
             max_poll_interval=max_poll_interval,
             connection_retry_interval=connection_retry_interval,
             show_error_logs=show_error_logs,
         )
+        if outputfile is not None:
+            job.download_result(target=outputfile)
+        return job

openeo/rest/vectorcube.py

@@ -383,14 +383,15 @@ def execute_batch(
             log_level=log_level,
             **create_kwargs,
         )
-        return job.run_synchronous(
-            # TODO #135 support multi file result sets too
-            outputfile=outputfile,
+        job.start_and_wait(
             print=print,
             max_poll_interval=max_poll_interval,
             connection_retry_interval=connection_retry_interval,
             show_error_logs=show_error_logs,
         )
+        if outputfile is not None:
+            job.download_result(target=outputfile)
+        return job
 
     def create_job(
         self,

tests/internal/test_documentation.py

@@ -55,7 +55,7 @@ def test_extract_main_description():
         (DataCube.download, DataCube.execute_batch),
         (DataCube.create_job, DataCube.execute_batch),
         # DataCube vs BatchJob
-        (BatchJob.run_synchronous, DataCube.execute_batch),
+        (BatchJob.start_and_wait, DataCube.execute_batch),
         # DataCube vs VectorCube
         (DataCube.download, VectorCube.download),
         (DataCube.create_job, VectorCube.create_job),