freva-client 2404.0.0__tar.gz → 2408.0.0.dev1__tar.gz

{freva_client-2404.0.0 → freva_client-2408.0.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: freva-client
-Version: 2404.0.0
+Version: 2408.0.0.dev1
 Summary: Search for climate data based on key-value pairs
 Author-email: "DKRZ, Clint" <freva@dkrz.de>
 Requires-Python: >=3.8
@@ -18,7 +18,9 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: appdirs
 Requires-Dist: pyyaml
+Requires-Dist: authlib
 Requires-Dist: requests
+Requires-Dist: intake_esm
 Requires-Dist: rich
 Requires-Dist: tomli
 Requires-Dist: typer
@@ -31,7 +33,7 @@ Provides-Extra: dev
 # A REST API for the freva databrowser
 
 [![License](https://img.shields.io/badge/License-BSD-purple.svg)](LICENSE)
-[![Python](https://img.shields.io/badge/python-3.12-red.svg)](https://www.python.org/downloads/release/python-312/)
+[![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)

{freva_client-2404.0.0 → freva_client-2408.0.0.dev1}/README.md

@@ -1,7 +1,7 @@
 # A REST API for the freva databrowser
 
 [![License](https://img.shields.io/badge/License-BSD-purple.svg)](LICENSE)
-[![Python](https://img.shields.io/badge/python-3.12-red.svg)](https://www.python.org/downloads/release/python-312/)
+[![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)

{freva_client-2404.0.0 → freva_client-2408.0.0.dev1}/pyproject.toml

@@ -24,7 +24,9 @@ requires-python = ">=3.8"
 dependencies = [
 "appdirs",
 "pyyaml",
+"authlib",
 "requests",
+"intake_esm",
 "rich",
 "tomli",
 "typer",

{freva_client-2404.0.0 → freva_client-2408.0.0.dev1}/src/freva_client/__init__.py

@@ -14,7 +14,8 @@ library described in the documentation only support searching for data. If you
 need to apply data analysis plugins, please visit the
 """
 
+from .auth import authenticate
 from .query import databrowser
 
-__version__ = "2404.0.0"
-__all__ = ["databrowser", "__version__"]
+__version__ = "2408.0.0.dev1"
+__all__ = ["authenticate", "databrowser", "__version__"]

freva_client-2408.0.0.dev1/src/freva_client/auth.py

@@ -0,0 +1,197 @@
+"""Module that handles the authentication at the rest service."""
+
+from datetime import datetime
+from getpass import getpass, getuser
+from typing import Optional, TypedDict
+
+from authlib.integrations.requests_client import OAuth2Session
+
+from .utils import logger
+from .utils.databrowser_utils import Config
+
+Token = TypedDict(
+    "Token",
+    {
+        "access_token": str,
+        "token_type": str,
+        "expires": float,
+        "refresh_token": str,
+        "refresh_expires": float,
+    },
+)
+
+
+class Auth:
+    """Helper class for authentication."""
+
+    _instance: Optional["Auth"] = None
+    _auth_token: Optional[Token] = None
+
+    def __new__(cls) -> "Auth":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self) -> None:
+        self._auth_cls = OAuth2Session()
+
+    @property
+    def token_expiration_time(self) -> datetime:
+        """Get the expiration time of an access token."""
+        if self._auth_token is None:
+            exp = 0.0
+        else:
+            exp = self._auth_token["expires"]
+        return datetime.fromtimestamp(exp)
+
+    def set_token(
+        self,
+        access_token: str,
+        refresh_token: Optional[str] = None,
+        expires_in: int = 10,
+        refresh_expires_in: int = 10,
+        expires: Optional[float] = None,
+        refresh_expires: Optional[float] = None,
+        token_type: str = "Bearer",
+    ) -> Token:
+        """Override the existing auth token."""
+        now = datetime.now().timestamp()
+
+        self._auth_token = Token(
+            access_token=access_token or "",
+            refresh_token=refresh_token or "",
+            token_type=token_type,
+            expires=expires or now + expires_in,
+            refresh_expires=refresh_expires or now + refresh_expires_in,
+        )
+        return self._auth_token
+
+    def _refresh(
+        self, url: str, refresh_token: str, username: Optional[str] = None
+    ) -> Token:
+        """Refresh the access_token with a refresh token."""
+        auth = self._auth_cls.refresh_token(f"{url}/token", refresh_token or " ")
+        try:
+            return self.set_token(
+                access_token=auth["access_token"],
+                token_type=auth["token_type"],
+                expires_in=auth["expires_in"],
+                refresh_token=auth["refresh_token"],
+                refresh_expires_in=auth["refresh_expires_in"],
+            )
+        except KeyError:
+            logger.warning("Failed to refresh token: %s", auth.get("detail", ""))
+            if username:
+                return self._login_with_password(url, username)
+            raise ValueError("Could not use refresh token") from None
+
+    def check_authentication(self, auth_url: Optional[str] = None) -> Token:
+        """Check the status of the authentication.
+
+        Raises
+        ------
+        ValueError: If user isn't or is no longer authenticated.
+        """
+        if not self._auth_token:
+            raise ValueError("You must authenticate first.")
+        now = datetime.now().timestamp()
+        if now > self._auth_token["refresh_expires"]:
+            raise ValueError("Refresh token has expired.")
+        if now > self._auth_token["expires"] and auth_url:
+            self._refresh(auth_url, self._auth_token["refresh_token"])
+        return self._auth_token
+
+    def _login_with_password(self, auth_url: str, username: str) -> Token:
+        """Create a new token."""
+        pw_msg = "Give password for server authentication: "
+        auth = self._auth_cls.fetch_token(
+            f"{auth_url}/token", username=username, password=getpass(pw_msg)
+        )
+        try:
+            return self.set_token(
+                access_token=auth["access_token"],
+                token_type=auth["token_type"],
+                expires_in=auth["expires_in"],
+                refresh_token=auth["refresh_token"],
+                refresh_expires_in=auth["refresh_expires_in"],
+            )
+        except KeyError:
+            logger.error("Failed to authenticate: %s", auth.get("detail", ""))
+            raise ValueError("Token creation failed") from None
+
+    def authenticate(
+        self,
+        host: Optional[str] = None,
+        refresh_token: Optional[str] = None,
+        username: Optional[str] = None,
+        force: bool = False,
+    ) -> Token:
+        """Authenticate the user to the host."""
+        cfg = Config(host)
+        if refresh_token:
+            try:
+                return self._refresh(cfg.auth_url, refresh_token)
+            except ValueError:
+                logger.warning(
+                    (
+                        "Could not use refresh token, falling back "
+                        "to username/password"
+                    )
+                )
+        username = username or getuser()
+        if self._auth_token is None or force:
+            return self._login_with_password(cfg.auth_url, username)
+        if self.token_expiration_time < datetime.now():
+            self._refresh(cfg.auth_url, self._auth_token["refresh_token"], username)
+        return self._auth_token
+
+
+def authenticate(
+    *,
+    refresh_token: Optional[str] = None,
+    username: Optional[str] = None,
+    host: Optional[str] = None,
+    force: bool = False,
+) -> Token:
+    """Authenticate to the host.
+
+    This method generates a new access token that should be used for restricted methods.
+
+    Parameters
+    ----------
+    refresh_token: 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.
+    username: str, optional
+        The username used for authentication. By default, the current
+        system username is used.
+    host: str, optional
+        The hostname of the REST server.
+    force: bool, default: False
+        Force token recreation, even if current token is still valid.
+
+    Returns
+    -------
+    Token: The authentication token.
+
+    Examples
+    --------
+    Interactive authentication:
+
+    .. code-block:: python
+
+        from freva_client import authenticate
+        token = authenticate(username="janedoe")
+        print(token)
+
+    Batch mode authentication with a refresh token:
+
+    .. code-block:: python
+
+        from freva_client import authenticate
+        token = authenticate(refresh_token="MYTOKEN")
+    """
+    auth = Auth()
+    return auth.authenticate(
+        host=host, username=username, refresh_token=refresh_token, force=force
+    )

freva_client-2408.0.0.dev1/src/freva_client/cli/auth_cli.py

@@ -0,0 +1,71 @@
+"""Command line interface for authentication."""
+
+import json
+from getpass import getuser
+from typing import Optional
+
+import typer
+from freva_client import authenticate
+from freva_client.utils import exception_handler, logger
+
+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"
+        ),
+    ),
+    username: str = typer.Option(
+        getuser(),
+        "--username",
+        "-u",
+        help="The username used for authentication.",
+    ),
+    refresh_token: Optional[str] = typer.Option(
+        None,
+        "--refresh-token",
+        "-r",
+        help=(
+            "Instead of using a password, you can use a refresh token. "
+            "refresh the access token. This is recommended for non-interactive"
+            " environments."
+        ),
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Force token recreation, even if current token is still valid.",
+    ),
+    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_data = authenticate(
+        host=host,
+        username=username,
+        refresh_token=refresh_token,
+        force=force,
+    )
+    print(json.dumps(token_data, indent=3))

freva_client-2408.0.0.dev1/src/freva_client/cli/cli_app.py

@@ -0,0 +1,35 @@
+"""Freva the Free Evaluation System command line interface."""
+
+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
+
+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.0/src/freva_client/cli/cli_utils.py → freva_client-2408.0.0.dev1/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:
@@ -103,7 +90,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-2408.0.0.dev1/src/freva_client/cli/cli_utils.py

@@ -0,0 +1,31 @@
+"""Utilities for the command line interface."""
+
+from typing import Dict, List
+
+import typer
+from freva_client import __version__
+from freva_client.utils import logger
+from rich import print as pprint
+
+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