freva-client 2411.0.0__tar.gz → 2505.0.0__tar.gz

{freva_client-2411.0.0 → freva_client-2505.0.0}/PKG-INFO

@@ -1,11 +1,11 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: freva-client
-Version: 2411.0.0
+Version: 2505.0.0
 Summary: Search for climate data based on key-value pairs
 Author-email: "DKRZ, Clint" <freva@dkrz.de>
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: appdirs
 Requires-Dist: pyyaml
 Requires-Dist: authlib

{freva_client-2411.0.0 → freva_client-2505.0.0}/pyproject.toml

@@ -8,7 +8,7 @@ description = "Search for climate data based on key-value pairs"
 authors = [{name = "DKRZ, Clint", email = "freva@dkrz.de"}]
 readme = "README.md"
 classifiers = [
-               "Development Status :: 3 - Alpha",
+               "Development Status :: 4 - Beta",
                "Environment :: Console",
                "Intended Audience :: Developers",
                "Intended Audience :: Science/Research",
@@ -19,6 +19,7 @@ classifiers = [
                "Programming Language :: Python :: 3.10",
                "Programming Language :: Python :: 3.11",
                "Programming Language :: Python :: 3.12",
+               "Programming Language :: Python :: 3.13",
 ]
 requires-python = ">=3.8"
 dependencies = [
@@ -48,4 +49,4 @@ include = ["assets/*"]
 [tool.flit.external-data]
 directory = "assets"
 [package-data]
-freva_deployment = ["py.typed"]
+freva_client = ["py.typed"]

{freva_client-2411.0.0 → freva_client-2505.0.0}/src/freva_client/__init__.py

@@ -17,5 +17,5 @@ need to apply data analysis plugins, please visit the
 from .auth import authenticate
 from .query import databrowser
 
-__version__ = "2411.0.0"
+__version__ = "2505.0.0"
 __all__ = ["authenticate", "databrowser", "__version__"]

{freva_client-2411.0.0 → freva_client-2505.0.0}/src/freva_client/cli/auth_cli.py

@@ -5,6 +5,7 @@ from getpass import getuser
 from typing import Optional
 
 import typer
+
 from freva_client import authenticate
 from freva_client.utils import exception_handler, logger
 

{freva_client-2411.0.0 → freva_client-2505.0.0}/src/freva_client/cli/cli_app.py

@@ -4,6 +4,7 @@ import os
 from typing import Optional
 
 import typer
+
 from freva_client.utils import logger
 
 from .auth_cli import authenticate_cli

{freva_client-2411.0.0 → freva_client-2505.0.0}/src/freva_client/cli/cli_parser.py

@@ -69,6 +69,8 @@ class Completer:
             time=None,
             host=None,
             time_select="flexible",
+            bbox=None,
+            bbox_select="flexible",
             multiversion=False,
             extended_search=True,
             fail_on_error=False,

{freva_client-2411.0.0 → freva_client-2505.0.0}/src/freva_client/cli/cli_utils.py

@@ -3,9 +3,10 @@
 from typing import Dict, List
 
 import typer
+from rich import print as pprint
+
 from freva_client import __version__
 from freva_client.utils import logger
-from rich import print as pprint
 
 APP_NAME: str = "freva-client"
 

{freva_client-2411.0.0 → freva_client-2505.0.0}/src/freva_client/cli/databrowser_cli.py

@@ -7,10 +7,11 @@ import json
 from enum import Enum
 from pathlib import Path
 from tempfile import NamedTemporaryFile
-from typing import Dict, List, Literal, Optional, Union, cast
+from typing import Dict, List, Literal, Optional, Tuple, Union, cast
 
 import typer
 import xarray as xr
+
 from freva_client import databrowser
 from freva_client.auth import Auth
 from freva_client.utils import exception_handler, logger
@@ -31,41 +32,67 @@ def _auth(url: str, token: Optional[str]) -> None:
 class UniqKeys(str, Enum):
     """Literal implementation for the cli."""
 
-    file: str = "file"
-    uri: str = "uri"
+    file = "file"
+    uri = "uri"
 
 
 class Flavours(str, Enum):
     """Literal implementation for the cli."""
 
-    freva: str = "freva"
-    cmip6: str = "cmip6"
-    cmip5: str = "cmip5"
-    cordex: str = "cordex"
-    nextgems: str = "nextgems"
-    user: str = "user"
+    freva = "freva"
+    cmip6 = "cmip6"
+    cmip5 = "cmip5"
+    cordex = "cordex"
+    nextgems = "nextgems"
+    user = "user"
 
 
-class TimeSelect(str, Enum):
+class SelectMethod(str, Enum):
     """Literal implementation for the cli."""
 
-    strict: str = "strict"
-    flexible: str = "flexible"
-    file: str = "file"
+    strict = "strict"
+    flexible = "flexible"
+    file = "file"
 
     @staticmethod
-    def get_help() -> str:
-        """Generate the help string."""
+    def get_help(context: str) -> str:
+        """Generate the help string for time or bbox selection methods.
+
+        Parameters
+        ----------
+        context: str, default: "time"
+            Either "time" or "bbox" to generate appropriate help text.
+        """
+        examples = {
+            "time": ("2000 to 2012", "2010 to 2020"),
+            "bbox": ("-10 10 -10 10", "0 5 0 5")
+        }
+        descriptions = {
+            "time": {
+                "unit": "time period",
+                "start_end": "start or end period",
+                "subset": "time period"
+            },
+            "bbox": {
+                "unit": "spatial extent",
+                "start_end": "any part of the extent",
+                "subset": "spatial extent"
+            }
+        }
+
+        context_info = descriptions.get(context, descriptions["time"])
+        example = examples.get(context, examples["time"])
+
         return (
-            "Operator that specifies how the time period is selected. "
+            f"Operator that specifies how the {context_info['unit']} is selected. "
             "Choose from flexible (default), strict or file. "
             "``strict`` returns only those files that have the *entire* "
-            "time period covered. The time search ``2000 to 2012`` will "
-            "not select files containing data from 2010 to 2020 with "
-            "the ``strict`` method. ``flexible`` will select those files "
-            "as  ``flexible`` returns those files that have either start "
-            "or end period covered. ``file`` will only return files where "
-            "the entire time period is contained within *one single* file."
+            f"{context_info['unit']} covered. The {context} search ``{example[0]}`` "
+            f"will not select files containing data from {example[1]} with "
+            "the ``strict`` method. ``flexible`` will select those files as "
+            f"``flexible`` returns those files that have {context_info['start_end']} "
+            f"covered. ``file`` will only return files where the entire "
+            f"{context_info['subset']} is contained within *one single* file."
         )
 
 
@@ -123,11 +150,11 @@ def metadata_search(
             "of climate datasets to query."
         ),
     ),
-    time_select: TimeSelect = typer.Option(
+    time_select: SelectMethod = typer.Option(
         "flexible",
         "-ts",
         "--time-select",
-        help=TimeSelect.get_help(),
+        help=SelectMethod.get_help("time"),
     ),
     time: Optional[str] = typer.Option(
         None,
@@ -143,6 +170,24 @@ def metadata_search(
             " valid."
         ),
     ),
+    bbox: Optional[Tuple[float, float, float, float]] = typer.Option(
+        None,
+        "-b",
+        "--bbox",
+        help=(
+            "Special search facet to refine/subset search results by spatial "
+            "extent. This can be a string representation of a bounding box. "
+            "The bounding box has to follow the format ``min_lon max_lon "
+            "min_lat,max_lat``. Valid strings are ``-10 10 -10 10`` to "
+            "``0 5 0 5``."
+        ),
+    ),
+    bbox_select: SelectMethod = typer.Option(
+        "flexible",
+        "-bs",
+        "--bbox-select",
+        help=SelectMethod.get_help("bbox"),
+    ),
     extended_search: bool = typer.Option(
         False,
         "-e",
@@ -188,6 +233,8 @@ def metadata_search(
         *(facets or []),
         time=time or "",
         time_select=cast(Literal["file", "flexible", "strict"], time_select.value),
+        bbox=bbox or None,
+        bbox_select=cast(Literal["file", "flexible", "strict"], bbox_select.value),
         flavour=cast(
             Literal["freva", "cmip6", "cmip5", "cordex", "nextgems", "user"],
             flavour.value,
@@ -245,11 +292,11 @@ def data_search(
             "of climate datasets to query."
         ),
     ),
-    time_select: TimeSelect = typer.Option(
+    time_select: SelectMethod = typer.Option(
         "flexible",
         "-ts",
         "--time-select",
-        help=TimeSelect.get_help(),
+        help=SelectMethod.get_help("time"),
     ),
     zarr: bool = typer.Option(False, "--zarr", help="Create zarr stream files."),
     access_token: Optional[str] = typer.Option(
@@ -274,6 +321,24 @@ def data_search(
             " valid."
         ),
     ),
+    bbox: Optional[Tuple[float, float, float, float]] = typer.Option(
+        None,
+        "-b",
+        "--bbox",
+        help=(
+            "Special search facet to refine/subset search results by spatial "
+            "extent. This can be a string representation of a bounding box. "
+            "The bounding box has to follow the format ``min_lon max_lon "
+            "min_lat max_lat``. Valid strings are ``-10 10 -10 10`` to "
+            "``0 5 0 5``."
+        ),
+    ),
+    bbox_select: SelectMethod = typer.Option(
+        "flexible",
+        "-bs",
+        "--bbox-select",
+        help=SelectMethod.get_help("bbox"),
+    ),
     parse_json: bool = typer.Option(
         False, "-j", "--json", help="Parse output in json format."
     ),
@@ -311,6 +376,8 @@ def data_search(
         *(facets or []),
         time=time or "",
         time_select=cast(Literal["file", "flexible", "strict"], time_select),
+        bbox=bbox or None,
+        bbox_select=cast(Literal["file", "flexible", "strict"], bbox_select),
         flavour=cast(
             Literal["freva", "cmip6", "cmip5", "cordex", "nextgems", "user"],
             flavour.value,
@@ -371,11 +438,11 @@ def intake_catalogue(
             "of climate datasets to query."
         ),
     ),
-    time_select: TimeSelect = typer.Option(
+    time_select: SelectMethod = typer.Option(
         "flexible",
         "-ts",
         "--time-select",
-        help=TimeSelect.get_help(),
+        help=SelectMethod.get_help("time"),
     ),
     time: Optional[str] = typer.Option(
         None,
@@ -391,6 +458,24 @@ def intake_catalogue(
             " valid."
         ),
     ),
+    bbox: Optional[Tuple[float, float, float, float]] = typer.Option(
+        None,
+        "-b",
+        "--bbox",
+        help=(
+            "Special search facet to refine/subset search results by spatial "
+            "extent. This can be a string representation of a bounding box. "
+            "The bounding box has to follow the format ``min_lon max_lon "
+            "min_lat max_lat``. Valid strings are ``-10 10 -10 10`` to "
+            "``0 5 0 5``."
+        ),
+    ),
+    bbox_select: SelectMethod = typer.Option(
+        "flexible",
+        "-bs",
+        "--bbox-select",
+        help=SelectMethod.get_help("bbox"),
+    ),
     zarr: bool = typer.Option(
         False, "--zarr", help="Create zarr stream files, as catalogue targets."
     ),
@@ -442,6 +527,8 @@ def intake_catalogue(
         *(facets or []),
         time=time or "",
         time_select=cast(Literal["file", "flexible", "strict"], time_select),
+        bbox=bbox or None,
+        bbox_select=cast(Literal["file", "flexible", "strict"], bbox_select),
         flavour=cast(
             Literal["freva", "cmip6", "cmip5", "cordex", "nextgems", "user"],
             flavour.value,
@@ -461,7 +548,145 @@ def intake_catalogue(
             print(Path(temp_f.name).read_text())
 
 
-@databrowser_app.command(name="data-count", help="Count the databrowser search results")
+@databrowser_app.command(
+    name="stac-catalogue",
+    help="Create a static STAC catalogue from the search."
+)
+@exception_handler
+def stac_catalogue(
+    search_keys: Optional[List[str]] = typer.Argument(
+        default=None,
+        help="Refine your data search with this `key=value` pair search "
+        "parameters. The parameters could be, depending on the DRS standard, "
+        "flavour product, project model etc.",
+    ),
+    facets: Optional[List[str]] = typer.Option(
+        None,
+        "--facet",
+        help=(
+            "If you are not sure about the correct search key's you can use"
+            " the ``--facet`` flag to search of any matching entries. For "
+            "example --facet 'era5' would allow you to search for any entries"
+            " containing era5, regardless of project, product etc."
+        ),
+    ),
+    uniq_key: UniqKeys = typer.Option(
+        "file",
+        "--uniq-key",
+        "-u",
+        help=(
+            "The type of search result, which can be either “file” "
+            "or “uri”. This parameter determines whether the search will be "
+            "based on file paths or Uniform Resource Identifiers"
+        ),
+    ),
+    flavour: Flavours = typer.Option(
+        "freva",
+        "--flavour",
+        "-f",
+        help=(
+            "The Data Reference Syntax (DRS) standard specifying the type "
+            "of climate datasets to query."
+        ),
+    ),
+    time_select: SelectMethod = typer.Option(
+        "flexible",
+        "-ts",
+        "--time-select",
+        help=SelectMethod.get_help("time"),
+    ),
+    time: Optional[str] = typer.Option(
+        None,
+        "-t",
+        "--time",
+        help=(
+            "Special search facet to refine/subset search results by time. "
+            "This can be a string representation of a time range or a single "
+            "time step. The time steps have to follow ISO-8601. Valid strings "
+            "are ``%Y-%m-%dT%H:%M`` to ``%Y-%m-%dT%H:%M`` for time ranges and "
+            "``%Y-%m-%dT%H:%M``. **Note**: You don't have to give the full "
+            "string format to subset time steps ``%Y``, ``%Y-%m`` etc are also"
+            " valid."
+        ),
+    ),
+    bbox: Optional[Tuple[float, float, float, float]] = typer.Option(
+        None,
+        "-b",
+        "--bbox",
+        help=(
+            "Special search facet to refine/subset search results by spatial "
+            "extent. This can be a string representation of a bounding box. "
+            "The bounding box has to follow the format ``min_lon max_lon "
+            "min_lat max_lat``. Valid strings are ``-10 10 -10 10`` to "
+            "``0 5 0 5``."
+        ),
+    ),
+    bbox_select: SelectMethod = typer.Option(
+        "flexible",
+        "-bs",
+        "--bbox-select",
+        help=SelectMethod.get_help("bbox"),
+    ),
+    host: Optional[str] = typer.Option(
+        None,
+        "--host",
+        help=(
+            "Set the hostname of the databrowser, if not set (default) "
+            "the hostname is read from a config file"
+        ),
+    ),
+    verbose: int = typer.Option(0, "-v", help="Increase verbosity", count=True),
+    multiversion: bool = typer.Option(
+        False,
+        "--multi-version",
+        help="Select all versions and not just the latest version (default).",
+    ),
+    version: Optional[bool] = typer.Option(
+        False,
+        "-V",
+        "--version",
+        help="Show version an exit",
+        callback=version_callback,
+    ),
+    filename: Optional[Path] = typer.Option(
+        None,
+        "-o",
+        "--filename",
+        help=(
+            "Path to the file where the static STAC catalogue, "
+            "should be written to. If you don't specify or the path "
+            "does not exist, the file will be created in the current "
+            "working directory. "
+        ),
+    ),
+) -> None:
+    """Create a STAC catalogue for climate datasets based on the specified
+    Data Reference Syntax (DRS) standard (flavour) and the type of search
+    result (uniq_key), which can be either "file" or "uri"."""
+    logger.set_verbosity(verbose)
+    result = databrowser(
+        *(facets or []),
+        time=time or "",
+        time_select=cast(Literal["file", "flexible", "strict"], time_select),
+        bbox=bbox or None,
+        bbox_select=cast(Literal["file", "flexible", "strict"], bbox_select),
+        flavour=cast(
+            Literal["freva", "cmip6", "cmip5", "cordex", "nextgems", "user"],
+            flavour.value,
+        ),
+        uniq_key=cast(Literal["uri", "file"], uniq_key.value),
+        host=host,
+        fail_on_error=False,
+        multiversion=multiversion,
+        stream_zarr=False,
+        **(parse_cli_args(search_keys or [])),
+    )
+    print(result.stac_catalogue(filename=filename))
+
+
+@databrowser_app.command(
+    name="data-count", help="Count the databrowser search results"
+)
 @exception_handler
 def count_values(
     search_keys: Optional[List[str]] = typer.Argument(
@@ -495,11 +720,11 @@ def count_values(
             "of climate datasets to query."
         ),
     ),
-    time_select: TimeSelect = typer.Option(
+    time_select: SelectMethod = typer.Option(
         "flexible",
         "-ts",
         "--time-select",
-        help=TimeSelect.get_help(),
+        help=SelectMethod.get_help("time"),
     ),
     time: Optional[str] = typer.Option(
         None,
@@ -515,6 +740,24 @@ def count_values(
             " valid."
         ),
     ),
+    bbox: Optional[Tuple[float, float, float, float]] = typer.Option(
+        None,
+        "-b",
+        "--bbox",
+        help=(
+            "Special search facet to refine/subset search results by spatial "
+            "extent. This can be a string representation of a bounding box. "
+            "The bounding box has to follow the format ``min_lon max_lon "
+            "min_lat max_lat``. Valid strings are ``-10 10 -10 10`` to "
+            "``0 5 0 5``."
+        ),
+    ),
+    bbox_select: SelectMethod = typer.Option(
+        "flexible",
+        "-bs",
+        "--bbox-select",
+        help=SelectMethod.get_help("bbox"),
+    ),
     extended_search: bool = typer.Option(
         False,
         "-e",
@@ -559,12 +802,16 @@ def count_values(
     result: Union[int, Dict[str, Dict[str, int]]] = 0
     search_kws = parse_cli_args(search_keys or [])
     time = cast(str, time or search_kws.pop("time", ""))
+    bbox = cast(Optional[Tuple[float, float, float, float]],
+                bbox or search_kws.pop("bbox", None))
     facets = facets or []
     if detail:
         result = databrowser.count_values(
             *facets,
             time=time or "",
             time_select=cast(Literal["file", "flexible", "strict"], time_select),
+            bbox=bbox or None,
+            bbox_select=cast(Literal["file", "flexible", "strict"], bbox_select),
             flavour=cast(
                 Literal["freva", "cmip6", "cmip5", "cordex", "nextgems", "user"],
                 flavour.value,
@@ -581,8 +828,12 @@ def count_values(
                 *facets,
                 time=time or "",
                 time_select=cast(Literal["file", "flexible", "strict"], time_select),
+                bbox=bbox or None,
+                bbox_select=cast(Literal["file", "flexible", "strict"], bbox_select),
                 flavour=cast(
-                    Literal["freva", "cmip6", "cmip5", "cordex", "nextgems", "user"],
+                    Literal[
+                        "freva", "cmip6", "cmip5", "cordex", "nextgems", "user"
+                    ],
                     flavour.value,
                 ),
                 host=host,
@@ -662,11 +913,13 @@ def user_data_add(
         action="add",
         userdata_items=cast(List[Union[str, xr.Dataset]], paths),
         metadata=facet_dict,
-        host=host
+        host=host,
     )
 
 
-@user_data_app.command(name="delete", help="Delete user data from the databrowser.")
+@user_data_app.command(
+    name="delete", help="Delete user data from the databrowser."
+)
 @exception_handler
 def user_data_delete(
     search_keys: List[str] = typer.Option(

{freva_client-2411.0.0 → freva_client-2505.0.0}/src/freva_client/query.py

@@ -1,6 +1,5 @@
 """Query climate data sets by using-key value pair search queries."""
 
-
 import sys
 from collections import defaultdict
 from fnmatch import fnmatch
@@ -64,8 +63,10 @@ class databrowser:
         timestamp. The timestamps has to follow ISO-8601. Valid strings are
         ``%Y-%m-%dT%H:%M to %Y-%m-%dT%H:%M`` for time ranges or
         ``%Y-%m-%dT%H:%M`` for single time stamps.
-        **Note**: You don't have to give the full string format to subset
-        time steps: `%Y`, `%Y-%m` etc are also valid.
+
+        .. note:: You don't have to give the full string format to subset time
+                steps ``%Y``, ``%Y-%m`` etc are also valid.
+
     time_select: str, default: flexible
         Operator that specifies how the time period is selected. Choose from
         flexible (default), strict or file. ``strict`` returns only those files
@@ -75,11 +76,25 @@ class databrowser:
         ``flexible`` returns those files that have either start or end period
         covered. ``file`` will only return files where the entire time
         period is contained within `one single` file.
+    bbox: str, default: ""
+        Special search facet to refine/subset search results by spatial extent.
+        This can be a list representation of a bounding box or a WKT polygon.
+        Valid lists are ``min_lon max_lon min_lat max_lat`` for bounding
+        boxes and Well-Known Text (WKT) format for polygons.
+
+    bbox_select: str, default: flexible
+        Operator that specifies how the spatial extent is selected. Choose from
+        flexible (default), strict or file. ``strict`` returns only those files
+        that fully contain the query extent. The bbox search ``-10 10 -10 10``
+        will not select files covering only ``0 5 0 5`` with the ``strict``
+        method. ``flexible`` will select those files as it returns files that
+        have any overlap with the query extent. ``file`` will only return files
+        where the entire spatial extent is contained by the query geometry.
     uniq_key: str, default: file
         Chose if the solr search query should return paths to files or
         uris, uris will have the file path along with protocol of the storage
-        system. Uris can be useful if the search query result should be
-        used libraries like fsspec.
+        system. URIs are useful when working with libraries like fsspec, which
+        require protocol information.
     host: str, default: None
         Override the host name of the databrowser server. This is usually the
         url where the freva web site can be found. Such as www.freva.dkrz.de.
@@ -215,6 +230,8 @@ class databrowser:
         time: Optional[str] = None,
         host: Optional[str] = None,
         time_select: Literal["flexible", "strict", "file"] = "flexible",
+        bbox: Optional[Tuple[float, float, float, float]] = None,
+        bbox_select: Literal["flexible", "strict", "file"] = "flexible",
         stream_zarr: bool = False,
         multiversion: bool = False,
         fail_on_error: bool = False,
@@ -239,6 +256,10 @@ class databrowser:
         if time:
             self._params["time"] = time
             self._params["time_select"] = time_select
+        if bbox:
+            bbox_str = ",".join(map(str, bbox))
+            self._params["bbox"] = bbox_str
+            self._params["bbox_select"] = bbox_select
         if facets:
             self._add_search_keyword_args_from_facet(facets, facet_search)
 
@@ -246,7 +267,8 @@ class databrowser:
         self, facets: Tuple[str, ...], search_kw: Dict[str, List[str]]
     ) -> None:
         metadata = {
-            k: v[::2] for (k, v) in self._facet_search(extended_search=True).items()
+            k: v[::2]
+            for (k, v) in self._facet_search(extended_search=True).items()
         }
         primary_key = list(metadata.keys() or ["project"])[0]
         num_facets = 0
@@ -304,7 +326,9 @@ class databrowser:
 
         # Create a table-like structure for available flavors and search facets
         style = 'style="text-align: left"'
-        facet_heading = f"Available search facets for <em>{self._flavour}</em> flavour"
+        facet_heading = (
+            f"Available search facets for <em>{self._flavour}</em> flavour"
+        )
         html_repr = (
             "<table>"
             f"<tr><th colspan='2' {style}>{self.__class__.__name__}"
@@ -345,7 +369,9 @@ class databrowser:
         if self._stream_zarr:
             token = self._auth.check_authentication(auth_url=self._cfg.auth_url)
             url = self._cfg.zarr_loader_url
-            kwargs["headers"] = {"Authorization": f"Bearer {token['access_token']}"}
+            kwargs["headers"] = {
+                "Authorization": f"Bearer {token['access_token']}"
+            }
             kwargs["params"] = {"catalogue-type": "intake"}
         result = self._request("GET", url, **kwargs)
         if result is None:
@@ -357,7 +383,9 @@ class databrowser:
                 for content in result.iter_content(decode_unicode=False):
                     stream.write(content)
         except Exception as error:
-            raise ValueError(f"Couldn't write catalogue content: {error}") from None
+            raise ValueError(
+                f"Couldn't write catalogue content: {error}"
+            ) from None
 
     def intake_catalogue(self) -> intake_esm.core.esm_datastore:
         """Create an intake esm catalogue object from the search.
@@ -388,7 +416,88 @@ class databrowser:
         """
         with NamedTemporaryFile(suffix=".json") as temp_f:
             self._create_intake_catalogue_file(temp_f.name)
-            return intake.open_esm_datastore(temp_f.name)
+            return cast(
+                intake_esm.core.esm_datastore,
+                intake.open_esm_datastore(temp_f.name),
+            )
+
+    def stac_catalogue(
+        self,
+        filename: Optional[Union[str, Path]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """Create a static STAC catalogue from
+        the search.
+
+        Parameters
+        ~~~~~~~~~~
+        filename: str, default: None
+            The filename of the STAC catalogue. If not given
+            or doesn't exist the STAC catalogue will be saved
+            to the current working directory.
+        **kwargs: Any
+            Additional keyword arguments to be passed to the request.
+
+        Returns
+        ~~~~~~~
+        BinaryIO
+        A zip file stream
+
+        Raises
+        ~~~~~~
+        ValueError: If stac-catalogue creation failed.
+
+        Example
+        ~~~~~~~
+        Let's create a static STAC catalogue:
+
+        .. execute_code::
+
+            from tempfile import mktemp
+            temp_path = mktemp(suffix=".zip")
+
+            from freva_client import databrowser
+            db = databrowser(dataset="cmip6-hsm")
+            db.stac_catalogue(filename=temp_path)
+            print(f"STAC catalog saved to: {temp_path}")
+
+        """
+
+        kwargs.update({"stream": True})
+        stac_url = self._cfg.stac_url
+        pprint("[b][green]Downloading the STAC catalog started ...[green][b]")
+        result = self._request("GET", stac_url, **kwargs)
+        if result is None or result.status_code == 404:
+            raise ValueError(  # pragma: no cover
+                "No STAC catalog found. Please check if you have any search results."
+            )
+        default_filename = (
+            result.headers.get("Content-Disposition", "")
+            .split("filename=")[-1]
+            .strip('"')
+        )
+
+        if filename is None:
+            save_path = Path.cwd() / default_filename
+        else:
+            save_path = Path(cast(str, filename))
+        if save_path.is_dir() and save_path.exists():
+            save_path = save_path / default_filename
+
+        save_path.parent.mkdir(parents=True, exist_ok=True)
+
+        total_size = 0
+        with open(save_path, "wb") as f:
+            for chunk in result.iter_content(chunk_size=8192):
+                if chunk:
+                    f.write(chunk)
+                    total_size += len(chunk)
+
+        return (
+            f"STAC catalog saved to: {save_path} "
+            f"(size: {total_size / 1024 / 1024:.2f} MB). "
+            f"Or simply download from: {result.url}"
+        )
 
     @classmethod
     def count_values(
@@ -400,6 +509,8 @@ class databrowser:
         time: Optional[str] = None,
         host: Optional[str] = None,
         time_select: Literal["flexible", "strict", "file"] = "flexible",
+        bbox: Optional[Tuple[float, float, float, float]] = None,
+        bbox_select: Literal["flexible", "strict", "file"] = "flexible",
         multiversion: bool = False,
         fail_on_error: bool = False,
         extended_search: bool = False,
@@ -423,8 +534,11 @@ class databrowser:
             This can be a string representation of a time range or a single
             timestamp. The timestamp has to follow ISO-8601. Valid strings are
             ``%Y-%m-%dT%H:%M`` to ``%Y-%m-%dT%H:%M`` for time ranges and
-            ``%Y-%m-%dT%H:%M``. **Note**: You don't have to give the full string
-            format to subset time steps ``%Y``, ``%Y-%m`` etc are also valid.
+            ``%Y-%m-%dT%H:%M``.
+
+            .. note:: You don't have to give the full string format to subset time
+                    steps ``%Y``, ``%Y-%m`` etc are also valid.
+
         time_select: str, default: flexible
             Operator that specifies how the time period is selected. Choose from
             flexible (default), strict or file. ``strict`` returns only those files
@@ -434,6 +548,20 @@ class databrowser:
             ``flexible`` returns those files that have either start or end period
             covered. ``file`` will only return files where the entire time
             period is contained within `one single` file.
+        bbox: str, default: ""
+            Special search facet to refine/subset search results by spatial extent.
+            This can be a list representation of a bounding box or a WKT polygon.
+            Valid lists are ``min_lon max_lon min_lat max_lat`` for bounding
+            boxes and Well-Known Text (WKT) format for polygons.
+
+        bbox_select: str, default: flexible
+            Operator that specifies how the spatial extent is selected. Choose from
+            flexible (default), strict or file. ``strict`` returns only those files
+            that fully contain the query extent. The bbox search ``-10 10 -10 10``
+            will not select files covering only ``0 5 0 5`` with the ``strict``
+            method. ``flexible`` will select those files as it returns files that
+            have any overlap with the query extent. ``file`` will only return files
+            where the entire spatial extent is contained by the query geometry.
         extended_search: bool, default: False
             Retrieve information on additional search keys.
         host: str, default: None
@@ -485,6 +613,8 @@ class databrowser:
             flavour=flavour,
             time=time,
             time_select=time_select,
+            bbox=bbox,
+            bbox_select=bbox_select,
             host=host,
             multiversion=multiversion,
             fail_on_error=fail_on_error,
@@ -495,7 +625,9 @@ class databrowser:
         result = this._facet_search(extended_search=extended_search)
         counts = {}
         for facet, value_counts in result.items():
-            counts[facet] = dict(zip(value_counts[::2], map(int, value_counts[1::2])))
+            counts[facet] = dict(
+                zip(value_counts[::2], map(int, value_counts[1::2]))
+            )
         return counts
 
     @cached_property
@@ -520,7 +652,8 @@ class databrowser:
 
         """
         return {
-            k: v[::2] for (k, v) in self._facet_search(extended_search=True).items()
+            k: v[::2]
+            for (k, v) in self._facet_search(extended_search=True).items()
         }
 
     @classmethod
@@ -533,6 +666,8 @@ class databrowser:
         time: Optional[str] = None,
         host: Optional[str] = None,
         time_select: Literal["flexible", "strict", "file"] = "flexible",
+        bbox: Optional[Tuple[float, float, float, float]] = None,
+        bbox_select: Literal["flexible", "strict", "file"] = "flexible",
         multiversion: bool = False,
         fail_on_error: bool = False,
         extended_search: bool = False,
@@ -559,8 +694,11 @@ class databrowser:
             This can be a string representation of a time range or a single
             timestamp. The timestamp has to follow ISO-8601. Valid strings are
             ``%Y-%m-%dT%H:%M`` to ``%Y-%m-%dT%H:%M`` for time ranges and
-            ``%Y-%m-%dT%H:%M``. **Note**: You don't have to give the full string
-            format to subset time steps ``%Y``, ``%Y-%m`` etc are also valid.
+            ``%Y-%m-%dT%H:%M``.
+
+            .. note:: You don't have to give the full string format to subset time
+                    steps ``%Y``, ``%Y-%m`` etc are also valid.
+
         time_select: str, default: flexible
             Operator that specifies how the time period is selected. Choose from
             flexible (default), strict or file. ``strict`` returns only those files
@@ -570,6 +708,20 @@ class databrowser:
             ``flexible`` returns those files that have either start or end period
             covered. ``file`` will only return files where the entire time
             period is contained within *one single* file.
+        bbox: str, default: ""
+            Special search facet to refine/subset search results by spatial extent.
+            This can be a list representation of a bounding box or a WKT polygon.
+            Valid lists are ``min_lon max_lon min_lat max_lat`` for bounding
+            boxes and Well-Known Text (WKT) format for polygons.
+
+        bbox_select: str, default: flexible
+            Operator that specifies how the spatial extent is selected. Choose from
+            flexible (default), strict or file. ``strict`` returns only those files
+            that fully contain the query extent. The bbox search ``-10 10 -10 10``
+            will not select files covering only ``0 5 0 5`` with the ``strict``
+            method. ``flexible`` will select those files as it returns files that
+            have any overlap with the query extent. ``file`` will only return files
+            where the entire spatial extent is contained by the query geometry.
         extended_search: bool, default: False
             Retrieve information on additional search keys.
         multiversion: bool, default: False
@@ -638,12 +790,30 @@ class databrowser:
             from freva_client import databrowser
             print(databrowser.metadata_search("reana*", realm="ocean", flavour="cmip6"))
 
+        In datasets with multiple versions only the `latest` version (i.e.
+        `highest` version number) is returned by default. Querying a specific
+        version from a multi versioned datasets requires the ``multiversion``
+        flag in combination with the ``version`` special attribute:
+
+        .. execute_code::
+
+            from freva_client import databrowser
+            res = databrowser.metadata_search(dataset="cmip6-fs",
+                model="access-cm2", version="v20191108", extended_search=True,
+                multiversion=True)
+            print(res)
+
+        If no particular ``version`` is requested, information of all versions
+        will be returned.
+
         """
         this = cls(
             *facets,
             flavour=flavour,
             time=time,
             time_select=time_select,
+            bbox=bbox,
+            bbox_select=bbox_select,
             host=host,
             multiversion=multiversion,
             fail_on_error=fail_on_error,
@@ -653,7 +823,9 @@ class databrowser:
         )
         return {
             k: v[::2]
-            for (k, v) in this._facet_search(extended_search=extended_search).items()
+            for (k, v) in this._facet_search(
+                extended_search=extended_search
+            ).items()
         }
 
     @classmethod
@@ -782,11 +954,11 @@ class databrowser:
             import xarray as xr
             token_info = authenticate(username="janedoe")
             filenames = (
-                "../freva-rest/src/databrowser_api/mock/data/model/regional/cordex/output/EUR-11/"
+                "../freva-rest/src/freva_rest/databrowser_api/mock/data/model/regional/cordex/output/EUR-11/"
                 "GERICS/NCC-NorESM1-M/rcp85/r1i1p1/GERICS-REMO2015/v1/3hr/pr/v20181212/*.nc"
             )
             filename1 = (
-                "../freva-rest/src/databrowser_api/mock/data/model/regional/cordex/output/EUR-11/"
+                "../freva-rest/src/freva_rest/databrowser_api/mock/data/model/regional/cordex/output/EUR-11/"
                 "CLMcom/MPI-M-MPI-ESM-LR/historical/r0i0p0/CLMcom-CCLM4-8-17/v1/fx/orog/v20140515/"
                 "orog_EUR-11_MPI-M-MPI-ESM-LR_historical_r1i1p1_CLMcom-CCLM4-8-17_v1_fx.nc"
             )
@@ -856,7 +1028,7 @@ class databrowser:
         method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"],
         url: str,
         data: Optional[Dict[str, Any]] = None,
-        **kwargs: Any
+        **kwargs: Any,
     ) -> Optional[requests.models.Response]:
         """Request method to handle CRUD operations (GET, POST, PUT, PATCH, DELETE)."""
         method_upper = method.upper()
@@ -864,8 +1036,13 @@ class databrowser:
         params = kwargs.pop("params", {})
         stream = kwargs.pop("stream", False)
 
-        logger.debug("%s request to %s with data: %s and parameters: %s",
-                     method_upper, url, data, {**self._params, **params})
+        logger.debug(
+            "%s request to %s with data: %s and parameters: %s",
+            method_upper,
+            url,
+            data,
+            {**self._params, **params},
+        )
 
         try:
             req = requests.Request(
@@ -873,7 +1050,7 @@ class databrowser:
                 url=url,
                 params={**self._params, **params},
                 json=None if method_upper in "GET" else data,
-                **kwargs
+                **kwargs,
             )
             with requests.Session() as session:
                 prepared = session.prepare_request(req)
@@ -883,8 +1060,10 @@ class databrowser:
 
         except KeyboardInterrupt:
             pprint("[red][b]User interrupt: Exit[/red][/b]", file=sys.stderr)
-        except (requests.exceptions.ConnectionError,
-                requests.exceptions.HTTPError) as error:
+        except (
+            requests.exceptions.ConnectionError,
+            requests.exceptions.HTTPError,
+        ) as error:
             msg = f"{method_upper} request failed with {error}"
             if self._fail_on_error:
                 raise ValueError(msg) from None

{freva_client-2411.0.0 → freva_client-2505.0.0}/src/freva_client/utils/databrowser_utils.py

@@ -53,7 +53,7 @@ class Config:
         ini_parser.read_string(path.read_text())
         config = ini_parser["evaluation_system"]
         scheme, host = self._split_url(
-            config.get("databrowser.host") or config.get("solr.host")
+            config.get("databrowser.host", config.get("solr.host", ""))
         )
         host, _, port = (host or "").partition(":")
         port = port or config.get("databrowser.port", "")
@@ -88,7 +88,9 @@ class Config:
         try:
             res = requests.get(f"{self.databrowser_url}/overview", timeout=15)
         except requests.exceptions.ConnectionError:
-            raise ValueError(f"Could not connect to {self.databrowser_url}") from None
+            raise ValueError(
+                f"Could not connect to {self.databrowser_url}"
+            ) from None
         return cast(Dict[str, Any], res.json())
 
     def _get_databrowser_host_from_config(self) -> str:
@@ -103,7 +105,9 @@ class Config:
             Path(appdirs.user_config_dir("freva")) / "freva.toml": "toml",
             Path(self.get_dirs(user=True)) / "freva.toml": "toml",
             freva_config: "toml",
-            Path(os.environ.get("EVALUATION_SYSTEM_CONFIG_FILE") or eval_conf): "ini",
+            Path(
+                os.environ.get("EVALUATION_SYSTEM_CONFIG_FILE") or eval_conf
+            ): "ini",
         }
         for config_path, config_type in paths.items():
             if config_path.is_file():
@@ -130,7 +134,9 @@ class Config:
     @property
     def search_url(self) -> str:
         """Define the data search endpoint."""
-        return f"{self.databrowser_url}/data_search/{self.flavour}/{self.uniq_key}"
+        return (
+            f"{self.databrowser_url}/data-search/{self.flavour}/{self.uniq_key}"
+        )
 
     @property
     def zarr_loader_url(self) -> str:
@@ -140,13 +146,19 @@ class Config:
     @property
     def intake_url(self) -> str:
         """Define the url for creating intake catalogues."""
-        return f"{self.databrowser_url}/intake_catalogue/{self.flavour}/{self.uniq_key}"
+        return f"{self.databrowser_url}/intake-catalogue/{self.flavour}/{self.uniq_key}"
+
+    @property
+    def stac_url(self) -> str:
+        """Define the url for creating stac catalogue."""
+        return f"{self.databrowser_url}/stac-catalogue/{self.flavour}/{self.uniq_key}"
 
     @property
     def metadata_url(self) -> str:
         """Define the endpoint for the metadata search."""
         return (
-            f"{self.databrowser_url}/metadata_search/" f"{self.flavour}/{self.uniq_key}"
+            f"{self.databrowser_url}/metadata-search/"
+            f"{self.flavour}/{self.uniq_key}"
         )
 
     @staticmethod
@@ -166,7 +178,7 @@ class Config:
         if port:
             hostname = f"{hostname}:{port}"
         hostname = hostname.partition("/")[0]
-        return f"{scheme}://{hostname}/api"
+        return f"{scheme}://{hostname}/api/freva-nextgen"
 
     @staticmethod
     def get_dirs(user: bool = True) -> Path:
@@ -199,9 +211,12 @@ class UserDataHandler:
     This class is used for processing user data and extracting metadata
     from the data files.
     """
+
     def __init__(self, userdata_items: List[Union[str, xr.Dataset]]) -> None:
         self._suffixes = [".nc", ".nc4", ".grb", ".grib", ".zarr", "zar"]
-        self.user_metadata: List[Dict[str, Union[str, List[str], Dict[str, str]]]] = []
+        self.user_metadata: List[
+            Dict[str, Union[str, List[str], Dict[str, str]]]
+        ] = []
         self._metadata_collection: List[Dict[str, Union[str, List[str]]]] = []
         try:
             self._executor = concurrent.futures.ThreadPoolExecutor(
@@ -238,28 +253,37 @@ class UserDataHandler:
                 validated_xarray_datasets.append(data)
 
         if not validated_paths and not validated_xarray_datasets:
-            raise FileNotFoundError("No valid file paths or xarray datasets found.")
+            raise FileNotFoundError(
+                "No valid file paths or xarray datasets found."
+            )
         return {
             "validated_user_paths": validated_paths,
             "validated_user_xrdatasets": validated_xarray_datasets,
         }
 
-    def _process_user_data(self, userdata_items: List[Union[str, xr.Dataset]],
-                           ) -> None:
+    def _process_user_data(
+        self,
+        userdata_items: List[Union[str, xr.Dataset]],
+    ) -> None:
         """Process xarray datasets and file paths using thread pool."""
         futures = []
-        validated_userdata: Dict[str, Union[List[Path], List[xr.Dataset]]] = \
+        validated_userdata: Dict[str, Union[List[Path], List[xr.Dataset]]] = (
             self._validate_user_data(userdata_items)
+        )
         if validated_userdata["validated_user_xrdatasets"]:
             futures.append(
-                self._executor.submit(self._process_userdata_in_executor,
-                                      validated_userdata["validated_user_xrdatasets"])
+                self._executor.submit(
+                    self._process_userdata_in_executor,
+                    validated_userdata["validated_user_xrdatasets"],
+                )
             )
 
         if validated_userdata["validated_user_paths"]:
             futures.append(
-                self._executor.submit(self._process_userdata_in_executor,
-                                      validated_userdata["validated_user_paths"])
+                self._executor.submit(
+                    self._process_userdata_in_executor,
+                    validated_userdata["validated_user_paths"],
+                )
             )
         for future in futures:
             try:
@@ -309,11 +333,11 @@ class UserDataHandler:
 
         try:
             dset = (
-                path if isinstance(path, xr.Dataset)
-                else xr.open_mfdataset(str(path),
-                                       parallel=False,
-                                       use_cftime=True,
-                                       lock=False)
+                path
+                if isinstance(path, xr.Dataset)
+                else xr.open_mfdataset(
+                    str(path), parallel=False, use_cftime=True, lock=False
+                )
             )
             time_freq = dset.attrs.get("frequency", "")
             data_vars = list(map(str, dset.data_vars))
@@ -328,16 +352,26 @@ class UserDataHandler:
             return {}
         if len(times) > 0:
             try:
-                time_str = f"[{times[0].isoformat()}Z TO {times[-1].isoformat()}Z]"
-                dt = abs((times[1] - times[0]).total_seconds()) if len(times) > 1 else 0
+                time_str = (
+                    f"[{times[0].isoformat()}Z TO {times[-1].isoformat()}Z]"
+                )
+                dt = (
+                    abs((times[1] - times[0]).total_seconds())
+                    if len(times) > 1
+                    else 0
+                )
             except Exception as non_cftime:
-                logger.info("The time var is not based on the cftime: %s", non_cftime)
+                logger.info(
+                    "The time var is not based on the cftime: %s", non_cftime
+                )
                 time_str = (
                     f"[{np.datetime_as_string(times[0], unit='s')}Z TO "
                     f"{np.datetime_as_string(times[-1], unit='s')}Z]"
                 )
                 dt = (
-                    abs((times[1] - times[0]).astype("timedelta64[s]").astype(int))
+                    abs(
+                        (times[1] - times[0]).astype("timedelta64[s]").astype(int)
+                    )
                     if len(times) > 1
                     else 0
                 )
@@ -357,7 +391,9 @@ class UserDataHandler:
 
         _data: Dict[str, Union[str, List[str], Dict[str, str]]] = {}
         _data.setdefault("variable", variables[0])
-        _data.setdefault("time_frequency", self._get_time_frequency(dt, time_freq))
+        _data.setdefault(
+            "time_frequency", self._get_time_frequency(dt, time_freq)
+        )
         _data["time"] = time_str
         _data.setdefault("cmor_table", _data["time_frequency"])
         _data.setdefault("version", "")