Issue #611/#610 Introduce OpenEoCapabilities and deprecate RESTCapabilities

- Introduce openeo.rest.capabilities.OpenEoCapabilities and add to API docs
- Deprecate openeo.rest.rest_capabilities.RESTCapabilities
- Remove base class openeo.capabilities.Capabilities

Author: soxofaan

CHANGELOG.md

@@ -13,9 +13,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Improved tracking of metadata changes with `resample_spatial` and `resample_cube_spatial` ([#690](https://github.com/Open-EO/openeo-python-client/issues/690))
 - Move `ComparableVersion` to `openeo.utils.version` (related to [#611](https://github.com/Open-EO/openeo-python-client/issues/611))
+- Deprecate `openeo.rest.rest_capabilities.RESTCapabilities` and introduce replacement `openeo.rest.capabilities.OpenEoCapabilities` ([#611](https://github.com/Open-EO/openeo-python-client/issues/611), [#610](https://github.com/Open-EO/openeo-python-client/issues/610))
 
 ### Removed
 
+- Remove unnecessary base class `openeo.capabilities.Capabilities` [#611](https://github.com/Open-EO/openeo-python-client/issues/611)
+
 ### Fixed
 
 

docs/api.rst

@@ -63,6 +63,13 @@ openeo.metadata
    :members: CollectionMetadata, BandDimension, SpatialDimension, TemporalDimension
 
 
+openeo.rest.capabilities
+------------------------
+
+.. automodule:: openeo.rest.capabilities
+   :members: OpenEoCapabilities
+
+
 openeo.api.process
 --------------------
 

openeo/capabilities.py

@@ -1,54 +1,12 @@
-from __future__ import annotations
-
-from abc import ABC
+import warnings
 
+from openeo.internal.warnings import UserDeprecationWarning
 from openeo.utils.version import ApiVersionException, ComparableVersion
 
-__all__ = ["Capabilities", "ComparableVersion", "ApiVersionException"]
-
-
-class Capabilities(ABC):
-    """Represents capabilities of a connection / back end."""
-
-    # TODO Is this base class (still) useful?
-
-    def __init__(self, data):
-        pass
-
-    def version(self):
-        """ Get openEO version. DEPRECATED: use api_version instead"""
-        # Field: version
-        # TODO: raise deprecation warning here?
-        return self.api_version()
-
-    def api_version(self) -> str:
-        """Get OpenEO API version."""
-        raise NotImplementedError
-
-    @property
-    def api_version_check(self) -> ComparableVersion:
-        """Helper to easily check if the API version is at least or below some threshold version."""
-        api_version = self.api_version()
-        if not api_version:
-            raise ApiVersionException("No API version found")
-        return ComparableVersion(api_version)
-
-    def list_features(self):
-        """ List all supported features / endpoints."""
-        # Field: endpoints
-        pass
-
-    def has_features(self, method_name):
-        """ Check whether a feature / endpoint is supported."""
-        # Field: endpoints > ...
-        pass
-
-    def currency(self):
-        """ Get default billing currency."""
-        # Field: billing > currency
-        pass
+warnings.warn(
+    message="Submodule `openeo.capabilities` is deprecated. Find `ComparableVersion` and related at `openeo.utils.version`.",
+    category=UserDeprecationWarning,
+    stacklevel=2,
+)
 
-    def list_plans(self):
-        """ List all billing plans."""
-        # Field: billing > plans
-        pass
+__all__ = ["ComparableVersion", "ApiVersionException"]

openeo/rest/capabilities.py

@@ -0,0 +1,55 @@
+from typing import List, Optional, Union
+
+from openeo.internal.jupyter import render_component
+from openeo.util import deep_get
+from openeo.utils.version import ApiVersionException, ComparableVersion
+
+__all__ = ["OpenEoCapabilities"]
+
+
+class OpenEoCapabilities:
+    """Container of the openEO capabilities document of an openEO backend."""
+
+    def __init__(self, data: dict, url: Optional[str] = None):
+        self.capabilities = data
+        self.url = url
+
+    def get(self, key: str, default=None):
+        return self.capabilities.get(key, default)
+
+    def deep_get(self, *keys, default=None):
+        return deep_get(self.capabilities, *keys, default=default)
+
+    def api_version(self) -> Union[str, None]:
+        """Version number of the openEO API specification this back-end implements."""
+        if "api_version" in self.capabilities:
+            return self.capabilities.get("api_version")
+        else:
+            # Legacy/deprecated
+            return self.capabilities.get("version")
+
+    @property
+    def api_version_check(self) -> ComparableVersion:
+        """Helper to easily check if the API version is at least or below some threshold version."""
+        api_version = self.api_version()
+        if not api_version:
+            raise ApiVersionException("No API version found")
+        return ComparableVersion(api_version)
+
+    def supports_endpoint(self, path: str, method="GET") -> bool:
+        """Check if backend supports given endpoint"""
+        return any(
+            endpoint.get("path") == path and method.upper() in endpoint.get("methods", [])
+            for endpoint in self.capabilities.get("endpoints", [])
+        )
+
+    def currency(self) -> Union[str, None]:
+        """Get default billing currency."""
+        return self.deep_get("billing", "currency", default=None)
+
+    def list_plans(self) -> List[dict]:
+        """List all billing plans."""
+        return self.deep_get("billing", "plans", default=[])
+
+    def _repr_html_(self):
+        return render_component("capabilities", data=self.capabilities, parameters={"url": self.url})

openeo/rest/connection.py

@@ -70,11 +70,11 @@
     OidcRefreshTokenAuthenticator,
     OidcResourceOwnerPasswordAuthenticator,
 )
+from openeo.rest.capabilities import OpenEoCapabilities
 from openeo.rest.datacube import DataCube, InputDate
 from openeo.rest.graph_building import CollectionProperty
 from openeo.rest.job import BatchJob, RESTJob
 from openeo.rest.mlmodel import MlModel
-from openeo.rest.rest_capabilities import RESTCapabilities
 from openeo.rest.service import Service
 from openeo.rest.udp import Parameter, RESTUserDefinedProcess
 from openeo.rest.userfile import UserFile
@@ -927,13 +927,13 @@ def list_collection_ids(self) -> List[str]:
         """
         return [collection['id'] for collection in self.list_collections() if 'id' in collection]
 
-    def capabilities(self) -> RESTCapabilities:
+    def capabilities(self) -> OpenEoCapabilities:
         """
-        Loads all available capabilities.
+        Fetch the openEO capabilities document.
         """
         return self._capabilities_cache.get(
             "capabilities",
-            load=lambda: RESTCapabilities(data=self.get('/', expected_status=200).json(), url=self._orig_url)
+            load=lambda: OpenEoCapabilities(data=self.get("/", expected_status=200).json(), url=self._orig_url),
         )
 
     def list_input_formats(self) -> dict:

openeo/rest/rest_capabilities.py

@@ -1,54 +1,15 @@
-from typing import List, Optional
+import warnings
 
-from openeo.capabilities import Capabilities
-from openeo.internal.jupyter import render_component
-from openeo.util import deep_get
+from openeo.internal.warnings import UserDeprecationWarning
+from openeo.rest.capabilities import OpenEoCapabilities
 
+warnings.warn(
+    message="`RESTCapabilities` from `openeo.rest.rest_capabilities` is deprecated. Instead use `OpenEoCapabilities` from `openeo.rest.capabilities`.",
+    category=UserDeprecationWarning,
+    stacklevel=2,
+)
 
-class RESTCapabilities(Capabilities):
-    """Represents REST capabilities of a connection / back end."""
+__all__ = ["RESTCapabilities"]
 
-    def __init__(self, data: dict, url: str = None):
-        super(RESTCapabilities, self).__init__(data)
-        self.capabilities = data
-        self.url = url
-
-    def get(self, key: str, default=None):
-        return self.capabilities.get(key, default)
-
-    def deep_get(self, *keys, default=None):
-        return deep_get(self.capabilities, *keys, default=default)
-
-    def api_version(self) -> str:
-        """ Get openEO version."""
-        if 'api_version' in self.capabilities:
-            return self.capabilities.get('api_version')
-        else:
-            # Legacy/deprecated
-            return self.capabilities.get('version')
-
-    def list_features(self):
-        """ List all supported features / endpoints."""
-        return self.capabilities.get('endpoints')
-
-    def has_features(self, method_name):
-        """ Check whether a feature / endpoint is supported."""
-        # Field: endpoints > ... TODO
-        pass
-
-    def supports_endpoint(self, path: str, method="GET"):
-        return any(
-            endpoint.get("path") == path and method.upper() in endpoint.get("methods", [])
-            for endpoint in self.capabilities.get("endpoints", [])
-        )
-
-    def currency(self) -> Optional[str]:
-        """Get default billing currency."""
-        return self.deep_get("billing", "currency", default=None)
-
-    def list_plans(self) -> List[dict]:
-        """List all billing plans."""
-        return self.deep_get("billing", "plans", default=[])
-
-    def _repr_html_(self):
-        return render_component("capabilities", data = self.capabilities, parameters = {"url": self.url})
+# Legacy alias
+RESTCapabilities = OpenEoCapabilities

tests/rest/test_capabilities.py

@@ -1,16 +1,51 @@
-from openeo.rest.rest_capabilities import RESTCapabilities
+from openeo.rest.capabilities import OpenEoCapabilities
+from openeo.utils.version import ComparableVersion
 
 
-class TestCapabilities:
+class TestOpenEoCapabilities:
+
+    def test_api_version(self):
+        capabilities = OpenEoCapabilities(
+            {
+                "api_version": "1.2.3",
+            }
+        )
+        assert capabilities.api_version() == "1.2.3"
+
+    def test_api_version_check(self):
+        capabilities = OpenEoCapabilities(
+            {
+                "api_version": "1.2.3",
+            }
+        )
+        checker = capabilities.api_version_check
+        assert isinstance(checker, ComparableVersion)
+        assert checker == "1.2.3"
+        assert checker > "1.2"
+        assert checker < "1.5"
+
+    def test_supports_endpoint(self):
+        capabilities = OpenEoCapabilities(
+            {
+                "api_version": "1.2.3",
+                "endpoints": [
+                    {"path": "/collections", "methods": ["GET"]},
+                    {"path": "/jobs", "methods": ["GET", "POST"]},
+                ],
+            }
+        )
+        assert capabilities.supports_endpoint(path="/collections", method="GET")
+        assert not capabilities.supports_endpoint(path="/collections", method="POST")
+        assert capabilities.supports_endpoint(path="/jobs", method="GET")
+        assert capabilities.supports_endpoint(path="/jobs", method="POST")
+
     def test_currency(self):
-        assert RESTCapabilities({}).currency() is None
-        assert RESTCapabilities({"billing": None}).currency() is None
-        assert RESTCapabilities({"billing": {"currency": "EUR"}}).currency() == "EUR"
+        assert OpenEoCapabilities({}).currency() is None
+        assert OpenEoCapabilities({"billing": None}).currency() is None
+        assert OpenEoCapabilities({"billing": {"currency": "EUR"}}).currency() == "EUR"
 
     def test_list_plans(self):
-        assert RESTCapabilities({}).list_plans() == []
-        assert RESTCapabilities({"billing": None}).list_plans() == []
-        assert RESTCapabilities({"billing": {"plans": []}}).list_plans() == []
-        assert RESTCapabilities(
-            {"billing": {"plans": [{"name": "free"}]}}
-        ).list_plans() == [{"name": "free"}]
+        assert OpenEoCapabilities({}).list_plans() == []
+        assert OpenEoCapabilities({"billing": None}).list_plans() == []
+        assert OpenEoCapabilities({"billing": {"plans": []}}).list_plans() == []
+        assert OpenEoCapabilities({"billing": {"plans": [{"name": "free"}]}}).list_plans() == [{"name": "free"}]

tests/rest/test_connection.py

@@ -525,7 +525,6 @@ def test_capabilities_api_version(requests_mock):
     requests_mock.get(API_URL, status_code=200, json={"api_version": "1.0.0"})
     con = openeo.connect("https://oeo.test")
     capabilities = con.capabilities()
-    assert capabilities.version() == "1.0.0"
     assert capabilities.api_version() == "1.0.0"