freva-client 2509.1.0__tar.gz → 2510.0.0__tar.gz

{freva_client-2509.1.0 → freva_client-2510.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freva-client
-Version: 2509.1.0
+Version: 2510.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-2509.1.0 → freva_client-2510.0.0}/src/freva_client/__init__.py

@@ -18,5 +18,5 @@ official documentation: https://freva-org.github.io/freva-legacy
 from .auth import authenticate
 from .query import databrowser
 
-__version__ = "2509.1.0"
+__version__ = "2510.0.0"
 __all__ = ["authenticate", "databrowser", "__version__"]

{freva_client-2509.1.0 → freva_client-2510.0.0}/src/freva_client/auth.py

@@ -11,6 +11,7 @@ import requests
 from .utils import logger
 from .utils.auth_utils import (
     AuthError,
+    CodeAuthClient,
     DeviceAuthClient,
     Token,
     choose_token_strategy,
@@ -72,17 +73,27 @@ class Auth:
     ) -> Token:
         device_endpoint = f"{auth_url}/device"
         token_endpoint = f"{auth_url}/token"
-        client = DeviceAuthClient(
+        device_client = DeviceAuthClient(
             device_endpoint=device_endpoint,
             token_endpoint=token_endpoint,
             timeout=_timeout,
         )
+        code_client = CodeAuthClient(
+            login_endpoint=f"{auth_url}/login",
+            token_endpoint=f"{auth_url}/token",
+            port_endpoint=f"{auth_url}/auth-ports",
+        )
+
         is_interactive_auth = int(
             os.getenv("BROWSER_SESSION", str(int(is_interactive_auth_possible())))
         )
-        response = client.login(
-            token_normalizer=self.get_token, auto_open=bool(is_interactive_auth)
-        )
+        try:
+            response = device_client.login(auto_open=bool(is_interactive_auth))
+        except AuthError as error:
+            if error.status_code == 503:
+                response = code_client.login()
+            else:
+                raise
         return self.set_token(
             access_token=response["access_token"],
             token_type=response["token_type"],

{freva_client-2509.1.0 → freva_client-2510.0.0}/src/freva_client/cli/databrowser_cli.py

@@ -33,6 +33,7 @@ class UniqKeys(str, Enum):
 
 class FlavourAction(str, Enum):
     add = "add"
+    update = "update"
     delete = "delete"
     list = "list"
 
@@ -1056,6 +1057,73 @@ def flavour_add(
     )
 
 
+@flavour_app.command("update", help="Update an existing custom flavour.")
+@exception_handler
+def flavour_update(
+    name: str = typer.Argument(..., help="Name of the flavour to update"),
+    mapping: List[str] = typer.Option(
+        [],
+        "--map",
+        "-m",
+        help="Key-value mappings to update in the format key=value",
+    ),
+    new_name: Optional[str] = typer.Option(
+        None,
+        "--new-name",
+        help="New name for the flavour (optional)",
+    ),
+    global_: bool = typer.Option(
+        False,
+        "--global",
+        help="Update 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:
+    """Update an existing custom flavour in the databrowser.
+    This command allows partial updates to flavour mappings. Only the keys
+    provided will be updated; other keys remain unchanged."""
+    logger.set_verbosity(verbose)
+    logger.debug(f"Updating flavour '{name}' with mapping {mapping}")
+    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
+
+    databrowser.flavour(
+        action="update",
+        name=name,
+        mapping=mapping_dict if mapping_dict else None,
+        new_name=new_name,
+        is_global=global_,
+        host=host,
+    )
+
+
 @flavour_app.command("delete", help="Delete an existing custom flavour.")
 @exception_handler
 def flavour_delete(

{freva_client-2509.1.0 → freva_client-2510.0.0}/src/freva_client/query.py

@@ -721,7 +721,9 @@ class databrowser:
                 for k, v in self._facet_search(extended_search=True).items()
             ], columns=["facet", "values"])
             .explode("values")
-            .groupby("facet")["values"].apply(list)
+            .groupby("facet")["values"].apply(
+                lambda x: [v for v in x if pd.notna(v)]
+            )
         )
 
     @classmethod
@@ -907,7 +909,9 @@ class databrowser:
                 ], columns=["facet", "values"]
             )
             .explode("values")
-            .groupby("facet")["values"].apply(list)
+            .groupby("facet")["values"].apply(
+                lambda x: [v for v in x if pd.notna(v)]
+            )
         )
 
     @classmethod
@@ -1104,8 +1108,9 @@ class databrowser:
     @classmethod
     def flavour(
         cls,
-        action: Literal["add", "delete", "list"],
+        action: Literal["add", "update", "delete", "list"],
         name: Optional[str] = None,
+        new_name: Optional[str] = None,
         mapping: Optional[Dict[str, str]] = None,
         is_global: bool = False,
         host: Optional[str] = None,
@@ -1168,6 +1173,18 @@ class databrowser:
                 is_global=False
             )
 
+        Updating a custom flavour:
+
+        .. code-block:: python
+
+            from freva_client import databrowser
+            databrowser.flavour(
+                action="update",
+                name="klimakataster",
+                mapping={"experiment": "Experiment"},
+                new_name="klimakataster_v2",
+                is_global=False
+            )
         Listing all custom flavours:
 
         .. code-block:: python
@@ -1210,6 +1227,29 @@ class databrowser:
                 msg = result.json().get("status", "Flavour added successfully")
                 pprint(f"[b][green] {msg} [/green][/b]")
 
+        elif action == "update":
+            token = this._auth.authenticate(config=this._cfg)
+            headers = {"Authorization": f"Bearer {token['access_token']}"}
+            if not name:
+                raise ValueError("'name' is required for update action")
+
+            payload_update: Dict[str, Any] = {
+                "is_global": is_global,
+                "mapping": mapping or {},
+            }
+            if new_name:
+                payload_update["flavour_name"] = new_name
+
+            result = this._request(
+                "PUT",
+                f"{this._cfg.databrowser_url}/flavours/{name}",
+                data=payload_update,
+                headers=headers,
+            )
+            if result is not None:
+                msg = result.json().get("status", "Flavour updated successfully")
+                pprint(f"[b][green] {msg} [/green][/b]")
+
         elif action == "delete":
             token = this._auth.authenticate(config=this._cfg)
             headers = {"Authorization": f"Bearer {token['access_token']}"}

{freva_client-2509.1.0 → freva_client-2510.0.0}/src/freva_client/utils/auth_utils.py

@@ -3,17 +3,22 @@
 import json
 import os
 import random
+import socket
 import sys
 import time
+import urllib.parse
 import webbrowser
 from contextlib import contextmanager
 from dataclasses import dataclass, field
+from getpass import getuser
+from http.server import BaseHTTPRequestHandler, HTTPServer
 from pathlib import Path
+from threading import Event, Thread
 from typing import (
     Any,
-    Callable,
     Dict,
     Iterator,
+    List,
     Literal,
     Optional,
     TypedDict,
@@ -33,6 +38,7 @@ TOKEN_EXPIRY_BUFFER = 60  # seconds
 TOKEN_ENV_VAR = "FREVA_TOKEN_FILE"
 
 
+REDIRECT_URI = "http://localhost:{port}/callback"
 BROWSER_MESSAGE = """Will attempt to open the auth url in your browser.
 
 If this doesn't work, try opening the following url:
@@ -80,11 +86,15 @@ class AuthError(Exception):
     """Athentication error."""
 
     def __init__(
-        self, message: str, detail: Optional[Dict[str, str]] = None
+        self,
+        message: str,
+        detail: Optional[Dict[str, str]] = None,
+        status_code: int = 500,
     ) -> None:
         super().__init__(message)
         self.message = message
         self.detail = detail or {}
+        self.status_code = status_code
 
     def __str__(self) -> str:
         return f"{self.message}: {self.detail}" if self.detail else self.message
@@ -101,10 +111,165 @@ class Token(TypedDict, total=False):
     scope: str
 
 
+class OAuthCallbackHandler(BaseHTTPRequestHandler):
+    def log_message(self, format: str, *args: object) -> None:
+        logger.debug(format, *args)
+
+    def do_GET(self) -> None:
+        query = urllib.parse.urlparse(self.path).query
+        params = urllib.parse.parse_qs(query)
+        if "code" in params:
+            setattr(self.server, "auth_code", params["code"][0])
+            self.send_response(200)
+            self.end_headers()
+            self.wfile.write(b"Login successful! You can close this tab.")
+        else:
+            self.send_response(400)
+            self.end_headers()
+            self.wfile.write(b"Authorization code not found.")
+
+
 @dataclass
-class DeviceAuthClient:
+class CodeAuthClient:
+    """Minimal OIDC Code Authorization Grand client.
+
+    Parameters
+    ----------
+    device_endpoint : str
+        Device endpoint URL, e.g. ``{issuer}/protocol/openid-connect/auth/device``.
+    token_endpoint : str
+        Token endpoint URL, e.g. ``{issuer}/protocol/openid-connect/token``.
+    scope : str, optional
+        Space-separated scopes; include ``offline_access`` if you need offline RTs.
+    timeout : int | None, optional
+        Overall timeout (seconds) for user approval. ``None`` waits indefinitely.
+    session : requests.Session | None, optional
+        Reusable HTTP session. A new one is created if omitted.
+
     """
-    Minimal OIDC Device Authorization Grant client.
+
+    login_endpoint: str
+    token_endpoint: str
+    port_endpoint: str
+    timeout: Optional[int] = 600
+    session: requests.Session = field(default_factory=requests.Session)
+
+    @staticmethod
+    def _start_local_server(port: int, event: Event) -> HTTPServer:
+        """Start local HTTP server to wait for a single callback."""
+        server = HTTPServer(("localhost", port), OAuthCallbackHandler)
+
+        def handle() -> None:
+            logger.info("Waiting for browser callback on port %s ...", port)
+            while not event.is_set():
+                server.handle_request()
+                if getattr(server, "auth_code", None):
+                    event.set()
+
+        thread = Thread(target=handle, daemon=True)
+        thread.start()
+        return server
+
+    def _find_free_port(self) -> int:
+        """Get a free port where we can start the test server."""
+        ports: List[int] = (
+            requests.get(self.port_endpoint).json().get("valid_ports", [])
+        )
+        for port in ports:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                try:
+                    s.bind(("localhost", port))
+                    return port
+                except (OSError, PermissionError):
+                    pass
+        raise OSError("No free ports available for login flow")
+
+    @staticmethod
+    def _wait_for_port(host: str, port: int, timeout: float = 5.0) -> None:
+        """Wait until a TCP port starts accepting connections."""
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+                sock.settimeout(0.5)
+                try:
+                    if sock.connect_ex((host, port)) == 0:
+                        return
+                except OSError:
+                    pass
+            time.sleep(0.05)
+        raise TimeoutError(
+            f"Port {port} on {host} did not open within {timeout} seconds."
+        )
+
+    def login(
+        self,
+    ) -> Token:
+        """Start the login flow."""
+        port = self._find_free_port()
+        redirect_uri = REDIRECT_URI.format(port=port)
+        params = {
+            "redirect_uri": redirect_uri,
+            "offline_access": "true",
+            "prompt": "consent",
+        }
+        query = urllib.parse.urlencode(params)
+        login_url = f"{self.login_endpoint}?{query}"
+        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 "
+            "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 = self._start_local_server(port, event)
+        code: Optional[str] = None
+        reason = "Login failed."
+        try:
+            self._wait_for_port("localhost", port)
+            webbrowser.open(login_url)
+            success = event.wait(timeout=self.timeout or None)
+            if not success:
+                raise TimeoutError(
+                    f"Login did not complete within {self.timeout} seconds. "
+                    "Possibly headless environment."
+                )
+            code = getattr(server, "auth_code", None)
+        except Exception as error:
+            logger.warning(
+                "Could not open browser automatically. %s"
+                "Please open the URL manually.",
+                error,
+            )
+            reason = str(error)
+
+        finally:
+            logger.debug("Cleaning up login state")
+            if hasattr(server, "server_close"):
+                try:
+                    server.server_close()
+                except Exception as error:
+                    logger.debug("Failed to close server cleanly: %s", error)
+        if not code:
+            raise AuthError(reason)
+        data = {
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "grant_type": "authorization_code",
+        }
+
+        response = requests.post(self.token_endpoint, data=data)
+        response.raise_for_status()
+        return cast(Token, response.json())
+
+
+@dataclass
+class DeviceAuthClient:
+    """Minimal OIDC Device Authorization Grant client.
 
     Parameters
     ----------
@@ -137,7 +302,6 @@ class DeviceAuthClient:
         self,
         *,
         auto_open: bool = True,
-        token_normalizer: Optional[Callable[[str, Dict[str, str]], Token]] = None,
     ) -> Token:
         """
         Run the full device flow and return an OIDC token payload.
@@ -146,10 +310,6 @@ class DeviceAuthClient:
         ----------
         auto_open : bool, optional
             Attempt to open ``verification_uri_complete`` in a browser.
-        token_normalizer : Callable, optional
-            If provided, called as ``token_normalizer(self.token_endpoint, data)``
-            to normalize/store tokens (e.g., your existing ``self.get_token``).
-            If omitted, the raw token JSON from the token endpoint is returned.
 
         Returns
         -------
@@ -276,7 +436,11 @@ class DeviceAuthClient:
                     "error": "http_error",
                     "error_description": resp.text[:300],
                 }
-            raise AuthError(f"{url} -> {resp.status_code}", detail=payload)
+            raise AuthError(
+                f"{url} -> {resp.status_code}",
+                detail=payload,
+                status_code=resp.status_code,
+            )
         try:
             return cast(Dict[str, Any], resp.json())
         except Exception as error:

{freva_client-2509.1.0 → freva_client-2510.0.0}/src/freva_client/utils/databrowser_utils.py

@@ -42,11 +42,18 @@ class Config:
         uniq_key: Literal["file", "uri"] = "file",
         flavour: Optional[str] = None,
     ) -> None:
-        self.databrowser_url = f"{self.get_api_url(host)}/databrowser"
-        self.auth_url = f"{self.get_api_url(host)}/auth/v2"
-        self.get_api_main_url = self.get_api_url(host)
+        config_host = host or cast(str, self._get_databrowser_param_from_config("host"))
+
+        self.databrowser_url = f"{self.get_api_url(config_host)}/databrowser"
+        self.auth_url = f"{self.get_api_url(config_host)}/auth/v2"
+        self.get_api_main_url = self.get_api_url(config_host)
         self.uniq_key = uniq_key
-        self.flavour = self.get_flavour(flavour)
+        self._flavour = (
+            flavour or self._get_databrowser_param_from_config(
+                "flavour",
+                optional=True
+            )
+        )
 
     @cached_property
     def validate_server(self) -> bool:
@@ -59,18 +66,17 @@ class Config:
                 f"Could not connect to {self.databrowser_url}: {e}"
             ) from None
 
-    def get_flavour(self, flavour: Optional[str]) -> str:
-        """Get the current flavour."""
-        if flavour:
-            return flavour
-        else:
-            try:
-                config_flavour = self._get_databrowser_params_from_config().get(
-                    "flavour", ""
-                )
-                return config_flavour or "freva"
-            except ValueError:
-                return "freva"
+    @property
+    def flavour(self) -> str:
+        """Get the flavour, using server default if not configured."""
+        if self._flavour:
+            return self._flavour
+        try:
+            flavours = self.overview.get("flavours", [])
+            self._flavour = flavours[0] if flavours else "freva"
+        except (ValueError, IndexError, KeyError):
+            self._flavour = "freva"
+        return self._flavour
 
     def _read_ini(self, path: Path) -> Dict[str, str]:
         """Read an ini file.
@@ -115,8 +121,11 @@ class Config:
         """
         try:
             config = tomli.loads(path.read_text()).get("freva", {})
-            scheme, host = self._split_url(cast(str, config.get("host", "")))
+            raw_host = cast(str, config.get("host", ""))
             flavour = config.get("default_flavour", "")
+            if not raw_host:
+                return {"host": "", "flavour": flavour}
+            scheme, host = self._split_url(raw_host)
         except (tomli.TOMLDecodeError, KeyError):
             return {}
         host, _, port = host.partition(":")
@@ -186,9 +195,10 @@ class Config:
                 f"Could not connect to {self.databrowser_url}"
             ) from None
 
-    def _get_databrowser_params_from_config(self) -> Dict[str, str]:
-        """Get the config file order."""
-
+    def _get_databrowser_param_from_config(
+            self, key: str, optional: bool = False
+    ) -> Optional[str]:
+        """Get a single config parameter following proper precedence."""
         eval_conf = self.get_dirs(user=False) / "evaluation_system.conf"
         freva_config = Path(
             os.environ.get("FREVA_CONFIG")
@@ -202,20 +212,22 @@ class Config:
                 os.environ.get("EVALUATION_SYSTEM_CONFIG_FILE") or eval_conf
             ): "ini",
         }
+
         for config_path, config_type in paths.items():
             if config_path.is_file():
                 config_data = self._read_config(config_path, config_type)
-                host = config_data.get("host", "")
-                flavour = config_data.get("flavour", "")
-                if host:
-                    return {
-                        "host": host,
-                        "flavour": flavour
-                    }
+                value = config_data.get(key, "")
+                # we cannot igonore the empty string here, because
+                # it needs to check the next config file
+                if value:
+                    return value if value else None
+        if optional:
+            return None
+
         raise ValueError(
-            "No databrowser host configured, please use a"
-            " configuration defining a databrowser host or"
-            " set a host name using the `host` key"
+            f"No databrowser {key} configured, please use a"
+            f" configuration defining a databrowser {key} or"
+            f" set a host name using the `{key}` key"
         )
 
     @property
@@ -257,9 +269,8 @@ class Config:
         scheme = scheme or "http"
         return scheme, hostname
 
-    def get_api_url(self, url: Optional[str]) -> str:
+    def get_api_url(self, url: str) -> str:
         """Construct the databrowser url from a given hostname."""
-        url = url or self._get_databrowser_params_from_config().get("host", "")
         scheme, hostname = self._split_url(url)
         hostname, _, port = hostname.partition(":")
         if port:
@@ -385,7 +396,7 @@ class UserDataHandler:
     ) -> None:
         for data in validated_userdata:
             metadata = self._get_metadata(data)
-            if isinstance(metadata, Exception) or metadata == {}:
+            if metadata == {}:
                 logger.warning("Error getting metadata: %s", metadata)
             else:
                 self.user_metadata.append(metadata)