freva-client 2505.0.0__py3-none-any.whl → 2506.0.0__py3-none-any.whl

freva_client/cli/databrowser_cli.py

@@ -7,7 +7,7 @@ import json
 from enum import Enum
 from pathlib import Path
 from tempfile import NamedTemporaryFile
-from typing import Dict, List, Literal, Optional, Tuple, Union, cast
+from typing import Dict, List, Optional, Tuple, Union, cast
 
 import typer
 import xarray as xr
@@ -19,16 +19,6 @@ from freva_client.utils import exception_handler, logger
 from .cli_utils import parse_cli_args, version_callback
 
 
-def _auth(url: str, token: Optional[str]) -> None:
-    if token:
-        auth = Auth()
-        auth.set_token(
-            access_token=token, expires=auth.token_expiration_time.timestamp()
-        )
-    else:
-        raise ValueError("`--access-token` is required for authentication.")
-
-
 class UniqKeys(str, Enum):
     """Literal implementation for the cli."""
 
@@ -65,19 +55,19 @@ class SelectMethod(str, Enum):
         """
         examples = {
             "time": ("2000 to 2012", "2010 to 2020"),
-            "bbox": ("-10 10 -10 10", "0 5 0 5")
+            "bbox": ("-10 10 -10 10", "0 5 0 5"),
         }
         descriptions = {
             "time": {
                 "unit": "time period",
                 "start_end": "start or end period",
-                "subset": "time period"
+                "subset": "time period",
             },
             "bbox": {
                 "unit": "spatial extent",
                 "start_end": "any part of the extent",
-                "subset": "spatial extent"
-            }
+                "subset": "spatial extent",
+            },
         }
 
         context_info = descriptions.get(context, descriptions["time"])
@@ -232,13 +222,10 @@ def metadata_search(
     result = databrowser.metadata_search(
         *(facets or []),
         time=time or "",
-        time_select=cast(Literal["file", "flexible", "strict"], time_select.value),
+        time_select=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,
-        ),
+        bbox_select=bbox_select.value,
+        flavour=flavour.value,
         host=host,
         extended_search=extended_search,
         multiversion=multiversion,
@@ -299,12 +286,14 @@ def data_search(
         help=SelectMethod.get_help("time"),
     ),
     zarr: bool = typer.Option(False, "--zarr", help="Create zarr stream files."),
-    access_token: Optional[str] = typer.Option(
+    token_file: Optional[Path] = typer.Option(
         None,
-        "--access-token",
+        "--token-file",
+        "-t",
         help=(
-            "Use this access token for authentication"
-            " when creating a zarr stream files."
+            "Instead of authenticating via code based authentication flow "
+            "you can set the path to the json file that contains a "
+            "`refresh token` containing a refresh_token key."
         ),
     ),
     time: Optional[str] = typer.Option(
@@ -375,14 +364,11 @@ def data_search(
     result = databrowser(
         *(facets or []),
         time=time or "",
-        time_select=cast(Literal["file", "flexible", "strict"], time_select),
+        time_select=time_select.value,
         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),
+        bbox_select=bbox_select.value,
+        flavour=flavour.value,
+        uniq_key=uniq_key.value,
         host=host,
         fail_on_error=False,
         multiversion=multiversion,
@@ -390,7 +376,7 @@ def data_search(
         **(parse_cli_args(search_keys or [])),
     )
     if zarr:
-        _auth(result._cfg.auth_url, access_token)
+        Auth(token_file).authenticate(host=host, _cli=True)
     if parse_json:
         print(json.dumps(sorted(result)))
     else:
@@ -479,12 +465,13 @@ def intake_catalogue(
     zarr: bool = typer.Option(
         False, "--zarr", help="Create zarr stream files, as catalogue targets."
     ),
-    access_token: Optional[str] = typer.Option(
+    token_file: Optional[Path] = typer.Option(
         None,
-        "--access-token",
+        "--token-file",
         help=(
-            "Use this access token for authentication"
-            " when creating a zarr based intake catalogue."
+            "Instead of authenticating via code based authentication flow "
+            "you can set the path to the json file that contains a "
+            "`refresh token` containing a refresh_token key."
         ),
     ),
     filename: Optional[Path] = typer.Option(
@@ -526,14 +513,11 @@ def intake_catalogue(
     result = databrowser(
         *(facets or []),
         time=time or "",
-        time_select=cast(Literal["file", "flexible", "strict"], time_select),
+        time_select=time_select.value,
         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),
+        bbox_select=bbox_select.value,
+        flavour=flavour.value,
+        uniq_key=uniq_key.value,
         host=host,
         fail_on_error=False,
         multiversion=multiversion,
@@ -541,7 +525,7 @@ def intake_catalogue(
         **(parse_cli_args(search_keys or [])),
     )
     if zarr:
-        _auth(result._cfg.auth_url, access_token)
+        Auth(token_file).authenticate(host=host, _cli=True)
     with NamedTemporaryFile(suffix=".json") as temp_f:
         result._create_intake_catalogue_file(str(filename or temp_f.name))
         if not filename:
@@ -549,8 +533,7 @@ def intake_catalogue(
 
 
 @databrowser_app.command(
-    name="stac-catalogue",
-    help="Create a static STAC catalogue from the search."
+    name="stac-catalogue", help="Create a static STAC catalogue from the search."
 )
 @exception_handler
 def stac_catalogue(
@@ -667,14 +650,11 @@ def stac_catalogue(
     result = databrowser(
         *(facets or []),
         time=time or "",
-        time_select=cast(Literal["file", "flexible", "strict"], time_select),
+        time_select=time_select.value,
         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),
+        bbox_select=bbox_select.value,
+        flavour=flavour.value,
+        uniq_key=uniq_key.value,
         host=host,
         fail_on_error=False,
         multiversion=multiversion,
@@ -802,20 +782,19 @@ 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))
+    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),
+            time_select=time_select.value,
             bbox=bbox or None,
-            bbox_select=cast(Literal["file", "flexible", "strict"], bbox_select),
-            flavour=cast(
-                Literal["freva", "cmip6", "cmip5", "cordex", "nextgems", "user"],
-                flavour.value,
-            ),
+            bbox_select=bbox_select.value,
+            flavour=flavour.value,
             host=host,
             extended_search=extended_search,
             multiversion=multiversion,
@@ -827,15 +806,10 @@ def count_values(
             databrowser(
                 *facets,
                 time=time or "",
-                time_select=cast(Literal["file", "flexible", "strict"], time_select),
+                time_select=time_select.value,
                 bbox=bbox or None,
-                bbox_select=cast(Literal["file", "flexible", "strict"], bbox_select),
-                flavour=cast(
-                    Literal[
-                        "freva", "cmip6", "cmip5", "cordex", "nextgems", "user"
-                    ],
-                    flavour.value,
-                ),
+                bbox_select=bbox_select.value,
+                flavour=flavour.value,
                 host=host,
                 multiversion=multiversion,
                 fail_on_error=False,
@@ -884,18 +858,21 @@ def user_data_add(
             "the hostname is read from a config file."
         ),
     ),
-    access_token: Optional[str] = typer.Option(
+    token_file: Optional[Path] = typer.Option(
         None,
-        "--access-token",
-        help="Access token for authentication when adding user data.",
+        "--token-file",
+        help=(
+            "Instead of authenticating via code based authentication flow "
+            "you can set the path to the json file that contains a "
+            "`refresh token` containing a refresh_token key."
+        ),
     ),
     verbose: int = typer.Option(0, "-v", help="Increase verbosity", count=True),
 ) -> None:
     """Add user data into the databrowser."""
     logger.set_verbosity(verbose)
     logger.debug("Checking if the user has the right to add data")
-    result = databrowser(host=host)
-    _auth(result._cfg.auth_url, access_token)
+    Auth(token_file).authenticate(host=host, _cli=True)
 
     facet_dict = {}
     if facets:
@@ -937,18 +914,21 @@ def user_data_delete(
             "the hostname is read from a config file."
         ),
     ),
-    access_token: Optional[str] = typer.Option(
+    token_file: Optional[Path] = typer.Option(
         None,
-        "--access-token",
-        help="Access token for authentication when deleting user data.",
+        "--token-file",
+        help=(
+            "Instead of authenticating via code based authentication flow "
+            "you can set the path to the json file that contains a "
+            "`refresh token` containing a refresh_token key."
+        ),
     ),
     verbose: int = typer.Option(0, "-v", help="Increase verbosity", count=True),
 ) -> None:
     """Delete user data from the databrowser."""
     logger.set_verbosity(verbose)
     logger.debug("Checking if the user has the right to delete data")
-    result = databrowser(host=host)
-    _auth(result._cfg.auth_url, access_token)
+    Auth(token_file).authenticate(host=host, _cli=True)
 
     search_key_dict = {}
     if search_keys:

freva_client/query.py

@@ -44,12 +44,12 @@ class databrowser:
     Parameters
     ~~~~~~~~~~
 
-    *facets: str
+    facets: str
         If you are not sure about the correct search key's you can use
         positional arguments to search of any matching entries. For example
         'era5' would allow you to search for any entries
         containing era5, regardless of project, product etc.
-    **search_keys: str
+    search_keys: str
         The search constraints applied in the data search. If not given
         the whole dataset will be queried.
     flavour: str, default: freva
@@ -128,7 +128,7 @@ class databrowser:
     databrowser class using the ``experiment`` search constraint.
     If you just 'print' the created object you will get a quick overview:
 
-    .. execute_code::
+    .. code-block:: python
 
         from freva_client import databrowser
         db = databrowser(experiment="cmorph", uniq_key="uri")
@@ -137,7 +137,7 @@ class databrowser:
     After having created the search object you can acquire different kinds of
     information like the number of found objects:
 
-    .. execute_code::
+    .. code-block:: python
 
         from freva_client import databrowser
         db = databrowser(experiment="cmorph", uniq_key="uri")
@@ -146,7 +146,7 @@ class databrowser:
 
     Or you can retrieve the combined metadata of the search objects.
 
-    .. execute_code::
+    .. code-block:: python
 
         from freva_client import databrowser
         db = databrowser(experiment="cmorph", uniq_key="uri")
@@ -154,7 +154,7 @@ class databrowser:
 
     Most importantly you can retrieve the locations of all encountered objects
 
-    .. execute_code::
+    .. code-block:: python
 
         from freva_client import databrowser
         db = databrowser(experiment="cmorph", uniq_key="uri")
@@ -167,7 +167,7 @@ class databrowser:
     You can also set a different flavour, for example according to cmip6
     standard:
 
-    .. execute_code::
+    .. code-block:: python
 
         from freva_client import databrowser
         db = databrowser(flavour="cmip6", experiment_id="cmorph")
@@ -179,7 +179,7 @@ class databrowser:
     for getting all ocean reanalysis datasets you can apply the 'reana*'
     search key as a positional argument:
 
-    .. execute_code::
+    .. code-block:: python
 
         from freva_client import databrowser
         db = databrowser("reana*", realm="ocean", flavour="cmip6")
@@ -195,17 +195,15 @@ class databrowser:
     before you are able to access the data. Refer also to the
     :py:meth:`freva_client.authenticate` method.
 
-    .. execute_code::
+    .. code-block:: python
 
-        from freva_client import authenticate, databrowser
-        token_info = authenticate(username="janedoe")
+        from freva_client import databrowser
         db = databrowser(dataset="cmip6-fs", stream_zarr=True)
         zarr_files = list(db)
-        print(zarr_files)
 
     After you have created the paths to the zarr files you can open them
 
-    ::
+    .. code-block:: python
 
         import xarray as xr
         dset = xr.open_dataset(
@@ -291,7 +289,7 @@ class databrowser:
         headers = {}
         if self._stream_zarr:
             query_url = self._cfg.zarr_loader_url
-            token = self._auth.check_authentication(auth_url=self._cfg.auth_url)
+            token = self._auth.authenticate(config=self._cfg)
             headers = {"Authorization": f"Bearer {token['access_token']}"}
         result = self._request("GET", query_url, headers=headers, stream=True)
         if result is not None:
@@ -350,7 +348,7 @@ class databrowser:
 
         Example
         ~~~~~~~
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             print(len(databrowser(experiment="cmorph")))
@@ -367,7 +365,7 @@ class databrowser:
         kwargs: Dict[str, Any] = {"stream": True}
         url = self._cfg.intake_url
         if self._stream_zarr:
-            token = self._auth.check_authentication(auth_url=self._cfg.auth_url)
+            token = self._auth.authenticate(config=self._cfg)
             url = self._cfg.zarr_loader_url
             kwargs["headers"] = {
                 "Authorization": f"Bearer {token['access_token']}"
@@ -407,7 +405,7 @@ class databrowser:
         Let's create an intake-esm catalogue that points points allows for
         streaming the target data as zarr:
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             db = databrowser(dataset="cmip6-hsm", stream_zarr=True)
@@ -435,7 +433,7 @@ class databrowser:
             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
+        kwargs: Any
             Additional keyword arguments to be passed to the request.
 
         Returns
@@ -451,7 +449,7 @@ class databrowser:
         ~~~~~~~
         Let's create a static STAC catalogue:
 
-        .. execute_code::
+        .. code-block:: python
 
             from tempfile import mktemp
             temp_path = mktemp(suffix=".zip")
@@ -521,7 +519,7 @@ class databrowser:
         Parameters
         ~~~~~~~~~~
 
-        *facets: str
+        facets: str
             If you are not sure about the correct search key's you can use
             positional arguments to search of any matching entries. For example
             'era5' would allow you to search for any entries
@@ -574,7 +572,7 @@ class databrowser:
         fail_on_error: bool, default: False
             Make the call fail if the connection to the databrowser could not
             be established.
-        **search_keys: str
+        search_keys: str
             The search constraints to be applied in the data search. If not given
             the whole dataset will be queried.
 
@@ -587,12 +585,12 @@ class databrowser:
         Example
         ~~~~~~~
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             print(databrowser.count_values(experiment="cmorph"))
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             print(databrowser.count_values("model"))
@@ -602,7 +600,7 @@ class databrowser:
         example for getting all ocean reanalysis datasets you can apply the
         'reana*' search key as a positional argument:
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             print(databrowser.count_values("reana*", realm="ocean", flavour="cmip6"))
@@ -643,7 +641,7 @@ class databrowser:
 
         Reverse search: retrieving meta data from a known file
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             db = databrowser(uri="slk:///arch/*/CPC/*")
@@ -681,7 +679,7 @@ class databrowser:
         Parameters
         ~~~~~~~~~~
 
-        *facets: str
+        facets: str
             If you are not sure about the correct search key's you can use
             positional arguments to search of any matching entries. For example
             'era5' would allow you to search for any entries
@@ -734,7 +732,7 @@ class databrowser:
         fail_on_error: bool, default: False
             Make the call fail if the connection to the databrowser could not
             be established.
-        **search_keys: str, list[str]
+        search_keys: str, list[str]
             The facets to be applied in the data search. If not given
             the whole dataset will be queried.
 
@@ -747,7 +745,7 @@ class databrowser:
         Example
         ~~~~~~~
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             all_facets = databrowser.metadata_search(project='obs*')
@@ -755,7 +753,7 @@ class databrowser:
 
         You can also search for all metadata matching a search string:
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             spec_facets = databrowser.metadata_search("obs*")
@@ -763,7 +761,7 @@ class databrowser:
 
         Get all models that have a given time step:
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             model = databrowser.metadata_search(
@@ -774,7 +772,7 @@ class databrowser:
 
         Reverse search: retrieving meta data from a known file
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             res = databrowser.metadata_search(file="/arch/*CPC/*")
@@ -785,7 +783,7 @@ class databrowser:
         example for getting all ocean reanalysis datasets you can apply the
         'reana*' search key as a positional argument:
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             print(databrowser.metadata_search("reana*", realm="ocean", flavour="cmip6"))
@@ -795,7 +793,7 @@ class databrowser:
         version from a multi versioned datasets requires the ``multiversion``
         flag in combination with the ``version`` special attribute:
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             res = databrowser.metadata_search(dataset="cmip6-fs",
@@ -852,7 +850,7 @@ class databrowser:
         Example
         ~~~~~~~
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             print(databrowser.overview())
@@ -869,7 +867,7 @@ class databrowser:
         Example
         ~~~~~~~
 
-        .. execute_code::
+        .. code-block:: python
 
             from freva_client import databrowser
             db = databrowser()
@@ -948,11 +946,10 @@ class databrowser:
 
         Adding user data:
 
-        .. execute_code::
+        .. code-block:: python
 
-            from freva_client import authenticate, databrowser
+            from freva_client import databrowser
             import xarray as xr
-            token_info = authenticate(username="janedoe")
             filenames = (
                 "../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"
@@ -971,10 +968,9 @@ class databrowser:
 
         Deleting user data:
 
-        .. execute_code::
+        .. code-block:: python
 
-            from freva_client import authenticate, databrowser
-            token_info = authenticate(username="janedoe")
+            from freva_client import databrowser
             databrowser.userdata(
                 action="delete",
                 metadata={"project": "cmip5", "experiment": "myFavExp"}
@@ -987,7 +983,7 @@ class databrowser:
         userdata_items = userdata_items or []
         metadata = metadata or {}
         url = f"{this._cfg.userdata_url}"
-        token = this._auth.check_authentication(auth_url=this._cfg.auth_url)
+        token = this._auth.authenticate(config=this._cfg)
         headers = {"Authorization": f"Bearer {token['access_token']}"}
         payload_metadata: dict[str, Collection[Collection[str]]] = {}