freva-client 2404.0.1__tar.gz → 2510.1.0__tar.gz

{freva_client-2404.0.1 → freva_client-2510.1.0}/PKG-INFO

@@ -1,11 +1,11 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: freva-client
-Version: 2404.0.1
+Version: 2510.1.0
 Summary: Search for climate data based on key-value pairs
 Author-email: "DKRZ, Clint" <freva@dkrz.de>
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -16,25 +16,28 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: appdirs
 Requires-Dist: pyyaml
 Requires-Dist: requests
+Requires-Dist: intake_esm
 Requires-Dist: rich
+Requires-Dist: setuptools
 Requires-Dist: tomli
 Requires-Dist: typer
 Requires-Dist: tox ; extra == "dev"
-Project-URL: Documentation, https://freva-clint.github.io/freva-nextgen
-Project-URL: Issues, https://github.com/FREVA-CLINT/freva-nextgen/issues
-Project-URL: Source, https://github.com/FREVA-CLINT/freva-nextgen/
+Project-URL: Documentation, https://freva-org.github.io/freva-nextgen
+Project-URL: Issues, https://github.com/freva-org/freva-nextgen/issues
+Project-URL: Source, https://github.com/freva-org/freva-nextgen/
 Provides-Extra: dev
 
 # A REST API for the freva databrowser
 
 [![License](https://img.shields.io/badge/License-BSD-purple.svg)](LICENSE)
 [![PyPI](https://img.shields.io/pypi/pyversions/freva-client.svg)](https://pypi.org/project/freva-client/)
-[![Docs](https://img.shields.io/badge/API-Doc-green.svg)](https://freva-clint.github.io/freva-nextgen)
-[![Tests](https://github.com/FREVA-CLINT/freva-nextgen/actions/workflows/ci_job.yml/badge.svg)](https://github.com/FREVA-CLINT/freva-nextgen/actions)
-[![Test-Coverage](https://codecov.io/github/FREVA-CLINT/freva-nextgen/branch/init/graph/badge.svg?token=dGhXxh7uP3)](https://codecov.io/github/FREVA-CLINT/freva-nextgen)
+[![Docs](https://img.shields.io/badge/API-Doc-green.svg)](https://freva-org.github.io/freva-nextgen)
+[![Tests](https://github.com/freva-org/freva-nextgen/actions/workflows/ci_job.yml/badge.svg)](https://github.com/freva-org/freva-nextgen/actions)
+[![Test-Coverage](https://codecov.io/github/freva-org/freva-nextgen/branch/init/graph/badge.svg?token=dGhXxh7uP3)](https://codecov.io/github/freva-org/freva-nextgen)
 
 The freva-client library is a small library that makes connections to the freva
 server. The client library currently supports the following services:

{freva_client-2404.0.1 → freva_client-2510.1.0}/README.md

@@ -2,9 +2,9 @@
 
 [![License](https://img.shields.io/badge/License-BSD-purple.svg)](LICENSE)
 [![PyPI](https://img.shields.io/pypi/pyversions/freva-client.svg)](https://pypi.org/project/freva-client/)
-[![Docs](https://img.shields.io/badge/API-Doc-green.svg)](https://freva-clint.github.io/freva-nextgen)
-[![Tests](https://github.com/FREVA-CLINT/freva-nextgen/actions/workflows/ci_job.yml/badge.svg)](https://github.com/FREVA-CLINT/freva-nextgen/actions)
-[![Test-Coverage](https://codecov.io/github/FREVA-CLINT/freva-nextgen/branch/init/graph/badge.svg?token=dGhXxh7uP3)](https://codecov.io/github/FREVA-CLINT/freva-nextgen)
+[![Docs](https://img.shields.io/badge/API-Doc-green.svg)](https://freva-org.github.io/freva-nextgen)
+[![Tests](https://github.com/freva-org/freva-nextgen/actions/workflows/ci_job.yml/badge.svg)](https://github.com/freva-org/freva-nextgen/actions)
+[![Test-Coverage](https://codecov.io/github/freva-org/freva-nextgen/branch/init/graph/badge.svg?token=dGhXxh7uP3)](https://codecov.io/github/freva-org/freva-nextgen)
 
 The freva-client library is a small library that makes connections to the freva
 server. The client library currently supports the following services:

{freva_client-2404.0.1 → freva_client-2510.1.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-2404.0.1 → freva_client-2510.1.0}/pyproject.toml

@@ -8,7 +8,7 @@ description = "Search for climate data based on key-value pairs"
 authors = [{name = "DKRZ, Clint", email = "freva@dkrz.de"}]
 readme = "README.md"
 classifiers = [
-               "Development Status :: 3 - Alpha",
+               "Development Status :: 4 - Beta",
                "Environment :: Console",
                "Intended Audience :: Developers",
                "Intended Audience :: Science/Research",
@@ -19,22 +19,25 @@ classifiers = [
                "Programming Language :: Python :: 3.10",
                "Programming Language :: Python :: 3.11",
                "Programming Language :: Python :: 3.12",
+               "Programming Language :: Python :: 3.13",
 ]
 requires-python = ">=3.8"
 dependencies = [
 "appdirs",
 "pyyaml",
 "requests",
+"intake_esm",
 "rich",
+"setuptools",
 "tomli",
 "typer",
 ]
 [project.scripts]
 freva-client = "freva_client:cli.app"
 [project.urls]
-Documentation = "https://freva-clint.github.io/freva-nextgen"
-Issues = "https://github.com/FREVA-CLINT/freva-nextgen/issues"
-Source = "https://github.com/FREVA-CLINT/freva-nextgen/"
+Documentation = "https://freva-org.github.io/freva-nextgen"
+Issues = "https://github.com/freva-org/freva-nextgen/issues"
+Source = "https://github.com/freva-org/freva-nextgen/"
 
 [project.optional-dependencies]
 dev = ["tox"]
@@ -45,4 +48,4 @@ include = ["assets/*"]
 [tool.flit.external-data]
 directory = "assets"
 [package-data]
-freva_deployment = ["py.typed"]
+freva_client = ["py.typed"]

{freva_client-2404.0.1 → freva_client-2510.1.0}/src/freva_client/__init__.py

@@ -12,9 +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__ = "2404.0.1"
-__all__ = ["databrowser", "__version__"]
+__version__ = "2510.1.0"
+__all__ = ["authenticate", "databrowser", "__version__"]

freva_client-2510.1.0/src/freva_client/auth.py

@@ -0,0 +1,248 @@
+"""Module that handles the authentication at the rest service."""
+
+import datetime
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+import requests
+
+from .utils import logger
+from .utils.auth_utils import (
+    AuthError,
+    CodeAuthClient,
+    DeviceAuthClient,
+    Token,
+    choose_token_strategy,
+    get_default_token_file,
+    is_interactive_auth_possible,
+    load_token,
+)
+from .utils.databrowser_utils import Config
+
+AUTH_FAILED_MSG = """Login failed or no valid token found in this environment.
+If you appear to be in a non-interactive or remote session create a new token
+via:
+
+   {command}
+
+Then pass the token file using:"
+
+"    {token_path} or set the $TOKEN_ENV_VAR env. variable."""
+
+
+class Auth:
+    """Helper class for authentication."""
+
+    _instance: Optional["Auth"] = None
+    _auth_token: Optional[Token] = None
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> "Auth":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self, token_file: Optional[Union[str, Path]] = None) -> None:
+        self.token_file = str(token_file or "").strip() or None
+
+    def get_token(
+        self,
+        token_url: str,
+        data: Dict[str, str],
+    ) -> Token:
+        try:
+            response = requests.post(token_url, data=data)
+            response.raise_for_status()
+        except requests.exceptions.RequestException as error:
+            raise AuthError(f"Fetching token failed: {error}")
+        auth = response.json()
+        return self.set_token(
+            access_token=auth["access_token"],
+            token_type=auth["token_type"],
+            expires=auth["expires"],
+            refresh_token=auth["refresh_token"],
+            refresh_expires=auth["refresh_expires"],
+            scope=auth["scope"],
+        )
+
+    def _login(
+        self,
+        auth_url: str,
+        _timeout: Optional[int] = 30,
+    ) -> Token:
+        device_endpoint = f"{auth_url}/device"
+        token_endpoint = f"{auth_url}/token"
+        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())))
+        )
+        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"],
+            expires=response["expires"],
+            refresh_token=response["refresh_token"],
+            refresh_expires=response["refresh_expires"],
+            scope=response["scope"],
+        )
+
+    def set_token(
+        self,
+        access_token: str,
+        refresh_token: Optional[str] = None,
+        expires_in: int = 10,
+        refresh_expires_in: int = 10,
+        expires: Optional[Union[float, int]] = None,
+        refresh_expires: Optional[Union[float, int]] = None,
+        token_type: str = "Bearer",
+        scope: str = "profile email address",
+    ) -> Token:
+        """Override the existing auth token."""
+        now = datetime.datetime.now(datetime.timezone.utc).timestamp()
+
+        self._auth_token = Token(
+            access_token=access_token or "",
+            refresh_token=refresh_token or "",
+            token_type=token_type,
+            expires=int(expires or now + expires_in),
+            refresh_expires=int(refresh_expires or now + refresh_expires_in),
+            scope=scope,
+        )
+        default_token_file = get_default_token_file()
+        for _file in map(
+            Path, set((self.token_file or default_token_file, default_token_file))
+        ):
+            _file.parent.mkdir(exist_ok=True, parents=True)
+            _file.write_text(json.dumps(self._auth_token))
+            _file.chmod(0o600)
+
+        return self._auth_token
+
+    def _refresh(
+        self, url: str, refresh_token: str, timeout: Optional[int] = 30
+    ) -> Token:
+        """Refresh the access_token with a refresh token."""
+        try:
+            return self.get_token(
+                f"{url}/token",
+                data={"refresh-token": refresh_token or ""},
+            )
+        except (AuthError, KeyError) as error:
+            logger.warning("Failed to refresh token: %s", error)
+            return self._login(url, _timeout=timeout)
+
+    def authenticate(
+        self,
+        host: Optional[str] = None,
+        config: Optional[Config] = None,
+        *,
+        force: bool = False,
+        timeout: Optional[int] = 30,
+        _cli: bool = False,
+    ) -> Token:
+        """Authenticate the user to the host."""
+        cfg = config or Config(host)
+        token = self._auth_token or load_token(self.token_file)
+        reason: Optional[str] = None
+        if force:
+            strategy = "browser_auth"
+        else:
+            strategy = choose_token_strategy(token)
+        if strategy == "use_token" and token:
+            self._auth_token = token
+            return self._auth_token
+        try:
+            if strategy == "refresh_token" and token:
+                return self._refresh(
+                    cfg.auth_url, token["refresh_token"], timeout=timeout
+                )
+            if strategy == "browser_auth":
+                return self._login(cfg.auth_url, _timeout=timeout)
+        except AuthError as error:
+            reason = str(error)
+
+        command, token_path = {
+            True: ("freva-client auth", "--token-file /path/to/token.json"),
+            False: (
+                "freva_client.auth",
+                "`token_file='/path/to/token.json'`",
+            ),
+        }[_cli]
+
+        reason = reason or AUTH_FAILED_MSG.format(
+            command=command, token_path=token_path
+        )
+        if _cli:
+            logger.critical(reason)
+            raise SystemExit(1)
+        else:
+            raise AuthError(reason)
+
+
+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.
+
+    This method generates a new access token that should be used for restricted methods.
+
+    Parameters
+    ----------
+    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
+    -------
+    Token: The authentication token.
+
+    Examples
+    --------
+    Interactive authentication:
+
+    .. code-block:: python
+
+        from freva_client import authenticate
+        token = authenticate(timeout=120)
+        print(token)
+
+    Batch mode authentication with a refresh token:
+
+    .. code-block:: python
+
+        from freva_client import authenticate
+        token = authenticate(token_file="~/.freva-login-token.json")
+    """
+    auth = Auth(token_file=token_file or None)
+    return auth.authenticate(
+        host=host,
+        force=force,
+        timeout=timeout,
+    )

freva_client-2510.1.0/src/freva_client/cli/auth_cli.py

@@ -0,0 +1,69 @@
+"""Command line interface for authentication."""
+
+import json
+import os
+from typing import Optional
+
+import typer
+
+from freva_client.auth import Auth
+from freva_client.utils import exception_handler, logger
+from freva_client.utils.auth_utils import TOKEN_ENV_VAR, get_default_token_file
+
+from .cli_utils import version_callback
+
+auth_app = typer.Typer(
+    name="auth",
+    help="Create OAuth2 access and refresh token.",
+    pretty_exceptions_short=False,
+)
+
+
+@exception_handler
+def authenticate_cli(
+    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: str = typer.Option(
+        os.getenv(TOKEN_ENV_VAR, "").strip(),
+        "--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."
+        ),
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-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,
+        "-V",
+        "--version",
+        help="Show version an exit",
+        callback=version_callback,
+    ),
+) -> None:
+    """Create OAuth2 access and refresh token."""
+    logger.set_verbosity(verbose)
+    token = Auth(token_file=token_file or get_default_token_file()).authenticate(
+        host=host,
+        force=force,
+        _cli=True,
+        timeout=timeout,
+    )
+    print(json.dumps(token, indent=3))

freva_client-2510.1.0/src/freva_client/cli/cli_app.py

@@ -0,0 +1,40 @@
+"""Freva the Free Evaluation System command line interface."""
+
+import os
+from typing import Optional
+
+import typer
+
+from freva_client.utils import logger
+
+from .auth_cli import authenticate_cli
+from .cli_utils import APP_NAME, version_callback
+from .databrowser_cli import databrowser_app
+
+if os.getenv("FREVA_NO_RICH_PANELS", "0") == "1":
+    typer.core.rich = None  # type: ignore
+
+app = typer.Typer(
+    name=APP_NAME,
+    help=__doc__,
+    add_completion=True,
+    callback=logger.set_cli,
+)
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        "-V",
+        help="Show version and exit",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """The main cli app."""
+
+
+app.add_typer(databrowser_app, name="databrowser")
+app.command(name="auth", help=authenticate_cli.__doc__)(authenticate_cli)

freva_client-2404.0.1/src/freva_client/cli/cli_utils.py → freva_client-2510.1.0/src/freva_client/cli/cli_parser.py

@@ -1,4 +1,4 @@
-"""Utilities for the command line interface."""
+"""Command line argument completion definitions."""
 
 import argparse
 import inspect
@@ -6,21 +6,8 @@ from typing import Any, Callable, Dict, List, Optional, Tuple, cast
 
 from freva_client import databrowser
 from freva_client.cli.cli_app import app
-from freva_client.utils import logger
 
-
-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
+from .cli_utils import parse_cli_args
 
 
 class Completer:
@@ -82,6 +69,8 @@ class Completer:
             time=None,
             host=None,
             time_select="flexible",
+            bbox=None,
+            bbox_select="flexible",
             multiversion=False,
             extended_search=True,
             fail_on_error=False,
@@ -103,7 +92,7 @@ class Completer:
         choices = self._get_choices()
         return {**self.choices, **choices}
 
-    def formated_print(self) -> None:
+    def formatted_print(self) -> None:
         """Print all choices to be processed by the shell completion function."""
 
         out = self.get_print(self.command_choices)

freva_client-2510.1.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)