Warn when not explicitly specifying dimension in apply_dimension #774

Author: soxofaan

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- `DataCube.apply_dimension()`: not explicitly specifying the `dimension` argument is deprecated and will trigger warnings ([#774](https://github.com/Open-EO/openeo-python-client/issues/774))
+
 ### Removed
 
 ### Fixed

openeo/rest/datacube.py

@@ -1370,8 +1370,8 @@ def apply_dimension(
         # TODO: drop None default of process (when `code` and `runtime` args can be dropped)
         process: Union[str, typing.Callable, UDF, PGNode] = None,
         version: Optional[str] = None,
-        # TODO: dimension has no default (per spec)?
-        dimension: str = "t",
+        # TODO #774 fully drop default value for dimension after deprecation period
+        dimension: str = _UNSET,
         target_dimension: Optional[str] = None,
         context: Optional[dict] = None,
     ) -> DataCube:
@@ -1426,6 +1426,9 @@ def apply_dimension(
             of using an :py:class:`UDF <openeo.rest._datacube.UDF>` object in the ``process`` argument.
             See :ref:`old_udf_api` for more background about the changes.
 
+        .. versionchanged:: 0.42.0
+            Not explicitly specifying the ``dimension`` argument is deprecated and will trigger warnings.
+            The original fallback value "t" is still in place, but that will be removed in a future version.
         """
         # TODO #137 #181 #312 remove support for code/runtime/version
         if runtime or (isinstance(code, str) and "\n" in code) or version:
@@ -1446,6 +1449,17 @@ def apply_dimension(
         process = build_child_callback(
             process=process, parent_parameters=["data", "context"], connection=self.connection
         )
+
+        if dimension is _UNSET:
+            # TODO #774 fully drop this dimension fallback value after deprecation period
+            warnings.warn(
+                "Using `DataCube.apply_dimension()` without explicit `dimension` argument is deprecated and will become invalid in a future version. "
+                "Falling back on dimension 't'.",
+                category=UserDeprecationWarning,
+                stacklevel=2,
+            )
+            dimension = "t"
+
         arguments = {
             "data": THIS,
             "process": process,

tests/rest/datacube/test_datacube.py

@@ -992,6 +992,29 @@ def test_apply_dimension(connection, requests_mock):
         s22.apply_dimension(dimension='wut', code="subtract_mean")
 
 
+def test_apply_dimension_unspecified_dimension(s2cube, dummy_backend, recwarn):
+    s2cube.apply_dimension("cumsum").create_job()
+    assert dummy_backend.get_pg(process_id="apply_dimension") == {
+        "process_id": "apply_dimension",
+        "arguments": {
+            "data": {"from_node": "loadcollection1"},
+            "dimension": "t",
+            "process": {
+                "process_graph": {
+                    "cumsum1": {
+                        "arguments": {"data": {"from_parameter": "data"}},
+                        "process_id": "cumsum",
+                        "result": True,
+                    }
+                }
+            },
+        },
+    }
+    assert str(recwarn.pop()) == dirty_equals.IsStr(
+        regex=".*UserDeprecationWarning.*apply_dimension.*without explicit.*dimension.*argument.*is deprecated.*filename.*/test_datacube.py.*"
+    )
+
+
 def test_download_path_str(connection, requests_mock, tmp_path):
     requests_mock.get(API_URL + "/collections/S2", json={})
     requests_mock.post(API_URL + '/result', content=b"tiffdata")