freva-client 2508.0.0__py3-none-any.whl → 2509.1.0__py3-none-any.whl

freva_client/utils/auth_utils.py

@@ -2,19 +2,95 @@
 
 import json
 import os
-import socket
+import random
 import sys
 import time
+import webbrowser
+from contextlib import contextmanager
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Literal, Optional, TypedDict, Union, cast
-
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterator,
+    Literal,
+    Optional,
+    TypedDict,
+    Union,
+    cast,
+)
+
+import requests
+import rich.console
+import rich.spinner
 from appdirs import user_cache_dir
+from rich.live import Live
+
+from freva_client.utils import logger
 
 TOKEN_EXPIRY_BUFFER = 60  # seconds
 TOKEN_ENV_VAR = "FREVA_TOKEN_FILE"
 
 
-class Token(TypedDict):
+BROWSER_MESSAGE = """Will attempt to open the auth url in your browser.
+
+If this doesn't work, try opening the following url:
+
+{interactive}{uri}{interactive_end}
+
+You might have to enter the this code manually {interactive}{user_code}{interactive_end}
+"""
+
+NON_INTERACTIVE_MESSAGE = """
+
+Visit the following url to authorise your session:
+
+{interactive}{uri}{interactive_end}
+
+You might have to enter the this code manually {interactive}{user_code}{interactive_end}
+
+"""
+
+
+@contextmanager
+def _clock(timeout: Optional[int] = None) -> Iterator[None]:
+    Console = rich.console.Console(
+        force_terminal=is_interactive_shell(), stderr=True
+    )
+    txt = f"- Timeout: {timeout:>3,.0f}s " if timeout else ""
+    interactive = int(Console.is_terminal)
+    if int(os.getenv("INTERACIVE_SESSION", str(interactive))):
+        spinner = rich.spinner.Spinner(
+            "moon", text=f"[b]Waiting for code {txt}... [/]"
+        )
+        live = Live(
+            spinner, console=Console, refresh_per_second=2.5, transient=True
+        )
+        try:
+            live.start()
+            yield
+        finally:
+            live.stop()
+    else:
+        yield
+
+
+class AuthError(Exception):
+    """Athentication error."""
+
+    def __init__(
+        self, message: str, detail: Optional[Dict[str, str]] = None
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.detail = detail or {}
+
+    def __str__(self) -> str:
+        return f"{self.message}: {self.detail}" if self.detail else self.message
+
+
+class Token(TypedDict, total=False):
     """Token information."""
 
     access_token: str
@@ -25,9 +101,191 @@ class Token(TypedDict):
     scope: str
 
 
-def get_default_token_file() -> Path:
+@dataclass
+class DeviceAuthClient:
+    """
+    Minimal OIDC Device Authorization Grant 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.
+
+    Notes
+    -----
+    - For a CLI UX, show both ``verification_uri_complete`` (if present) and
+      ``verification_uri`` + ``user_code`` as fallback.
+    - Polling respects ``interval`` and ``slow_down`` per RFC 8628.
+    """
+
+    device_endpoint: str
+    token_endpoint: str
+    timeout: Optional[int] = 600
+    session: requests.Session = field(default_factory=requests.Session)
+
+    # ---------- Public API ----------
+
+    def login(
+        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.
+
+        Parameters
+        ----------
+        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
+        -------
+        Token
+            The token payload. Includes a refresh token if granted and allowed.
+
+        Raises
+        ------
+        AuthError
+            If the device flow fails or times out.
+        """
+        init = self._authorize()
+
+        uri = init.get("verification_uri_complete") or init["verification_uri"]
+        user_code = init["user_code"]
+
+        Console = rich.console.Console(
+            force_terminal=is_interactive_shell(), stderr=True
+        )
+        pprint = Console.print if Console.is_terminal else print
+        interactive, interactive_end = (
+            ("[b]", "[/b]") if Console.is_terminal else ("", "")
+        )
+
+        if auto_open and init.get("verification_uri_complete"):
+            try:
+                pprint(
+                    BROWSER_MESSAGE.format(
+                        user_code=user_code,
+                        uri=uri,
+                        interactive=interactive,
+                        interactive_end=interactive_end,
+                    )
+                )
+                webbrowser.open(init["verification_uri_complete"])
+            except Exception as error:
+                logger.warning("Could not auto-open browser: %s", error)
+        else:
+            pprint(
+                NON_INTERACTIVE_MESSAGE.format(
+                    user_code=user_code,
+                    uri=uri,
+                    interactive=interactive,
+                    interactive_end=interactive_end,
+                )
+            )
+        return self._poll_for_token(
+            device_code=init["device_code"],
+            base_interval=int(init.get("interval", 5)),
+        )
+
+    # ---------- Internals ----------
+
+    def _authorize(self) -> Dict[str, Any]:
+        """Start device authorization; return the raw init payload."""
+        payload = self._post_form(self.device_endpoint)
+        # Validate essentials
+        for k in ("device_code", "user_code", "verification_uri", "expires_in"):
+            if k not in payload:
+                raise AuthError(f"Device authorization missing '{k}'")
+        return payload
+
+    def _poll_for_token(self, *, device_code: str, base_interval: int) -> Token:
+        """
+        Poll token endpoint until approved/denied/expired; return token JSON.
+
+        Raises
+        ------
+        AuthError
+            On timeout, denial, or other OAuth errors.
+        """
+        start = time.monotonic()
+        interval = max(1, base_interval)
+        with _clock(self.timeout):
+            while True:
+                sleep = interval + random.uniform(-0.2, 0.4)
+                if (
+                    self.timeout is not None
+                    and time.monotonic() - start > self.timeout
+                ):
+                    raise AuthError(
+                        "Login did not complete within the allotted time; "
+                        "approve the request in your browser and try again."
+                    )
+
+                data = {"device-code": device_code}
+                try:
+                    return cast(Token, self._post_form(self.token_endpoint, data))
+                except AuthError as error:
+                    err = (
+                        error.detail.get("error")
+                        if isinstance(error.detail, dict)
+                        else None
+                    )
+                    if err is None or "authorization_pending" in err:
+                        time.sleep(sleep)
+                    elif "slow_down" in err:
+                        interval += 5
+                        time.sleep(sleep)
+                    elif "expired_token" in err or "access_denied" in err:
+                        raise AuthError(f"Device flow failed: {err}")
+                    else:
+                        # Unknown OAuth error
+                        raise  # pragma: no cover
+
+    def _post_form(
+        self, url: str, data: Optional[Dict[str, str]] = None
+    ) -> Dict[str, Any]:
+        """POST x-www-form-urlencoded and return JSON or raise AuthError."""
+        resp = self.session.post(
+            url,
+            data=data,
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Connection": "close",
+            },
+            timeout=30,
+        )
+        if resp.status_code >= 400:
+            try:
+                payload = resp.json()
+            except Exception:
+                payload = {
+                    "error": "http_error",
+                    "error_description": resp.text[:300],
+                }
+            raise AuthError(f"{url} -> {resp.status_code}", detail=payload)
+        try:
+            return cast(Dict[str, Any], resp.json())
+        except Exception as error:
+            raise AuthError(f"Invalid JSON from {url}: {error}")
+
+
+def get_default_token_file(token_file: Optional[Union[str, Path]] = None) -> Path:
     """Get the location of the default token file."""
-    path_str = os.getenv(TOKEN_ENV_VAR, "").strip()
+    path_str = token_file or os.getenv(TOKEN_ENV_VAR, "").strip()
 
     path = Path(
         path_str or os.path.join(user_cache_dir("freva"), "auth-token.json")
@@ -223,18 +481,36 @@ def choose_token_strategy(
     return "fail"
 
 
-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 requires_authentication(
+    flavour: Optional[str],
+    zarr: bool = False,
+    databrowser_url: Optional[str] = None,
+) -> bool:
+    """Check if authentication is required.
+
+    Parameters
+    ----------
+    flavour : str or None
+        The data flavour to check.
+    zarr : bool, default: False
+        Whether the request is for zarr data.
+    databrowser_url : str or None
+        The URL of the databrowser to query for available flavours.
+        If None, the function will skip querying and assume authentication
+        is required for non-default flavours.
+    """
+    if zarr:
+        return True
+    if flavour in {"freva", "cmip6", "cmip5", "cordex", "user", None}:
+        return False
+    try:
+        response = requests.get(f"{databrowser_url}/flavours", timeout=30)
+        response.raise_for_status()
+        result = {"flavours": response.json().get("flavours", [])}
+        if "flavours" in result:
+            global_flavour_names = {f["flavour_name"] for f in result["flavours"]}
+            return flavour not in global_flavour_names
+    except Exception:
+        pass
+
+    return True

freva_client/utils/databrowser_utils.py

@@ -40,15 +40,50 @@ class Config:
         self,
         host: Optional[str] = None,
         uniq_key: Literal["file", "uri"] = "file",
-        flavour: str = "freva",
+        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)
         self.uniq_key = uniq_key
-        self._flavour = flavour
+        self.flavour = self.get_flavour(flavour)
 
-    def _read_ini(self, path: Path) -> str:
-        """Read an ini file."""
+    @cached_property
+    def validate_server(self) -> bool:
+        """Ping the databrowser to check if it is reachable."""
+        try:
+            res = requests.get(f"{self.get_api_main_url}/ping", timeout=15)
+            return res.status_code == 200
+        except Exception as e:
+            raise ValueError(
+                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"
+
+    def _read_ini(self, path: Path) -> Dict[str, str]:
+        """Read an ini file.
+
+        Parameters
+        ----------
+        path : Path
+            Path to the ini configuration file.
+        Returns
+        -------
+        Dict[str, str]
+            Dictionary with the configuration.
+        """
         ini_parser = ConfigParser(interpolation=ExtendedInterpolation())
         ini_parser.read_string(path.read_text())
         config = ini_parser["evaluation_system"]
@@ -59,41 +94,99 @@ class Config:
         port = port or config.get("databrowser.port", "")
         if port:
             host = f"{host}:{port}"
-        return f"{scheme}://{host}"
+        host = f"{scheme}://{host}"
+        flavour = config.get("databrowser.default_flavour", "")
+        return {
+            "host": host,
+            "flavour": flavour,
+        }
 
-    def _read_toml(self, path: Path) -> str:
-        """Read a new style toml config file."""
+    def _read_toml(self, path: Path) -> Dict[str, str]:
+        """Read a new style toml config file.
+
+        Parameters
+        ----------
+        path : Path
+            Path to the toml configuration file.
+        Returns
+        -------
+        Dict[str, str]
+            Dictionary with the configuration.
+        """
         try:
             config = tomli.loads(path.read_text()).get("freva", {})
-            scheme, host = self._split_url(cast(str, config["host"]))
+            scheme, host = self._split_url(cast(str, config.get("host", "")))
+            flavour = config.get("default_flavour", "")
         except (tomli.TOMLDecodeError, KeyError):
-            return ""
+            return {}
         host, _, port = host.partition(":")
         if port:
             host = f"{host}:{port}"
-        return f"{scheme}://{host}"
+        host = f"{scheme}://{host}"
+        return {
+            "host": host,
+            "flavour": flavour,
+        }
 
-    def _read_config(self, path: Path, file_type: Literal["toml", "ini"]) -> str:
-        """Read the configuration."""
+    def _read_config(
+            self, path: Path, file_type: Literal["toml", "ini"]
+    ) -> Dict[str, str]:
+        """Read the configuration.
+
+        Parameters
+        ----------
+        path : Path
+            Path to the configuration file.
+        file_type : Literal["toml", "ini"]
+            Type of the configuration file.
+        Returns
+        -------
+        Dict[str, str]
+            Dictionary with the configuration.
+        """
         data_types = {"toml": self._read_toml, "ini": self._read_ini}
         try:
             return data_types[file_type](path)
         except KeyError:
             pass
-        return ""
+        return {}
+
+    @cached_property
+    def _get_headers(self) -> Optional[Dict[str, str]]:
+        """Get the headers for requests."""
+        from freva_client.auth import Auth
+
+        from .auth_utils import load_token
+        auth = Auth()
+        token = auth._auth_token or load_token(auth.token_file)
+        if token and "access_token" in token:
+            return {"Authorization": f"Bearer {token['access_token']}"}
+        return None
 
     @cached_property
     def overview(self) -> Dict[str, Any]:
-        """Get an overview of the all databrowser flavours and search keys."""
+        """Get an overview of all databrowser flavours
+        and search keys including custom flavours."""
+        headers = self._get_headers
         try:
-            res = requests.get(f"{self.databrowser_url}/overview", timeout=15)
+            res = requests.get(
+                f"{self.databrowser_url}/overview",
+                headers=headers,
+                timeout=15
+            )
+            data = cast(Dict[str, Any], res.json())
+            if not headers:
+                data["Note"] = (
+                    "Displaying only global flavours. "
+                    "Authenticate to see custom user flavours as well."
+                )
+            return data
         except requests.exceptions.ConnectionError:
             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:
+    def _get_databrowser_params_from_config(self) -> Dict[str, str]:
         """Get the config file order."""
 
         eval_conf = self.get_dirs(user=False) / "evaluation_system.conf"
@@ -111,26 +204,20 @@ class Config:
         }
         for config_path, config_type in paths.items():
             if config_path.is_file():
-                host = self._read_config(config_path, config_type)
+                config_data = self._read_config(config_path, config_type)
+                host = config_data.get("host", "")
+                flavour = config_data.get("flavour", "")
                 if host:
-                    return host
+                    return {
+                        "host": host,
+                        "flavour": flavour
+                    }
         raise ValueError(
             "No databrowser host configured, please use a"
             " configuration defining a databrowser host or"
             " set a host name using the `host` key"
         )
 
-    @cached_property
-    def flavour(self) -> str:
-        """Get the flavour."""
-        flavours = self.overview.get("flavours", [])
-        if self._flavour not in flavours:
-            raise ValueError(
-                f"Search {self._flavour} not available, select from"
-                f" {','.join(flavours)}"
-            )
-        return self._flavour
-
     @property
     def search_url(self) -> str:
         """Define the data search endpoint."""
@@ -172,7 +259,7 @@ class Config:
 
     def get_api_url(self, url: Optional[str]) -> str:
         """Construct the databrowser url from a given hostname."""
-        url = url or self._get_databrowser_host_from_config()
+        url = url or self._get_databrowser_params_from_config().get("host", "")
         scheme, hostname = self._split_url(url)
         hostname, _, port = hostname.partition(":")
         if port:
@@ -207,7 +294,6 @@ class Config:
 
 class UserDataHandler:
     """Class for processing user data.
-
     This class is used for processing user data and extracting metadata
     from the data files.
     """

{freva_client-2508.0.0.data → freva_client-2509.1.0.data}/data/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.dist-info → freva_client-2509.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freva-client
-Version: 2508.0.0
+Version: 2509.1.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.dist-info/RECORD

@@ -0,0 +1,20 @@
+freva_client/__init__.py,sha256=m2rzqsvQ80LSRnN3aBwSfirKiSIqQb6qv6O9J_WhAOo,916
+freva_client/__main__.py,sha256=JVj12puT4o8JfhKLAggR2-NKCZa3wKwsYGi4HQ61DOQ,149
+freva_client/auth.py,sha256=_oHcMDKJjMvP7ZDNl6NK7NKelcxYW3jVpnQm8E-uvIU,7390
+freva_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+freva_client/query.py,sha256=Dm6Wy9U8ofzZd4v50Sjhl4Guh7njrClSnNNV5_7UdM0,49433
+freva_client/cli/__init__.py,sha256=NgTqBZGdozmTZtJduJUMrZj-opGw2KoT20tg6sc_xqo,149
+freva_client/cli/auth_cli.py,sha256=lM6QNcewh9Cz7DtHO4Wu6iv7GapwplyjhDRfmIlzyJ0,1950
+freva_client/cli/cli_app.py,sha256=QH6cb9XZTx8S9L0chPWOVd9Jn4GD1hd3sENAhdzmLZU,887
+freva_client/cli/cli_parser.py,sha256=EyzvTr70TBCD0mO2P3mVNtuEeEbNk2OdrhKSEHuu6NE,5101
+freva_client/cli/cli_utils.py,sha256=9h2hlBQA-D3n-JlFIC1DSuzEEv73Bpu8lXLAqZBDaYI,1946
+freva_client/cli/databrowser_cli.py,sha256=LpK6NvHWsbHVeJvOHG_su0dh9FHkLxTmY4K8P75S8A0,39397
+freva_client/utils/__init__.py,sha256=ySHn-3CZBwfZW2s0EpZ3INxUWOw1V4LOlKIxSLYr52U,1000
+freva_client/utils/auth_utils.py,sha256=H0knqoX2gvxM8hPzfIZQQZSKaT5tD1sRCSF2ddcdAzw,15058
+freva_client/utils/databrowser_utils.py,sha256=Hv39Q8Crd63l2U-lBJfppMn14BUm6ECY0ASsgP_8du8,17801
+freva_client/utils/logger.py,sha256=vjBbNb9KvyMriBPpgIoJjlQFCEj3DLqkJu8tYxfp2xI,2494
+freva_client-2509.1.0.data/data/share/freva/freva.toml,sha256=5xXWBqw0W6JyWfRMaSNnKDOGkDznx6NFaJvggh-cUPU,899
+freva_client-2509.1.0.dist-info/entry_points.txt,sha256=zGyEwHrH_kAGLsCXv00y7Qnp-WjXkUuIomHkfGMCxtA,53
+freva_client-2509.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+freva_client-2509.1.0.dist-info/METADATA,sha256=S92UfQmSmjiv_Ol1g1fy9OCPeZkoZl0n3943pN1Jyoc,2487
+freva_client-2509.1.0.dist-info/RECORD,,

freva_client-2508.0.0.dist-info/RECORD

@@ -1,20 +0,0 @@
-freva_client/__init__.py,sha256=Yh9B2N-5bZJgwcHOxXDMg5hEOgetBoU3TmbsE6IVLQk,851
-freva_client/__main__.py,sha256=JVj12puT4o8JfhKLAggR2-NKCZa3wKwsYGi4HQ61DOQ,149
-freva_client/auth.py,sha256=p1itCygbLgEaCFTPWgqoId3S9PteP1lrziULziKzPG4,10453
-freva_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-freva_client/query.py,sha256=SQx5c4lNwP7ZiP1u6uN7pbUyvdjv74s2vQ3kRAa_708,41906
-freva_client/cli/__init__.py,sha256=NgTqBZGdozmTZtJduJUMrZj-opGw2KoT20tg6sc_xqo,149
-freva_client/cli/auth_cli.py,sha256=hCgTxN930uTj5Z0NqItAyejiUI9E-1oSv_lWOVoHNUo,1780
-freva_client/cli/cli_app.py,sha256=QH6cb9XZTx8S9L0chPWOVd9Jn4GD1hd3sENAhdzmLZU,887
-freva_client/cli/cli_parser.py,sha256=EyzvTr70TBCD0mO2P3mVNtuEeEbNk2OdrhKSEHuu6NE,5101
-freva_client/cli/cli_utils.py,sha256=Ev9UxM4S1ZDbZSAGHFe5dMjVGot75w3muNKH3P80bHY,842
-freva_client/cli/databrowser_cli.py,sha256=eUd-lbSQaRyczLKQQLY_eKU3VRf6Zg5HaHMQbe2Ib5Q,32242
-freva_client/utils/__init__.py,sha256=ySHn-3CZBwfZW2s0EpZ3INxUWOw1V4LOlKIxSLYr52U,1000
-freva_client/utils/auth_utils.py,sha256=Tma8aPi32zhJ-z2o6gEe1LvpBFlkn-t__UgZONcuARY,6032
-freva_client/utils/databrowser_utils.py,sha256=X9M71mBfc8lauyLh3t1CCxhu_96Ya_NVkMNdxmWTsjE,15109
-freva_client/utils/logger.py,sha256=vjBbNb9KvyMriBPpgIoJjlQFCEj3DLqkJu8tYxfp2xI,2494
-freva_client-2508.0.0.data/data/share/freva/freva.toml,sha256=64Rh4qvWc9TaGJMXMi8tZW14FnESt5Z24y17BfD2VyM,736
-freva_client-2508.0.0.dist-info/entry_points.txt,sha256=zGyEwHrH_kAGLsCXv00y7Qnp-WjXkUuIomHkfGMCxtA,53
-freva_client-2508.0.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-freva_client-2508.0.0.dist-info/METADATA,sha256=8oAcxK-rhgUnBSSmUUsVcEJTNlzOcnWCkS91UaqhMqk,2487
-freva_client-2508.0.0.dist-info/RECORD,,