PR #727 also check return description

and involve Connection and BatchJob

Author: soxofaan

openeo/internal/documentation.py

@@ -81,6 +81,16 @@ def extract_params(doc: Union[str, Callable]) -> Dict[str, str]:
     return {m.group("param"): m.group("doc").strip() for m in params_regex.finditer(doc)}
 
 
+def extract_return(doc: Union[str, Callable]) -> Union[str, None]:
+    """
+    Extract return value description (``:return:`` format) from a docstring.
+    """
+    doc = _get_doc(doc)
+    return_regex = re.compile(r"^:return\s*:(?P<doc>.*(\n +.*)*)", re.MULTILINE)
+    matches = [m.group("doc").strip() for m in return_regex.finditer(doc)]
+    assert 0 <= len(matches) <= 1
+    return matches[0] if matches else None
+
 def assert_same_param_docs(doc_a: Union[str, Callable], doc_b: Union[str, Callable], only_intersection: bool = False):
     """
     Compare parameters (``:param name:`` format) from two docstrings.
@@ -95,3 +105,10 @@ def assert_same_param_docs(doc_a: Union[str, Callable], doc_b: Union[str, Callab
         params_b = {k: v for k, v in params_b.items() if k in intersection}
 
     assert params_a == params_b
+
+
+def assert_same_return_docs(doc_a: Union[str, Callable], doc_b: Union[str, Callable]):
+    """
+    Compare return value descriptions from two docstrings.
+    """
+    assert extract_return(doc_a) == extract_return(doc_b)

openeo/rest/connection.py

@@ -1565,15 +1565,18 @@ def download(
 
         :param graph: (flat) dict representing a process graph, or process graph as raw JSON string,
             or as local file path or URL
-        :param outputfile: output file
+        :param outputfile: (optional) output path to download to.
         :param timeout: timeout to wait for response
-        :param validate: Optional toggle to enable/prevent validation of the process graphs before execution
+        :param validate: (optional) toggle to enable/prevent validation of the process graphs before execution
             (overruling the connection's ``auto_validate`` setting).
         :param chunk_size: chunk size for streaming response.
-        :param additional: additional (top-level) properties to set in the request body
-        :param job_options: dictionary of job options to pass to the backend
+        :param additional: (optional) additional (top-level) properties to set in the request body
+        :param job_options: (optional) dictionary of job options to pass to the backend
             (under top-level property "job_options")
 
+        :return: ``None`` if ``outputfile`` was specified to store to disk.
+            Otherwise, a :py:class:`bytes` object containing the raw data.
+
         .. versionadded:: 0.36.0
             Added arguments ``additional`` and ``job_options``.
         """
@@ -1595,6 +1598,7 @@ def download(
             with target.open(mode="wb") as f:
                 for chunk in response.iter_content(chunk_size=chunk_size):
                     f.write(chunk)
+            # TODO: return target path instead of None? Or return a generic result wrapper?
         else:
             return response.content
 
@@ -1667,19 +1671,20 @@ def create_job(
             a string with a JSON representation,
             a local file path or URL to a JSON representation,
             a :py:class:`~openeo.rest.multiresult.MultiResult` object, ...
-        :param title: job title
-        :param description: job description
-        :param plan: The billing plan to process and charge the job with
-        :param budget: Maximum budget to be spent on executing the job.
+        :param title: (optional) job title.
+        :param description: (optional) job description.
+        :param plan: (optional) the billing plan to process and charge the job with.
+        :param budget: (optional) maximum budget to be spent on executing the job.
             Note that some backends do not honor this limit.
-        :param additional: additional (top-level) properties to set in the request body
-        :param job_options: dictionary of job options to pass to the backend
+        :param additional: (optional) additional (top-level) properties to set in the request body
+        :param job_options: (optional) dictionary of job options to pass to the backend
             (under top-level property "job_options")
-        :param validate: Optional toggle to enable/prevent validation of the process graphs before execution
+        :param validate: (optional) toggle to enable/prevent validation of the process graphs before execution
             (overruling the connection's ``auto_validate`` setting).
-        :param log_level: Optional minimum severity level for log entries that the back-end should keep track of.
+        :param log_level: (optional) minimum severity level for log entries that the back-end should keep track of.
             One of "error" (highest severity), "warning", "info", and "debug" (lowest severity).
-        :return: Created job
+
+        :return: Handle to the job created at the backend.
 
         .. versionchanged:: 0.35.0
             Add :ref:`multi-result support <multi-result-process-graphs>`.

openeo/rest/datacube.py

@@ -2399,7 +2399,8 @@ def download(
         :param job_options: (optional) dictionary of job options to pass to the backend
             (under top-level property "job_options")
 
-        :return: None if the result is stored to disk, or a bytes object returned by the backend.
+        :return: ``None`` if ``outputfile`` was specified to store to disk.
+            Otherwise, a :py:class:`bytes` object containing the raw data.
 
         .. versionchanged:: 0.32.0
             Added ``auto_add_save_result`` option
@@ -2564,6 +2565,8 @@ def execute_batch(
         :param connection_retry_interval: how long to wait when status poll failed due to connection issue
         :param print: print/logging function to show progress/status
 
+        :return: Handle to the job created at the backend.
+
         .. versionchanged:: 0.32.0
             Added ``auto_add_save_result`` option
 
@@ -2648,7 +2651,7 @@ def create_job(
         :param log_level: (optional) minimum severity level for log entries that the back-end should keep track of.
             One of "error" (highest severity), "warning", "info", and "debug" (lowest severity).
 
-        :return: Handle for the job created at the backend.
+        :return: Handle to the job created at the backend.
 
         .. versionchanged:: 0.32.0
             Added ``auto_add_save_result`` option

openeo/rest/job.py

@@ -233,12 +233,14 @@ def run_synchronous(
         """
         Start the job, wait for it to finish and download result
 
-        :param outputfile: The path of a file to which a result can be written
+        :param outputfile: (optional) output path to download to.
         :param print: print/logging function to show progress/status
         :param max_poll_interval: maximum number of seconds to sleep between job status polls
         :param connection_retry_interval: how long to wait when status poll failed due to connection issue
         :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

@@ -111,6 +111,8 @@ def execute_batch(
         :param connection_retry_interval: how long to wait when status poll failed due to connection issue
         :param print: print/logging function to show progress/status
 
+        :return: Handle to the job created at the backend.
+
         .. versionchanged:: 0.36.0
             Added argument ``additional``.
 
@@ -170,7 +172,8 @@ def create_job(
             (under top-level property "job_options")
         :param log_level: (optional) minimum severity level for log entries that the back-end should keep track of.
             One of "error" (highest severity), "warning", "info", and "debug" (lowest severity).
-        :return: Created job.
+
+        :return: Handle to the job created at the backend.
 
         .. versionchanged:: 0.36.0
             Added argument ``additional``.

openeo/rest/stac_resource.py

@@ -81,7 +81,8 @@ def download(
         :param job_options: (optional) dictionary of job options to pass to the backend
             (under top-level property "job_options")
 
-        :return: None if the result is stored to disk, or a bytes object returned by the backend.
+        :return: ``None`` if ``outputfile`` was specified to store to disk.
+            Otherwise, a :py:class:`bytes` object containing the raw data.
         """
         return self._connection.download(
             graph=self.flat_graph(),
@@ -126,7 +127,7 @@ def create_job(
         :param log_level: (optional) minimum severity level for log entries that the back-end should keep track of.
             One of "error" (highest severity), "warning", "info", and "debug" (lowest severity).
 
-        :return: Handle for the job created at the backend.
+        :return: Handle to the job created at the backend.
         """
         return self._connection.create_job(
             process_graph=self.flat_graph(),
@@ -192,6 +193,7 @@ def execute_batch(
         :param connection_retry_interval: how long to wait when status poll failed due to connection issue
         :param show_error_logs: whether to automatically print error logs when the batch job failed.
 
+        :return: Handle to the job created at the backend.
         """
         job = self.create_job(
             title=title,

openeo/rest/vectorcube.py

@@ -260,6 +260,9 @@ def download(
         :param job_options: (optional) dictionary of job options to pass to the backend
             (under top-level property "job_options")
 
+        :return: ``None`` if ``outputfile`` was specified to store to disk.
+            Otherwise, a :py:class:`bytes` object containing the raw data.
+
         .. versionchanged:: 0.21.0
             When not specified explicitly, output format is guessed from output file extension.
 
@@ -336,6 +339,8 @@ def execute_batch(
         :param connection_retry_interval: how long to wait when status poll failed due to connection issue
         :param print: print/logging function to show progress/status
 
+        :return: Handle to the job created at the backend.
+
         .. versionchanged:: 0.21.0
             When not specified explicitly, output format is guessed from output file extension.
 
@@ -418,7 +423,7 @@ def create_job(
         :param log_level: (optional) minimum severity level for log entries that the back-end should keep track of.
             One of "error" (highest severity), "warning", "info", and "debug" (lowest severity).
 
-        :return: Created job.
+        :return: Handle to the job created at the backend.
 
         .. versionchanged:: 0.32.0
             Added ``auto_add_save_result`` option

tests/internal/test_documentation.py

@@ -1,56 +1,86 @@
+import inspect
+
 import pytest
 
-from openeo import DataCube, VectorCube
-from openeo.internal.documentation import assert_same_param_docs, extract_params
+from openeo import BatchJob, Connection, DataCube, VectorCube
+from openeo.internal.documentation import (
+    assert_same_param_docs,
+    assert_same_return_docs,
+    extract_params,
+    extract_return,
+)
 from openeo.rest.mlmodel import MlModel
 from openeo.rest.stac_resource import StacResource
 
 
 def test_extract_params():
-    assert (
-        extract_params(
-            """
-                The description
+    doc = """
+        The description
+
+        and more
+
+        :param a: description of a
+        :param b_b : multi-line description
+            of b
+
+        That's it!
+    """
+    assert extract_params(doc) == {
+        "a": "description of a",
+        "b_b": "multi-line description\n    of b",
+    }
 
-                and more
 
-                :param a: description of a
-                :param b_b : multi-line description
-                    of b
+def test_extract_return():
+    doc = """
+        The description
 
-                That's it!
-                """
-        )
-        == {
-            "a": "description of a",
-            "b_b": "multi-line description\n    of b",
-        }
-    )
+        and more
 
+        :param a: description of a
 
+        :return: the result
+            of the operation
+
+        That's it!
+    """
+
+    assert extract_return(doc) == "the result\n    of the operation"
 
 
 @pytest.mark.parametrize(
-    ["method_a", "method_b", "only_intersection"],
+    ["method_a", "method_b"],
     [
+        # Connection vs DataCube
+        (Connection.download, DataCube.download),
+        (Connection.create_job, DataCube.create_job),
         # Compare DataCube methods internally
-        (DataCube.download, DataCube.create_job, True),
-        (DataCube.download, DataCube.execute_batch, True),
-        (DataCube.create_job, DataCube.execute_batch, True),
+        (DataCube.download, DataCube.create_job),
+        (DataCube.download, DataCube.execute_batch),
+        (DataCube.create_job, DataCube.execute_batch),
+        # DataCube vs BatchJob
+        (BatchJob.run_synchronous, DataCube.execute_batch),
         # DataCube vs VectorCube
-        (DataCube.download, VectorCube.download, False),
-        (DataCube.create_job, VectorCube.create_job, False),
-        (DataCube.execute_batch, VectorCube.execute_batch, False),
-        (DataCube.save_result, VectorCube.save_result, False),
+        (DataCube.download, VectorCube.download),
+        (DataCube.create_job, VectorCube.create_job),
+        (DataCube.execute_batch, VectorCube.execute_batch),
+        (DataCube.save_result, VectorCube.save_result),
         # DataCube vs MlModel
-        (DataCube.create_job, MlModel.create_job, True),
-        (DataCube.execute_batch, MlModel.execute_batch, True),
+        (DataCube.create_job, MlModel.create_job),
+        (DataCube.execute_batch, MlModel.execute_batch),
         # DataCube vs StacResource
-        (DataCube.download, StacResource.download, True),
-        (DataCube.create_job, StacResource.create_job, True),
-        (DataCube.execute_batch, StacResource.execute_batch, True),
+        (DataCube.download, StacResource.download),
+        (DataCube.create_job, StacResource.create_job),
+        (DataCube.execute_batch, StacResource.execute_batch),
     ],
 )
-def test_compare_download_execute_params(method_a, method_b, only_intersection):
+def test_cube_processing_params_and_return(method_a, method_b):
+    """Check params/return of cube download/execute related methods"""
+    signature_a = inspect.signature(method_a)
+    signature_b = inspect.signature(method_b)
+
+    only_intersection = set(signature_a.parameters.keys()) != set(signature_b.parameters.keys())
     assert_same_param_docs(method_a, method_b, only_intersection=only_intersection)
-    # TODO: compare return description
+
+    if signature_a.return_annotation == signature_b.return_annotation:
+        assert_same_return_docs(method_a, method_b)