Issue #668 add changelog and docs on federation extension

Author: soxofaan

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add initial support for accessing [Federation Extension](https://github.com/Open-EO/openeo-api/tree/master/extensions/federation) related metadata ([#668](https://github.com/Open-EO/openeo-python-client/issues/668))
+
 ### Changed
 
 - Improved tracking of metadata changes with `resample_spatial` and `resample_cube_spatial` ([#690](https://github.com/Open-EO/openeo-python-client/issues/690))

docs/federation-extension.rst

@@ -0,0 +1,68 @@
+
+.. _federation-extension:
+
+===========================
+openEO Federation Extension
+===========================
+
+
+The `openEO Federation extension <https://github.com/Open-EO/openeo-api/tree/master/extensions/federation>`_
+is a set of additional specifications,
+on top of the standard openEO API specification,
+to address the need for extra metadata in the context
+of federated openEO processing,
+where multiple (separately operated) openEO services are bundled together
+behind a single API endpoint.
+
+
+Accessing federation extension metadata
+========================================
+
+The openEO Python client library provides access to this additional metadata
+in a couple of resources.
+
+.. versionadded:: 0.38.0
+    initial support to access federation extension related metadata.
+
+Backend details
+---------------
+
+Participating backends in a federation are listed under the ``federation`` field
+of the capabilities document (``GET /``) and can be inspected
+using :py:meth:`OpenEoCapabilities.get_federation() <openeo.rest.capabilities.OpenEoCapabilities.get_federation>`:
+
+.. code-block:: python
+
+    import openeo
+    connection = openeo.connect(url=...)
+    capabilities = connection.capabilities()
+    print("Federated backends:", capabilities.get_federation())
+
+
+Unavailable backends (``federation:missing``)
+----------------------------------------------
+
+When listing resources like
+collections (with :py:meth:`Connection.list_collections() <openeo.rest.connection.Connection.list_collections>`),
+processes (with :py:meth:`Connection.list_processes() <openeo.rest.connection.Connection.list_processes>`),
+jobs (with :py:meth:`Connection.list_jobs() <openeo.rest.connection.Connection.list_jobs>`),
+etc.,
+there might be items missing due to federation participants being temporarily unavailable.
+These missing federation components are listed in the response under the ``federation:missing`` field
+and can be inspected as follows:
+
+.. code-block:: python
+
+    import openeo
+    connection = openeo.connect(url=...)
+    collections = connection.list_collections()
+    print("Number of collections:", len(collections))
+    print("Missing federation components:", collections.ext_federation.missing)
+
+
+Note that the ``collections`` object in this example, returned by
+:py:meth:`Connection.list_collections() <openeo.rest.connection.Connection.list_collections>`,
+acts at the surface as a simple list of dictionaries with collection metadata,
+but also provides additional properties/methods like
+:py:attr:`ext_federation <openeo.rest.models.general.CollectionListingResponse.ext_federation>`.
+This is an accessor (an instance of :py:class:`FederationExtension <openeo.rest.models.federation_extension.FederationExtension>`)

docs/index.rst

@@ -64,6 +64,7 @@ Table of contents
    process_mapping
    development
    best_practices
+   Federation extension <federation-extension>
    changelog
 
 

openeo/rest/capabilities.py

@@ -60,6 +60,10 @@ def get_federation(self) -> Union[Dict[str, dict], None]:
         if this backend acts as a federated backend,
         as specified in the openEO Federation Extension.
         Returns ``None`` otherwise
+
+        .. versionadded:: 0.38.0
         """
         # TODO: also check related conformance class in `/conformance`?
+        # TODO: refactor into FederationExtension
+        # TODO: return a richer object instead of raw dicts?
         return self.get("federation")

openeo/rest/models/federation_extension.py

@@ -6,7 +6,9 @@
 class FederationExtension:
     """
     Wrapper the openEO Federation extension as defined by
-    https://github.com/Open-EO/openeo-api/tree/draft/extensions/federation
+    https://github.com/Open-EO/openeo-api/tree/master/extensions/federation
+
+    .. seealso:: :ref:`federation-extension`
     """
 
     __slots__ = ["_data"]