freva-client 2508.0.0__tar.gz → 2509.0.0__tar.gz

{freva_client-2508.0.0 → freva_client-2509.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freva-client
-Version: 2508.0.0
+Version: 2509.0.0
 Summary: Search for climate data based on key-value pairs
 Author-email: "DKRZ, Clint" <freva@dkrz.de>
 Requires-Python: >=3.8

{freva_client-2508.0.0 → freva_client-2509.0.0}/assets/share/freva/freva.toml

@@ -17,3 +17,8 @@
 ## You can set a port by separating <hostname:port>
 ## for example freva.example.org:7777
 # host = ""
+
+##
+## The default flavour to use when accessing freva. You can simply list
+## the flavours you want to use and choose one as default.
+# default_flavour = "cmip6"

{freva_client-2508.0.0 → freva_client-2509.0.0}/src/freva_client/__init__.py

@@ -12,10 +12,11 @@ science community. With help of Freva researchers can:
 The code described here is currently in testing phase. The client and server
 library described in the documentation only support searching for data. If you
 need to apply data analysis plugins, please visit the
+official documentation: https://freva-org.github.io/freva-legacy
 """
 
 from .auth import authenticate
 from .query import databrowser
 
-__version__ = "2508.0.0"
+__version__ = "2509.0.0"
 __all__ = ["authenticate", "databrowser", "__version__"]

{freva_client-2508.0.0 → freva_client-2509.0.0}/src/freva_client/auth.py

@@ -5,6 +5,7 @@ import json
 import socket
 import urllib.parse
 import webbrowser
+from getpass import getuser
 from http.server import BaseHTTPRequestHandler, HTTPServer
 from pathlib import Path
 from threading import Event, Lock, Thread
@@ -113,7 +114,7 @@ class Auth:
         self,
         auth_url: str,
         force: bool = False,
-        _timeout: int = 30,
+        _timeout: Optional[int] = 30,
     ) -> Token:
         login_endpoint = f"{auth_url}/login"
         token_endpoint = f"{auth_url}/token"
@@ -121,6 +122,7 @@ class Auth:
         redirect_uri = REDIRECT_URI.format(port=port)
         params = {
             "redirect_uri": redirect_uri,
+            "offline_access": "true",
         }
         if force:
             params["prompt"] = "login"
@@ -129,11 +131,13 @@ class Auth:
         logger.info("Opening browser for login:\n%s", login_url)
         logger.info(
             "If you are using this on a remote host, you might need to "
-            "forward port %d:\n"
-            "    ssh -L %d:localhost:%d user@remotehost",
+            "increase the login timeout and forward port %d:\n"
+            "    ssh -L %d:localhost:%d %s@%s",
             port,
             port,
             port,
+            getuser(),
+            socket.gethostname(),
         )
         event = Event()
         server = start_local_server(port, event)
@@ -142,7 +146,7 @@ class Auth:
         try:
             wait_for_port("localhost", port)
             webbrowser.open(login_url)
-            success = event.wait(timeout=_timeout)
+            success = event.wait(timeout=_timeout or None)
             if not success:
                 raise TimeoutError(
                     f"Login did not complete within {_timeout} seconds. "
@@ -223,9 +227,7 @@ class Auth:
         return self._auth_token
 
     def _refresh(
-        self,
-        url: str,
-        refresh_token: str,
+        self, url: str, refresh_token: str, timeout: Optional[int] = 30
     ) -> Token:
         """Refresh the access_token with a refresh token."""
         try:
@@ -235,7 +237,7 @@ class Auth:
             )
         except (AuthError, KeyError) as error:
             logger.warning("Failed to refresh token: %s", error)
-            return self._login(url)
+            return self._login(url, _timeout=timeout)
 
     def authenticate(
         self,
@@ -243,6 +245,7 @@ class Auth:
         config: Optional[Config] = None,
         *,
         force: bool = False,
+        timeout: Optional[int] = 30,
         _cli: bool = False,
     ) -> Token:
         """Authenticate the user to the host."""
@@ -258,9 +261,11 @@ class Auth:
             return self._auth_token
         try:
             if strategy == "refresh_token" and token:
-                return self._refresh(cfg.auth_url, token["refresh_token"])
+                return self._refresh(
+                    cfg.auth_url, token["refresh_token"], timeout=timeout
+                )
             if strategy == "browser_auth":
-                return self._login(cfg.auth_url, force=force)
+                return self._login(cfg.auth_url, force=force, _timeout=timeout)
         except AuthError as error:
             reason = str(error)
 
@@ -287,6 +292,7 @@ def authenticate(
     token_file: Optional[Union[Path, str]] = None,
     host: Optional[str] = None,
     force: bool = False,
+    timeout: Optional[int] = 30,
 ) -> Token:
     """Authenticate to the host.
 
@@ -294,13 +300,15 @@ def authenticate(
 
     Parameters
     ----------
-    refresh_token: str, optional
+    token_file: str, optional
         Instead of setting a password, you can set a refresh token to refresh
         the access token. This is recommended for non-interactive environments.
     host: str, optional
         The hostname of the REST server.
     force: bool, default: False
         Force token recreation, even if current token is still valid.
+    timeout: int, default: 30
+        Set the timeout, None for indefinate.
 
     Returns
     -------
@@ -313,7 +321,7 @@ def authenticate(
     .. code-block:: python
 
         from freva_client import authenticate
-        token = authenticate()
+        token = authenticate(timeout=120)
         print(token)
 
     Batch mode authentication with a refresh token:
@@ -327,4 +335,5 @@ def authenticate(
     return auth.authenticate(
         host=host,
         force=force,
+        timeout=timeout,
     )

{freva_client-2508.0.0 → freva_client-2509.0.0}/src/freva_client/cli/auth_cli.py

@@ -44,6 +44,11 @@ def authenticate_cli(
         "-f",
         help="Force token recreation, even if current token is still valid.",
     ),
+    timeout: int = typer.Option(
+        30,
+        "--timeout",
+        help="Set the timeout for login in secdonds, 0 for indefinate",
+    ),
     verbose: int = typer.Option(0, "-v", help="Increase verbosity", count=True),
     version: Optional[bool] = typer.Option(
         False,
@@ -59,5 +64,6 @@ def authenticate_cli(
         host=host,
         force=force,
         _cli=True,
+        timeout=timeout,
     )
     print(json.dumps(token, indent=3))

freva_client-2509.0.0/src/freva_client/cli/cli_utils.py

@@ -0,0 +1,69 @@
+"""Utilities for the command line interface."""
+
+from typing import Any, Dict, List
+
+import pandas as pd
+import typer
+from rich import print as pprint
+from rich.console import Console
+from rich.table import Table
+
+from freva_client import __version__
+from freva_client.utils import logger
+
+APP_NAME: str = "freva-client"
+
+
+def version_callback(version: bool) -> None:
+    """Print the version and exit."""
+    if version:
+        pprint(f"{APP_NAME}: {__version__}")
+        raise typer.Exit()
+
+
+def parse_cli_args(cli_args: List[str]) -> Dict[str, List[str]]:
+    """Convert the cli arguments to a dictionary."""
+    logger.debug("parsing command line arguments.")
+    kwargs = {}
+    for entry in cli_args:
+        key, _, value = entry.partition("=")
+        if value and key not in kwargs:
+            kwargs[key] = [value]
+        elif value:
+            kwargs[key].append(value)
+    logger.debug(kwargs)
+    return kwargs
+
+
+def _summarize(val: Any, max_items: int = 6) -> str:
+    """Summarize values for table display, truncating long lists."""
+    n = len(val)
+    head = ", ".join(map(str, val[:max_items]))
+    if n > max_items:
+        return f"{head} … (+{n - max_items} more)"
+    return head
+
+
+def print_df(s: pd.Series, max_items: int = 6) -> None:
+    """Print a pandas Series as a rich table.
+
+    Parameters
+    ----------
+    s : pd.Series
+        The pandas Series to print.
+    max_items : int, optional
+        Maximum number of items to display for list-like values,
+        by default 6.
+    """
+    left_col: str = s.index.name or "index"
+    right_col: str = s.name or "value"
+
+    table: Table = Table(show_header=True, header_style="bold magenta")
+    table.add_column(left_col, style="cyan", no_wrap=True)
+    table.add_column(right_col, style="green")
+
+    for key, val in s.items():
+        table.add_row(str(key), _summarize(val, max_items=max_items))
+
+    console: Console = Console()
+    console.print(table)

{freva_client-2508.0.0 → freva_client-2509.0.0}/src/freva_client/cli/databrowser_cli.py

@@ -7,16 +7,21 @@ import json
 from enum import Enum
 from pathlib import Path
 from tempfile import NamedTemporaryFile
-from typing import Dict, List, Optional, Tuple, Union, cast
+from typing import Any, Dict, List, Optional, Tuple, Union, cast
 
 import typer
+import typer.models
 import xarray as xr
 
+# import pprinr from rich
+from rich import print as pprint
+
 from freva_client import databrowser
 from freva_client.auth import Auth
 from freva_client.utils import exception_handler, logger
+from freva_client.utils.auth_utils import requires_authentication
 
-from .cli_utils import parse_cli_args, version_callback
+from .cli_utils import parse_cli_args, print_df, version_callback
 
 
 class UniqKeys(str, Enum):
@@ -26,14 +31,18 @@ class UniqKeys(str, Enum):
     uri = "uri"
 
 
-class Flavours(str, Enum):
-    """Literal implementation for the cli."""
+class FlavourAction(str, Enum):
+    add = "add"
+    delete = "delete"
+    list = "list"
+
 
+class BuiltinFlavours(str, Enum):
+    """Literal implementation for the cli."""
     freva = "freva"
     cmip6 = "cmip6"
     cmip5 = "cmip5"
     cordex = "cordex"
-    nextgems = "nextgems"
     user = "user"
 
 
@@ -131,10 +140,9 @@ def metadata_search(
             " containing era5, regardless of project, product etc."
         ),
     ),
-    flavour: Flavours = typer.Option(
-        "freva",
+    flavour: Optional[str] = typer.Option(
+        None,
         "--flavour",
-        "-f",
         help=(
             "The Data Reference Syntax (DRS) standard specifying the type "
             "of climate datasets to query."
@@ -200,6 +208,16 @@ def metadata_search(
     parse_json: bool = typer.Option(
         False, "-j", "--json", help="Parse output in json format."
     ),
+    token_file: Optional[Path] = typer.Option(
+        None,
+        "--token-file",
+        "-tf",
+        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),
     version: Optional[bool] = typer.Option(
         False,
@@ -219,13 +237,15 @@ def metadata_search(
     """
     logger.set_verbosity(verbose)
     logger.debug("Search the databrowser")
+    if requires_authentication(flavour=flavour, databrowser_url=host):
+        Auth(token_file).authenticate(host=host, _cli=True)
     result = databrowser.metadata_search(
         *(facets or []),
         time=time or "",
         time_select=time_select.value,
         bbox=bbox or None,
         bbox_select=bbox_select.value,
-        flavour=flavour.value,
+        flavour=flavour,
         host=host,
         extended_search=extended_search,
         multiversion=multiversion,
@@ -233,10 +253,9 @@ def metadata_search(
         **(parse_cli_args(search_keys or [])),
     )
     if parse_json:
-        print(json.dumps(result))
+        print(result.to_json())
         return
-    for key, values in result.items():
-        print(f"{key}: {', '.join(values)}")
+    print_df(result)
 
 
 @databrowser_app.command(
@@ -270,10 +289,9 @@ def data_search(
             "based on file paths or Uniform Resource Identifiers"
         ),
     ),
-    flavour: Flavours = typer.Option(
-        "freva",
+    flavour: Optional[str] = typer.Option(
+        None,
         "--flavour",
-        "-f",
         help=(
             "The Data Reference Syntax (DRS) standard specifying the type "
             "of climate datasets to query."
@@ -361,13 +379,14 @@ def data_search(
     """
     logger.set_verbosity(verbose)
     logger.debug("Search the databrowser")
+
     result = databrowser(
         *(facets or []),
         time=time or "",
         time_select=time_select.value,
         bbox=bbox or None,
         bbox_select=bbox_select.value,
-        flavour=flavour.value,
+        flavour=flavour,
         uniq_key=uniq_key.value,
         host=host,
         fail_on_error=False,
@@ -375,7 +394,7 @@ def data_search(
         stream_zarr=zarr,
         **(parse_cli_args(search_keys or [])),
     )
-    if zarr:
+    if requires_authentication(flavour=flavour, zarr=zarr, databrowser_url=host):
         Auth(token_file).authenticate(host=host, _cli=True)
     if parse_json:
         print(json.dumps(sorted(result)))
@@ -415,10 +434,9 @@ def intake_catalogue(
             "based on file paths or Uniform Resource Identifiers"
         ),
     ),
-    flavour: Flavours = typer.Option(
-        "freva",
+    flavour: Optional[str] = typer.Option(
+        None,
         "--flavour",
-        "-f",
         help=(
             "The Data Reference Syntax (DRS) standard specifying the type "
             "of climate datasets to query."
@@ -508,7 +526,7 @@ def intake_catalogue(
 ) -> None:
     """Create an intake 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”."""
+    result (uniq_key), which can be either "file" or "uri"."""
     logger.set_verbosity(verbose)
     logger.debug("Search the databrowser")
     result = databrowser(
@@ -517,7 +535,7 @@ def intake_catalogue(
         time_select=time_select.value,
         bbox=bbox or None,
         bbox_select=bbox_select.value,
-        flavour=flavour.value,
+        flavour=flavour,
         uniq_key=uniq_key.value,
         host=host,
         fail_on_error=False,
@@ -525,7 +543,7 @@ def intake_catalogue(
         stream_zarr=zarr,
         **(parse_cli_args(search_keys or [])),
     )
-    if zarr:
+    if requires_authentication(flavour=flavour, zarr=zarr, databrowser_url=host):
         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))
@@ -564,10 +582,9 @@ def stac_catalogue(
             "based on file paths or Uniform Resource Identifiers"
         ),
     ),
-    flavour: Flavours = typer.Option(
-        "freva",
+    flavour: Optional[str] = typer.Option(
+        None,
         "--flavour",
-        "-f",
         help=(
             "The Data Reference Syntax (DRS) standard specifying the type "
             "of climate datasets to query."
@@ -619,6 +636,16 @@ def stac_catalogue(
             "the hostname is read from a config file"
         ),
     ),
+    token_file: Optional[Path] = typer.Option(
+        None,
+        "--token-file",
+        "-tf",
+        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),
     multiversion: bool = typer.Option(
         False,
@@ -654,7 +681,7 @@ def stac_catalogue(
         time_select=time_select.value,
         bbox=bbox or None,
         bbox_select=bbox_select.value,
-        flavour=flavour.value,
+        flavour=flavour,
         uniq_key=uniq_key.value,
         host=host,
         fail_on_error=False,
@@ -662,6 +689,8 @@ def stac_catalogue(
         stream_zarr=False,
         **(parse_cli_args(search_keys or [])),
     )
+    if requires_authentication(flavour=flavour, databrowser_url=host):
+        Auth(token_file).authenticate(host=host, _cli=True)
     print(result.stac_catalogue(filename=filename))
 
 
@@ -692,10 +721,9 @@ def count_values(
         "-d",
         help=("Separate the count by search facets."),
     ),
-    flavour: Flavours = typer.Option(
-        "freva",
+    flavour: Optional[str] = typer.Option(
+        None,
         "--flavour",
-        "-f",
         help=(
             "The Data Reference Syntax (DRS) standard specifying the type "
             "of climate datasets to query."
@@ -761,6 +789,16 @@ def count_values(
     parse_json: bool = typer.Option(
         False, "-j", "--json", help="Parse output in json format."
     ),
+    token_file: Optional[Path] = typer.Option(
+        None,
+        "--token-file",
+        "-tf",
+        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),
     version: Optional[bool] = typer.Option(
         False,
@@ -788,6 +826,8 @@ def count_values(
         bbox or search_kws.pop("bbox", None),
     )
     facets = facets or []
+    if requires_authentication(flavour=flavour, databrowser_url=host):
+        Auth(token_file).authenticate(host=host, _cli=True)
     if detail:
         result = databrowser.count_values(
             *facets,
@@ -795,7 +835,7 @@ def count_values(
             time_select=time_select.value,
             bbox=bbox or None,
             bbox_select=bbox_select.value,
-            flavour=flavour.value,
+            flavour=flavour,
             host=host,
             extended_search=extended_search,
             multiversion=multiversion,
@@ -810,7 +850,7 @@ def count_values(
                 time_select=time_select.value,
                 bbox=bbox or None,
                 bbox_select=bbox_select.value,
-                flavour=flavour.value,
+                flavour=flavour,
                 host=host,
                 multiversion=multiversion,
                 fail_on_error=False,
@@ -945,3 +985,163 @@ def user_data_delete(
             key, value = search_key.split("=", 1)
             search_key_dict[key] = value
     databrowser.userdata(action="delete", metadata=search_key_dict, host=host)
+
+
+flavour_app = typer.Typer(help="Manage custom flavours")
+databrowser_app.add_typer(flavour_app, name="flavour")
+
+
+@flavour_app.command("add", help="Add a new custom flavour.")
+@exception_handler
+def flavour_add(
+    name: str = typer.Argument(..., help="Name of the flavour to add"),
+    mapping: List[str] = typer.Option(
+        [],
+        "--map",
+        "-m",
+        help="Key-value mappings in the format key=value",
+    ),
+    global_: bool = typer.Option(
+        False,
+        "--global",
+        help="Make the flavour available to all users (requires admin privileges)",
+    ),
+    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."
+        ),
+    ),
+    token_file: Optional[Path] = typer.Option(
+        None,
+        "--token-file",
+        "-tf",
+        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 a new custom flavour to the databrowser.
+    This command allows user to create custom DRS (Data Reference Syntax)
+    flavours that define how search facets are mapped to different data
+    standards."""
+    logger.set_verbosity(verbose)
+    logger.debug(f"Adding flavour '{name}' with mapping {mapping} and global={global_}")
+    Auth(token_file).authenticate(host=host, _cli=True)
+    mapping_dict = {}
+    for map_item in mapping:
+        if "=" not in map_item:
+            logger.error(
+                f"Invalid mapping format: {map_item}. Expected format: key=value."
+            )
+            raise typer.Exit(code=1)
+        key, value = map_item.split("=", 1)
+        mapping_dict[key] = value
+
+    if not mapping_dict:
+        logger.error("At least one mapping must be provided using --map")
+        raise typer.Exit(code=1)
+
+    databrowser.flavour(
+        action="add",
+        name=name,
+        mapping=mapping_dict,
+        is_global=global_,
+        host=host,
+    )
+
+
+@flavour_app.command("delete", help="Delete an existing custom flavour.")
+@exception_handler
+def flavour_delete(
+    name: str = typer.Argument(..., help="Name of the flavour to delete"),
+    global_: bool = typer.Option(
+        False,
+        "--global",
+        help="Delete global flavour (requires admin privileges)",
+    ),
+    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."
+        ),
+    ),
+    token_file: Optional[Path] = typer.Option(
+        None,
+        "--token-file",
+        "-tf",
+        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 a custom flavour from the databrowser.
+    This command removes a custom flavour that was previously created.
+    You can only delete flavours that you own, unless you are an admin
+    user who can delete global flavours."""
+    logger.set_verbosity(verbose)
+    logger.debug(f"Deleting flavour '{name}'")
+    Auth(token_file).authenticate(host=host, _cli=True)
+
+    databrowser.flavour(
+        action="delete",
+        name=name,
+        is_global=global_,
+        host=host,
+    )
+
+
+@flavour_app.command("list", help="List all available custom flavours.")
+@exception_handler
+def flavour_list(
+    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."
+        ),
+    ),
+    parse_json: bool = typer.Option(
+        False, "-j", "--json", help="Parse output in json format."
+    ),
+    token_file: Optional[Path] = typer.Option(
+        None,
+        "--token-file",
+        "-tf",
+        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:
+    """List all custom flavours available to the current user.
+    This command shows both personal flavours created by the user and
+    global flavours available to all users."""
+    logger.set_verbosity(verbose)
+    logger.debug("Listing custom flavours")
+    results = cast(Dict[str, Any], databrowser.flavour(action="list", host=host))
+    flavours_json = json.dumps(results["flavours"], indent=2)
+    if parse_json:
+        print(flavours_json)
+    else:
+        pprint(f"[yellow]{results.get('Note', '')}[/yellow]")
+        print("🎨 Available Data Reference Syntax (DRS) Flavours")
+        print("=" * 55)
+        for flavour in results["flavours"]:
+            owner_icon = "🌐" if flavour['owner'] == "global" else "👤"
+            print(f"  {owner_icon} {flavour['flavour_name']} (by {flavour['owner']})")
+            print(f"    Mapping: {flavour['mapping']}")
+            print()