PR #727 also check main description

soxofaan · soxofaan · commit bae921a00c99 · 2025-02-13T13:28:14.000+01:00
diff --git a/openeo/internal/documentation.py b/openeo/internal/documentation.py
@@ -7,7 +7,7 @@
 import re
 import textwrap
 from functools import partial
-from typing import Callable, Dict, Optional, Tuple, TypeVar, Union
+from typing import Callable, Dict, List, Optional, Sequence, Tuple, TypeVar, Union
 
 # TODO: give this a proper public API?
 _process_registry = collections.defaultdict(list)
@@ -61,7 +61,7 @@ def decorate(f: Callable) -> Callable:
     return decorate
 
 
-def _get_doc(obj: Union[str, Callable]) -> str:
+def get_docstring(obj: Union[str, Callable]) -> str:
     """
     Get docstring of a method or function.
     """
@@ -76,7 +76,7 @@ def extract_params(doc: Union[str, Callable]) -> Dict[str, str]:
     """
     Extract parameters (``:param name:`` format) from a docstring.
     """
-    doc = _get_doc(doc)
+    doc = get_docstring(doc)
     params_regex = re.compile(r"^:param\s+(?P<param>\w+)\s*:(?P<doc>.*(\n +.*)*)", re.MULTILINE)
     return {m.group("param"): m.group("doc").strip() for m in params_regex.finditer(doc)}
 
@@ -85,12 +85,27 @@ def extract_return(doc: Union[str, Callable]) -> Union[str, None]:
     """
     Extract return value description (``:return:`` format) from a docstring.
     """
-    doc = _get_doc(doc)
+    doc = get_docstring(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 extract_main_description(doc: Union[str, Callable]) -> List[str]:
+    """
+    Extract main description from a docstring:
+    paragraphs before the params/returns description.
+    """
+    paragraphs = []
+    for part in re.split(r"\s*\n(?:\s*\n)+", get_docstring(doc)):
+        if re.match(r"\s*:", part):
+            break
+        paragraphs.append(part.strip("\n"))
+    assert len(paragraphs) > 0
+    return paragraphs
+
+
 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.
@@ -112,3 +127,17 @@ def assert_same_return_docs(doc_a: Union[str, Callable], doc_b: Union[str, Calla
     Compare return value descriptions from two docstrings.
     """
     assert extract_return(doc_a) == extract_return(doc_b)
+
+
+def assert_same_main_description(doc_a: Union[str, Callable], doc_b: Union[str, Callable], ignore: Sequence[str] = ()):
+    """
+    Compare main description from two docstrings.
+    """
+    description_a = extract_main_description(doc_a)
+    description_b = extract_main_description(doc_b)
+
+    for s in ignore:
+        description_a = [p.replace(s, "<IGNORED>") for p in description_a]
+        description_b = [p.replace(s, "<IGNORED>") for p in description_b]
+
+    assert description_a == description_b
diff --git a/openeo/rest/connection.py b/openeo/rest/connection.py
@@ -1559,9 +1559,11 @@ def download(
         job_options: Optional[dict] = None,
     ) -> Union[None, bytes]:
         """
-        Downloads the result of a process graph synchronously,
-        and save the result to the given file or return bytes object if no outputfile is specified.
-        This method is useful to export binary content such as images. For json content, the execute method is recommended.
+        Send the underlying process graph to the backend
+        for synchronous processing and directly download the result.
+
+        If ``outputfile`` is provided, the result is downloaded to that path.
+        Otherwise a :py:class:`bytes` object is returned with the raw data.
 
         :param graph: (flat) dict representing a process graph, or process graph as raw JSON string,
             or as local file path or URL
@@ -1574,8 +1576,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.
+        :return: if ``outputfile`` was not specified:
+            a :py:class:`bytes` object containing the raw data.
+            Otherwise, ``None`` is returned.
 
         .. versionadded:: 0.36.0
             Added arguments ``additional`` and ``job_options``.
@@ -1663,7 +1666,14 @@ def create_job(
         log_level: Optional[str] = None,
     ) -> BatchJob:
         """
-        Create a new job from given process graph on the back-end.
+        Send the underlying process graph to the backend
+        to create an openEO batch job
+        and return a corresponding :py:class:`~openeo.rest.job.BatchJob` instance.
+
+        Note that this method only *creates* the openEO batch job at the backend,
+        but it does not *start* it.
+        Use :py:meth:`execute_batch` instead to let the openEO Python client
+        take care of the full job life cycle: create, start and track its progress until completion.
 
         :param process_graph: openEO-style (flat) process graph representation,
             or an object that can be converted to such a representation:
diff --git a/openeo/rest/datacube.py b/openeo/rest/datacube.py
@@ -2384,10 +2384,11 @@ def download(
         job_options: Optional[dict] = None,
     ) -> Union[None, bytes]:
         """
-        Execute synchronously and download the raster data cube, e.g. as GeoTIFF.
+        Send the underlying process graph to the backend
+        for synchronous processing and directly download the result.
 
-        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.
+        If ``outputfile`` is provided, the result is downloaded to that path.
+        Otherwise a :py:class:`bytes` object is returned with the raw data.
 
         :param outputfile: (optional) output path to download to.
         :param format: (optional) an output format supported by the backend.
@@ -2399,8 +2400,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.
+        :return: if ``outputfile`` was not specified:
+            a :py:class:`bytes` object containing the raw data.
+            Otherwise, ``None`` is returned.
 
         .. versionchanged:: 0.32.0
             Added ``auto_add_save_result`` option
diff --git a/openeo/rest/stac_resource.py b/openeo/rest/stac_resource.py
@@ -69,10 +69,11 @@ def download(
         job_options: Optional[dict] = None,
     ):
         """
-        Execute synchronously and download the result (cube).
+        Send the underlying process graph to the backend
+        for synchronous processing and directly download the result.
 
-        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.
+        If ``outputfile`` is provided, the result is downloaded to that path.
+        Otherwise a :py:class:`bytes` object is returned with the raw data.
 
         :param outputfile: (optional) output path to download to.
         :param validate: (optional) toggle to enable/prevent validation of the process graphs before execution
@@ -81,8 +82,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.
+        :return: if ``outputfile`` was not specified:
+            a :py:class:`bytes` object containing the raw data.
+            Otherwise, ``None`` is returned.
         """
         return self._connection.download(
             graph=self.flat_graph(),
diff --git a/openeo/rest/vectorcube.py b/openeo/rest/vectorcube.py
@@ -245,10 +245,11 @@ def download(
         job_options: Optional[dict] = None,
     ) -> Union[None, bytes]:
         """
-        Execute synchronously and download the vector cube.
+        Send the underlying process graph to the backend
+        for synchronous processing and directly download the result.
 
-        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.
+        If ``outputfile`` is provided, the result is downloaded to that path.
+        Otherwise a :py:class:`bytes` object is returned with the raw data.
 
         :param outputfile: (optional) output path to download to.
         :param format: (optional) an output format supported by the backend.
@@ -260,8 +261,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.
+        :return: if ``outputfile`` was not specified:
+            a :py:class:`bytes` object containing the raw data.
+            Otherwise, ``None`` is returned.
 
         .. versionchanged:: 0.21.0
             When not specified explicitly, output format is guessed from output file extension.
diff --git a/tests/internal/test_documentation.py b/tests/internal/test_documentation.py
@@ -4,48 +4,44 @@
 
 from openeo import BatchJob, Connection, DataCube, VectorCube
 from openeo.internal.documentation import (
+    assert_same_main_description,
     assert_same_param_docs,
     assert_same_return_docs,
+    extract_main_description,
     extract_params,
     extract_return,
 )
 from openeo.rest.mlmodel import MlModel
 from openeo.rest.stac_resource import StacResource
 
+DOCBLOCK1 = """
+    The description
 
-def test_extract_params():
-    doc = """
-        The description
+    and more
+
+    :param a: description of a
+    :param b_b : multi-line description
+        of b
 
-        and more
+    :return: the result
+        of the operation
 
-        :param a: description of a
-        :param b_b : multi-line description
-            of b
+    That's it!
+"""
 
-        That's it!
-    """
-    assert extract_params(doc) == {
+def test_extract_params():
+    assert extract_params(DOCBLOCK1) == {
         "a": "description of a",
         "b_b": "multi-line description\n    of b",
     }
 
 
 def test_extract_return():
-    doc = """
-        The description
-
-        and more
+    assert extract_return(DOCBLOCK1) == "the result\n    of the operation"
 
-        :param a: description of a
 
-        :return: the result
-            of the operation
-
-        That's it!
-    """
-
-    assert extract_return(doc) == "the result\n    of the operation"
+def test_extract_main_description():
+    assert extract_main_description(DOCBLOCK1) == ["The description", "and more"]
 
 
 @pytest.mark.parametrize(
@@ -84,3 +80,28 @@ def test_cube_processing_params_and_return(method_a, method_b):
 
     if signature_a.return_annotation == signature_b.return_annotation:
         assert_same_return_docs(method_a, method_b)
+
+
+@pytest.mark.parametrize(
+    ["method_a", "method_b"],
+    [
+        # Connection vs DataCube
+        (Connection.download, DataCube.download),
+        (Connection.create_job, DataCube.create_job),
+        # DataCube vs VectorCube
+        (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),
+        (DataCube.execute_batch, MlModel.execute_batch),
+        # DataCube vs StacResource
+        (DataCube.download, StacResource.download),
+        (DataCube.create_job, StacResource.create_job),
+        (DataCube.execute_batch, StacResource.execute_batch),
+    ],
+)
+def test_cube_processing_description(method_a, method_b):
+    """Check main description of cube download/execute related methods"""
+    assert_same_main_description(method_a, method_b)
