From 42d0062c86350861be5dd577941b5313d0fbd143 Mon Sep 17 00:00:00 2001
From: Stefaan Lippens <stefaan.lippens@vito.be>
Date: Wed, 19 Jul 2023 09:57:15 +0200
Subject: [PATCH] Minor doc updates on output format guessing in VectorCube
 #401/#449

---
 openeo/rest/datacube.py   |  3 ++-
 openeo/rest/vectorcube.py | 29 ++++++++++++++++++++++++++---
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/openeo/rest/datacube.py b/openeo/rest/datacube.py
index ac2147213..19ff97945 100644
--- a/openeo/rest/datacube.py
+++ b/openeo/rest/datacube.py
@@ -1933,7 +1933,8 @@ def download(
         options: Optional[dict] = None,
     ) -> Union[None, bytes]:
         """
-        Download the raster data cube, e.g. as GeoTIFF.
+        Execute synchronously and download the raster data cube, e.g. as GeoTIFF.
+
         If outputfile is provided, the result is stored on disk locally, otherwise, a bytes object is returned.
         The bytes object can be passed on to a suitable decoder for decoding.
 
diff --git a/openeo/rest/vectorcube.py b/openeo/rest/vectorcube.py
index 78ccd6d17..c9e63ff30 100644
--- a/openeo/rest/vectorcube.py
+++ b/openeo/rest/vectorcube.py
@@ -136,7 +136,27 @@ def execute(self) -> dict:
         """Executes the process graph of the imagery."""
         return self._connection.execute(self.flat_graph())
 
-    def download(self, outputfile: Union[str, pathlib.Path], format: Optional[str] = None, options: dict = None):
+    def download(
+        self,
+        outputfile: Optional[Union[str, pathlib.Path]] = None,
+        format: Optional[str] = None,
+        options: Optional[dict] = None,
+    ) -> Union[None, bytes]:
+        """
+        Execute synchronously and download the vector cube.
+
+        The result will be stored to the output path, when specified.
+        If no output path (or ``None``) is given, the raw download content will be returned as ``bytes`` object.
+
+        :param outputfile: (optional) output file to store the result to
+        :param format: (optional) output format to use.
+        :param options: (optional) additional output format options.
+        :return:
+
+        .. versionchanged:: 0.21.0
+            When not specified explicitly, output format is guessed from output file extension.
+
+        """
         # TODO #401 make outputfile optional (See DataCube.download)
         # TODO #401/#449 don't guess/override format if there is already a save_result with format?
         if format is None and outputfile:
@@ -163,8 +183,11 @@ def execute_batch(
 
         :param job_options:
         :param outputfile: The path of a file to which a result can be written
-        :param out_format: (optional) Format of the job result.
-        :param format_options: String Parameters for the job result format
+        :param out_format: (optional) output format to use.
+        :param format_options: (optional) additional output format options
+
+        .. versionchanged:: 0.21.0
+            When not specified explicitly, output format is guessed from output file extension.
         """
         if out_format is None and outputfile:
             # TODO #401/#449 don't guess/override format if there is already a save_result with format?