add xarray DatasetMetadataExtension (#1118)

* add xarray DatasetMetadataExtension

* add /dataset prefix and refactor

* add tests and deprecate VariablesExtension

* revert and follow xpublish

Author: vincentsarago

CHANGES.md

@@ -91,6 +91,8 @@
 ### titiler.xarray
 
 * change `get_variable.drop_dim` parameter type from `str` to `List[str]` **breaking change**
+* deprecate `VariablesExtension` extension
+* add `DatasetMetadataExtension` extension (`/dataset/keys`, `/dataset/` and `/dataset/dict` endpoints)
 
 ## 0.21.1 (2025-01-29)
 

src/titiler/core/tests/test_utils.py

@@ -1,7 +1,14 @@
 """Test utils."""
 
+import pytest
+
 from titiler.core.dependencies import BidxParams
-from titiler.core.utils import deserialize_query_params, get_dependency_query_params
+from titiler.core.resources.enums import MediaType
+from titiler.core.utils import (
+    accept_media_type,
+    deserialize_query_params,
+    get_dependency_query_params,
+)
 
 
 def test_get_dependency_params():
@@ -65,3 +72,47 @@ def test_deserialize_query_params():
     )
     assert res == BidxParams(indexes=[1])
     assert not err
+
+
+@pytest.mark.parametrize(
+    "media,accept,expected",
+    [
+        ([MediaType.html], "text/html, application/json;q=0.8", MediaType.html),
+        (
+            [MediaType.html, MediaType.json],
+            "application/json, text/html;q=0.8",
+            MediaType.json,
+        ),
+        ([MediaType.xml], "application/json, text/html;q=0.8", None),
+        ([MediaType.json], "", None),
+        (
+            [MediaType.json, MediaType.html],
+            "application/json;q=1.0, text/html;q=0.8",
+            MediaType.json,
+        ),
+        (
+            [MediaType.json, MediaType.html],
+            "application/json;q=1.0, text/html;q=1.0",
+            MediaType.json,
+        ),
+        (
+            [MediaType.html, MediaType.json],
+            "application/json;q=1.0, text/html;q=1.0",
+            MediaType.html,
+        ),
+        ([MediaType.html, MediaType.json], "*;q=1.0", MediaType.html),
+        (
+            [MediaType.json, MediaType.html],
+            "application/json;q=aaa, text/html",
+            MediaType.html,
+        ),
+        (
+            [MediaType.json, MediaType.html],
+            "application/json;q=0.0, text/html",
+            MediaType.html,
+        ),
+    ],
+)
+def test_accept_media_type(media, accept, expected):
+    """test MetadataOutputType dependency."""
+    assert accept_media_type(accept, media) == expected

src/titiler/core/titiler/core/utils.py

@@ -15,7 +15,7 @@
 from rio_tiler.types import BBox, ColorMapType, IntervalTuple
 from rio_tiler.utils import linear_rescale, render
 
-from titiler.core.resources.enums import ImageType
+from titiler.core.resources.enums import ImageType, MediaType
 
 
 def rescale_array(
@@ -183,3 +183,50 @@ def extract_query_params(dependencies, params) -> Tuple[ValidParams, Errors]:
             values.update(dep_values)
         errors += dep_errors
     return values, errors
+
+
+def accept_media_type(accept: str, mediatypes: List[MediaType]) -> Optional[MediaType]:
+    """Return MediaType based on accept header and available mediatype.
+
+    Links:
+    - https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
+    - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept
+
+    """
+    accept_values = {}
+    for m in accept.replace(" ", "").split(","):
+        values = m.split(";")
+        if len(values) == 1:
+            name = values[0]
+            quality = 1.0
+        else:
+            name = values[0]
+            groups = dict([param.split("=") for param in values[1:]])  # type: ignore
+            try:
+                q = groups.get("q")
+                quality = float(q) if q else 1.0
+            except ValueError:
+                quality = 0
+
+        # if quality is 0 we ignore encoding
+        if quality:
+            accept_values[name] = quality
+
+    # Create Preference matrix
+    media_preference = {
+        v: [n for (n, q) in accept_values.items() if q == v]
+        for v in sorted(set(accept_values.values()), reverse=True)
+    }
+
+    # Loop through available compression and encoding preference
+    for _, pref in media_preference.items():
+        for media in mediatypes:
+            if media.value in pref:
+                return media
+
+    # If no specified encoding is supported but "*" is accepted,
+    # take one of the available compressions.
+    if "*" in accept_values and mediatypes:
+        return mediatypes[0]
+
+    return None

src/titiler/xarray/examples/main.py

@@ -0,0 +1,86 @@
+# /// script
+# dependencies = [
+#   "titiler.xarray[full]",
+#   "starlette_cramjam",
+#   "uvicorn",
+# ]
+# ///
+"""Example of Application."""
+
+from fastapi import FastAPI
+from starlette.middleware.cors import CORSMiddleware
+from starlette_cramjam.middleware import CompressionMiddleware
+
+from titiler.core.errors import DEFAULT_STATUS_CODES, add_exception_handlers
+from titiler.core.factory import AlgorithmFactory, ColorMapFactory, TMSFactory
+from titiler.core.middleware import CacheControlMiddleware
+from titiler.xarray.extensions import DatasetMetadataExtension
+from titiler.xarray.factory import TilerFactory
+
+app = FastAPI(
+    title="TiTiler with support of Multidimensional dataset",
+    openapi_url="/api",
+    docs_url="/api.html",
+    version="0.1.0",
+)
+
+
+md = TilerFactory(
+    router_prefix="/md",
+    extensions=[
+        DatasetMetadataExtension(),
+    ],
+)
+app.include_router(md.router, prefix="/md", tags=["Multi Dimensional"])
+
+# TileMatrixSets endpoints
+app.include_router(TMSFactory().router, tags=["Tiling Schemes"])
+
+###############################################################################
+# Algorithms endpoints
+app.include_router(
+    AlgorithmFactory().router,
+    tags=["Algorithms"],
+)
+
+# Colormaps endpoints
+app.include_router(
+    ColorMapFactory().router,
+    tags=["ColorMaps"],
+)
+
+add_exception_handlers(app, DEFAULT_STATUS_CODES)
+
+# Set all CORS enabled origins
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins="*",
+    allow_credentials=True,
+    allow_methods=["GET"],
+    allow_headers=["*"],
+)
+
+app.add_middleware(
+    CompressionMiddleware,
+    minimum_size=0,
+    exclude_mediatype={
+        "image/jpeg",
+        "image/jpg",
+        "image/png",
+        "image/jp2",
+        "image/webp",
+    },
+    compression_level=6,
+)
+
+app.add_middleware(
+    CacheControlMiddleware,
+    cachecontrol="public, max-age=3600",
+    exclude_path={r"/healthz"},
+)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app=app, host="127.0.0.1", port=8080, log_level="info")

src/titiler/xarray/tests/test_dependencies.py

@@ -1,8 +1,9 @@
 """test dependencies."""
 
+from typing import Annotated
+
 from fastapi import Depends, FastAPI, Path
 from starlette.testclient import TestClient
-from typing_extensions import Annotated
 
 from titiler.xarray import dependencies
 

src/titiler/xarray/tests/test_factory.py

@@ -7,7 +7,7 @@
 from rasterio.io import MemoryFile
 from starlette.testclient import TestClient
 
-from titiler.xarray.extensions import VariablesExtension
+from titiler.xarray.extensions import DatasetMetadataExtension, VariablesExtension
 from titiler.xarray.factory import TilerFactory
 
 prefix = os.path.join(os.path.dirname(__file__), "fixtures")
@@ -19,16 +19,26 @@
 zarr_pyramid = os.path.join(prefix, "pyramid.zarr")
 
 
+def test_deprecated_extension():
+    """Test factory with options."""
+    """Test TilerFactory class."""
+    with pytest.warns(DeprecationWarning):
+        md = TilerFactory(extensions=[VariablesExtension()])
+    assert len(md.router.routes) == 20
+
+
 def test_tiler_factory():
     """Test factory with options."""
     """Test TilerFactory class."""
     md = TilerFactory(
-        add_viewer=False, add_part=False, extensions=[VariablesExtension()]
+        add_viewer=False,
+        add_part=False,
+        extensions=[DatasetMetadataExtension()],
     )
-    assert len(md.router.routes) == 14
+    assert len(md.router.routes) == 16
 
-    md = TilerFactory(router_prefix="/md", extensions=[VariablesExtension()])
-    assert len(md.router.routes) == 20
+    md = TilerFactory(router_prefix="/md", extensions=[DatasetMetadataExtension()])
+    assert len(md.router.routes) == 22
 
     app = FastAPI()
     app.include_router(md.router, prefix="/md")
@@ -44,8 +54,8 @@ def test_tiler_factory():
 @pytest.fixture
 def app():
     """App fixture."""
-    md = TilerFactory(router_prefix="/md", extensions=[VariablesExtension()])
-    assert len(md.router.routes) == 20
+    md = TilerFactory(router_prefix="/md", extensions=[DatasetMetadataExtension()])
+    assert len(md.router.routes) == 22
 
     app = FastAPI()
     app.include_router(md.router, prefix="/md")
@@ -57,13 +67,22 @@ def app():
     "filename",
     [dataset_2d_nc, dataset_3d_nc, dataset_3d_zarr],
 )
-def test_variable(filename, app):
-    """Test /variables endpoint."""
-    resp = app.get("/md/variables", params={"url": filename})
+def test_dataset_extension(filename, app):
+    """Test /dataset endpoints."""
+    resp = app.get("/md/dataset/keys", params={"url": filename})
     assert resp.status_code == 200
     assert resp.headers["content-type"] == "application/json"
     assert resp.json() == ["dataset"]
 
+    resp = app.get("/md/dataset/dict", params={"url": filename})
+    assert resp.status_code == 200
+    assert resp.headers["content-type"] == "application/json"
+    assert resp.json()["data_vars"]["dataset"]
+
+    resp = app.get("/md/dataset/", params={"url": filename})
+    assert resp.status_code == 200
+    assert "text/html" in resp.headers["content-type"]
+
 
 @pytest.mark.parametrize(
     "filename",