Merge remote-tracking branch 'origin/master' into 747-robustranged-download-support

Author: dsamaey

CHANGELOG.md

@@ -9,14 +9,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+### Changed
+
+### Removed
+
+### Fixed
+
+
+## [0.40.0] - 2025-04-14
+
+### Added
+
 - `sar_backscatter`: try to retrieve coefficient options from backend ([#693](https://github.com/Open-EO/openeo-python-client/issues/693))
 - Improve error message when OIDC provider is unavailable ([#751](https://github.com/Open-EO/openeo-python-client/issues/751))
 - Added `on_response_headers` argument to `DataCube.download()` and related to handle (e.g. `print`) the response headers ([#560](https://github.com/Open-EO/openeo-python-client/issues/560))
 - Added more robust download for large job result files (if supported by the server)
 
 ### Changed
 
-### Removed
+- When the bands provided to `Connection.load_stac(..., bands=[...])` do not fully match the bands the client extracted from the STAC metadata, a warning will be triggered, but the provided band names will still be used during the client-side preparation of the process graph. This is a pragmatic approach to bridge the gap between differing interpretations of band detection in STAC. Note that this might produce process graphs that are technically invalid and might not work on other backends or future versions of the backend you currently use. It is recommended to consult with the provider of the STAC metadata and openEO backend on the correct and future-proof band names. ([#752](https://github.com/Open-EO/openeo-python-client/issues/752))
 
 ### Fixed
 

docs/development.rst

@@ -246,7 +246,7 @@ we will use a concrete version ``0.8.0`` in the examples below.
 #.  Create release commit:
 
     A.  **Drop the pre-release suffix** from the version string in ``openeo/_version.py``
-        so that it just a "final" semantic versioning string, e.g. ``0.8.0``
+        so that it is just a "final" semantic versioning string, e.g. ``0.8.0``
 
     B.  **Update CHANGELOG.md**: rename the "Unreleased" section title
         to contain version and date, e.g.::

openeo/_version.py

@@ -1 +1 @@
-__version__ = "0.40.0a1"
+__version__ = "0.41.0a1"

openeo/metadata.py

@@ -218,6 +218,16 @@ def rename_labels(self, target, source) -> Dimension:
     def rename(self, name) -> Dimension:
         return BandDimension(name=name, bands=self.bands)
 
+    def contains_band(self, band: Union[int, str]) -> bool:
+        """
+        Check if the given band name or index is present in the dimension.
+        """
+        try:
+            self.band_index(band)
+            return True
+        except ValueError:
+            return False
+
 
 class GeometryDimension(Dimension):
     # TODO: how to model/store labels of geometry dimension?
@@ -365,22 +375,20 @@ def rename_labels(self, dimension: str, target: list, source: list = None) -> Cu
         :return: Updated metadata
         """
         self.assert_valid_dimension(dimension)
-        loc = self.dimension_names().index(dimension)
-        new_dimensions = self._dimensions.copy()
-        new_dimensions[loc] = new_dimensions[loc].rename_labels(target, source)
-
-        return self._clone_and_update(dimensions=new_dimensions)
+        return self._clone_and_update(
+            dimensions=[
+                d.rename_labels(target=target, source=source) if d.name == dimension else d for d in self._dimensions
+            ]
+        )
 
     def rename_dimension(self, source: str, target: str) -> CubeMetadata:
         """
         Rename source dimension into target, preserving other properties
         """
         self.assert_valid_dimension(source)
-        loc = self.dimension_names().index(source)
-        new_dimensions = self._dimensions.copy()
-        new_dimensions[loc] = new_dimensions[loc].rename(target)
-
-        return self._clone_and_update(dimensions=new_dimensions)
+        return self._clone_and_update(
+            dimensions=[d.rename(name=target) if d.name == source else d for d in self._dimensions]
+        )
 
     def reduce_dimension(self, dimension_name: str) -> CubeMetadata:
         """Create new CubeMetadata object by collapsing/reducing a dimension."""
@@ -413,6 +421,31 @@ def add_dimension(self, name: str, label: Union[str, float], type: Optional[str]
             dim = Dimension(type=type or "other", name=name)
         return self._clone_and_update(dimensions=self._dimensions + [dim])
 
+    def _ensure_band_dimension(
+        self, *, name: Optional[str] = None, bands: List[Union[Band, str]], warning: str
+    ) -> CubeMetadata:
+        """
+        Create new CubeMetadata object, ensuring a band dimension with given bands.
+        This will override any existing band dimension, and is intended for
+        special cases where pragmatism necessitates to ignore the original metadata.
+        For example, to overrule badly/incomplete detected band names from STAC metadata.
+
+        .. note::
+            It is required to specify a warning message as this method is only intended
+            to be used as temporary stop-gap solution for use cases that are possibly not future-proof.
+            Enforcing a warning should make that clear and avoid that users unknowingly depend on
+            metadata handling behavior that is not guaranteed to be stable.
+        """
+        _log.warning(warning or "ensure_band_dimension: overriding band dimension metadata with user-defined bands.")
+        if name is None:
+            # Preserve original band dimension name if possible
+            name = self.band_dimension.name if self.has_band_dimension() else "bands"
+        bands = [b if isinstance(b, Band) else Band(name=b) for b in bands]
+        band_dimension = BandDimension(name=name, bands=bands)
+        return self._clone_and_update(
+            dimensions=[d for d in self._dimensions if not isinstance(d, BandDimension)] + [band_dimension]
+        )
+
     def drop_dimension(self, name: str = None) -> CubeMetadata:
         """Create new CubeMetadata object without dropped dimension with given name"""
         dimension_names = self.dimension_names()
@@ -656,13 +689,13 @@ def is_band_asset(asset: pystac.Asset) -> bool:
         raise ValueError(stac_object)
 
     # At least assume there are spatial dimensions
-    # TODO: are there conditions in which we even should not assume the presence of spatial dimensions?
+    # TODO #743: are there conditions in which we even should not assume the presence of spatial dimensions?
     dimensions = [
         SpatialDimension(name="x", extent=[None, None]),
         SpatialDimension(name="y", extent=[None, None]),
     ]
 
-    # TODO: conditionally include band dimension when there was actual indication of band metadata?
+    # TODO #743: conditionally include band dimension when there was actual indication of band metadata?
     band_dimension = BandDimension(name="bands", bands=bands)
     dimensions.append(band_dimension)
 

openeo/rest/datacube.py

@@ -441,10 +441,27 @@ def load_stac(
         graph = PGNode("load_stac", arguments=arguments)
         try:
             metadata = metadata_from_stac(url)
+            # TODO: also apply spatial/temporal filters to metadata?
+
             if isinstance(bands, list):
-                # TODO: also apply spatial/temporal filters to metadata?
-                metadata = metadata.filter_bands(band_names=bands)
-        except Exception:
+                if metadata.has_band_dimension():
+                    unknown_bands = [b for b in bands if not metadata.band_dimension.contains_band(b)]
+                    if len(unknown_bands) == 0:
+                        # Ideal case: bands requested by user correspond with bands extracted from metadata.
+                        metadata = metadata.filter_bands(band_names=bands)
+                    else:
+                        metadata = metadata._ensure_band_dimension(
+                            bands=bands,
+                            warning=f"The specified bands {bands} in `load_stac` are not a subset of the bands {metadata.band_dimension.band_names} found in the STAC metadata (unknown bands: {unknown_bands}). Working with specified bands as is.",
+                        )
+                else:
+                    metadata = metadata._ensure_band_dimension(
+                        name="bands",
+                        bands=bands,
+                        warning=f"Bands {bands} were specified in `load_stac`, but no band dimension was detected in the STAC metadata. Working with band dimension and specified bands.",
+                    )
+
+        except Exception as e:
             log.warning(f"Failed to extract cube metadata from STAC URL {url}", exc_info=True)
             metadata = None
         return cls(graph=graph, connection=connection, metadata=metadata)