Datasphere-API 0.0.0__py3-none-any.whl → 0.1.0__py3-none-any.whl

datasphere_api/__init__.py

@@ -0,0 +1,27 @@
+import logging
+
+from datasphere_api.auth import TokenStore
+from datasphere_api.client import DatasphereClient
+from datasphere_api.config import Browser, DatasphereConfig
+from datasphere_api.exceptions import (
+    AuthenticationFailed,
+    DatasphereException,
+    InvalidConfiguration,
+    MissingCredentials,
+    UnexpectedResponse,
+)
+
+# Library logger stays silent unless the consumer adds handlers
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "AuthenticationFailed",
+    "Browser",
+    "DatasphereClient",
+    "DatasphereConfig",
+    "DatasphereException",
+    "InvalidConfiguration",
+    "MissingCredentials",
+    "TokenStore",
+    "UnexpectedResponse",
+]

datasphere_api/auth.py

@@ -0,0 +1,273 @@
+import asyncio
+import http.server
+import json
+import logging
+import socketserver
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qs, quote, urlparse
+
+import httpx
+from platformdirs import user_data_dir
+from playwright.async_api import async_playwright
+
+from datasphere_api.config import BROWSER_MAPPING, DatasphereConfig
+from datasphere_api.exceptions import AuthenticationFailed
+
+logger = logging.getLogger(__name__)
+
+# Raw token response of the OAuth token endpoint
+type TokenDict = dict[str, Any]
+
+
+class TokenStore:
+
+    def __init__(self, path: Path | None = None):
+        """
+        Initializes the token store. The store persists the raw token
+        response of the OAuth token endpoint as a JSON file so sessions
+        can be shared between consumers of this library.
+
+        Args:
+            path (Path | None, optional): Path of the token file.
+                                          Defaults to None, which
+                                          resolves to 'session.json' in
+                                          the user data directory of
+                                          'Datasphere'.
+        """
+        if path is None:
+            path = Path(user_data_dir("Datasphere")) / "session.json"
+        self.path = path
+
+    def load(self) -> TokenDict | None:
+        """
+        Loads the cached tokens from the token file. Deletes the file if
+        it cannot be parsed.
+
+        Returns:
+            TokenDict | None: Cached tokens if the file exists and is
+                              valid, else None.
+        """
+        if not self.path.is_file():
+            return None
+        try:
+            with open(self.path, encoding="utf-8") as token_file:
+                return json.load(token_file)
+        except json.JSONDecodeError:
+            logger.warning("Token file is corrupt. Deleting file...")
+            self.delete()
+            return None
+
+    def save(self, tokens: TokenDict) -> None:
+        """
+        Saves tokens to the token file. Creates the parent directory if
+        it doesn't exist yet.
+
+        Args:
+            tokens (TokenDict): Tokens to save.
+        """
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.path, "w", encoding="utf-8") as token_file:
+            json.dump(tokens, token_file)
+
+    def delete(self) -> None:
+        """
+        Deletes the token file if it exists.
+        """
+        self.path.unlink(missing_ok=True)
+
+
+async def refresh_tokens(
+    config: DatasphereConfig,
+    session: httpx.AsyncClient,
+    refresh_token: str,
+) -> TokenDict | None:
+    """
+    Requests new tokens from the token endpoint using a refresh token.
+
+    Args:
+        config (DatasphereConfig): Configuration with the token URL and
+                                   the client credentials.
+        session (httpx.AsyncClient): Session to send the request with.
+        refresh_token (str): Refresh token of a previous login.
+
+    Returns:
+        TokenDict | None: New tokens if the refresh was successful, else
+                          None (e.g. if the refresh token has expired).
+    """
+    # Send refresh request
+    auth = httpx.BasicAuth(
+        username=config.client_id,
+        password=config.client_secret,
+    )
+    response = await session.post(
+        url=config.token_url,
+        data={
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+        },
+        auth=auth,
+    )
+
+    # Parse and validate response
+    try:
+        tokens = response.json()
+    except json.JSONDecodeError:
+        tokens = {}
+    if response.status_code != 200 or "access_token" not in tokens:
+        logger.warning(
+            "Refreshing tokens failed with status code %s.",
+            response.status_code,
+        )
+        return None
+    return tokens
+
+
+async def authenticate_interactively(
+    config: DatasphereConfig,
+    session: httpx.AsyncClient,
+) -> TokenDict:
+    """
+    Runs the interactive OAuth authorization code flow. Starts a local
+    callback server to receive the authorization code and opens a
+    Playwright browser window for the user to log in. Exchanges the
+    received code for tokens at the token endpoint.
+
+    Args:
+        config (DatasphereConfig): Configuration with the URLs, the
+                                   client credentials and the browser to
+                                   use for the login.
+        session (httpx.AsyncClient): Session to send the token request
+                                     with.
+
+    Raises:
+        AuthenticationFailed: If the login is not completed in time or
+                              the token endpoint doesn't return tokens.
+
+    Returns:
+        TokenDict: Tokens returned by the token endpoint.
+    """
+
+    class ReusableServer(socketserver.TCPServer):
+        allow_reuse_address = True  # to allow immediate reuse of the port
+
+    # Mutable container to store the callback code and access it from
+    # different threads
+    callback: dict[str, str | None] = {"code": None}
+
+    # Async handling of the callback server using an event to signal when
+    # the code is received
+    loop = asyncio.get_running_loop()
+    received = asyncio.Event()
+
+    @contextmanager
+    def callback_server(port: int) -> Iterator[dict[str, str | None]]:
+        """
+        Context manager for the callback server. Everything before the
+        yield is treated as __enter__. Everything after the yield is
+        treated as __exit__.
+
+        Args:
+            port (int): Port to listen on.
+
+        Yields:
+            dict[str, str | None]: Mapping of the callback code received
+                                   in a GET-request. The key is 'code'.
+                                   The initial value is None.
+        """
+        class Handler(http.server.BaseHTTPRequestHandler):
+            def do_GET(self):
+                """
+                Checks the query params of an incoming GET-request for a
+                'code' parameter. Assigns the value to the 'code' key in
+                the callback dict and displays a short confirmation in
+                the browser.
+                """
+                params = parse_qs(urlparse(self.path).query)
+                callback_code = params.get("code", [None])[0]
+                if callback_code:
+                    callback["code"] = callback_code
+                    self.send_response(200)
+                    self.send_header(
+                        "Content-Type",
+                        "text/html; charset=utf-8",
+                    )
+                    self.end_headers()
+                    self.wfile.write(
+                        b"<h1>Code received</h1>"
+                        b"<p>This window will be closed automatically.</p>"
+                    )
+                    loop.call_soon_threadsafe(received.set)
+
+            def log_message(self, *args, **kwargs):
+                """
+                Overrides the default logs to hide output to the console.
+                """
+                return
+
+        # Starts server in separate thread to not block the main thread
+        with ReusableServer(("localhost", port), Handler) as server:
+            thread = threading.Thread(
+                target=server.serve_forever,
+                daemon=True,
+            )
+            thread.start()
+            try:
+                yield callback
+            finally:
+                server.shutdown()
+                thread.join(timeout=3)
+
+    # Start callback server and open Playwright browser for authentication
+    port = urlparse(config.redirect_uri).port or 80
+    with callback_server(port):
+        async with async_playwright() as p:
+            browser = await p.chromium.launch(
+                channel=BROWSER_MAPPING[config.browser],
+                headless=False,
+            )
+            page = await browser.new_page()
+            await page.goto(
+                f"{config.authorization_url}"
+                f"?response_type=code"
+                f"&client_id={quote(config.client_id)}"
+                f"&redirect_uri={quote(config.redirect_uri)}"
+            )
+
+            # Wait about 2 minutes for the user to complete the login
+            try:
+                await asyncio.wait_for(received.wait(), timeout=120)
+            except TimeoutError:
+                raise AuthenticationFailed(
+                    "Timed out waiting for the login to complete."
+                ) from None
+
+    # Send callback code to token endpoint to receive access tokens
+    auth = httpx.BasicAuth(
+        username=config.client_id,
+        password=config.client_secret,
+    )
+    response = await session.post(
+        url=config.token_url,
+        data={
+            "grant_type": "authorization_code",
+            "code": callback["code"],
+            "redirect_uri": config.redirect_uri,
+        },
+        auth=auth,
+    )
+
+    # Parse and validate response
+    try:
+        tokens = response.json()
+    except json.JSONDecodeError:
+        tokens = {}
+    if "access_token" not in tokens:
+        raise AuthenticationFailed(
+            f"Token endpoint returned an unexpected response "
+            f"[{response.status_code}]: {response.text}"
+        )
+    return tokens

datasphere_api/client.py

@@ -0,0 +1,219 @@
+import asyncio
+import logging
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING
+
+import httpx
+
+from datasphere_api.auth import (
+    TokenStore,
+    authenticate_interactively,
+    refresh_tokens,
+)
+from datasphere_api.config import BROWSER_MAPPING, DatasphereConfig
+from datasphere_api.exceptions import (
+    InvalidConfiguration,
+    MissingCredentials,
+)
+
+if TYPE_CHECKING:
+    from datasphere_api.resources.analytical_models import AnalyticalModels
+    from datasphere_api.resources.remote_tables import RemoteTables
+    from datasphere_api.resources.task_chains import TaskChains
+    from datasphere_api.resources.views import Views
+
+logger = logging.getLogger(__name__)
+
+
+class DatasphereClient:
+
+    def __init__(self, config: DatasphereConfig):
+        """
+        Initializes the client and its httpx session. Doesn't perform any
+        file or network I/O.
+
+        Args:
+            config (DatasphereConfig): Configuration with the URLs and
+                                       credentials of the tenant.
+
+        Raises:
+            MissingCredentials: If no client secret is configured.
+            InvalidConfiguration: If an unsupported browser is configured.
+        """
+        # Validate configuration
+        if not config.client_secret:
+            raise MissingCredentials()
+        if config.browser not in BROWSER_MAPPING:
+            raise InvalidConfiguration(
+                f"Unsupported browser '{config.browser}'. Supported "
+                f"browsers are: {', '.join(BROWSER_MAPPING)}."
+            )
+
+        # Initialize session and token store
+        self.config = config
+        self.session: httpx.AsyncClient = httpx.AsyncClient(
+            timeout=config.timeout,
+            follow_redirects=True,
+        )
+        self.token_store = TokenStore(config.session_file)
+
+        # Lazily created resource instances
+        self._analytical_models: AnalyticalModels | None = None
+        self._remote_tables: RemoteTables | None = None
+        self._task_chains: TaskChains | None = None
+        self._views: Views | None = None
+
+    async def login(self) -> None:
+        """
+        Authenticates the session against the Datasphere tenant. Refreshes
+        cached tokens from the token store if they exist. Falls back to
+        the interactive browser login if no tokens are cached or the
+        refresh fails.
+
+        Raises:
+            AuthenticationFailed: If the interactive login fails.
+        """
+        # Set default headers
+        self.session.headers.update(
+            {
+                "User-Agent": (
+                    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/"
+                    "537.36 (KHTML, like Gecko) Chrome/138.0.0.0 "
+                    "Safari/537.36 Edg/138.0.0.0"
+                ),
+                "Accept": "text/plain, */*; q=0.01",
+                "Accept-Encoding": "gzip, deflate, zstd",
+                "Accept-Language": "en",
+            }
+        )
+
+        # Try to refresh cached tokens
+        tokens = self.token_store.load()
+        if tokens is not None and "refresh_token" in tokens:
+            logger.info("Loading session tokens...")
+            new_tokens = await refresh_tokens(
+                config=self.config,
+                session=self.session,
+                refresh_token=tokens["refresh_token"],
+            )
+            if new_tokens is not None:
+                self._apply_tokens(new_tokens)
+                return
+            logger.warning("Starting a new login...")
+            self.token_store.delete()
+        else:
+            logger.debug("No session tokens found.")
+
+        # Start interactive login
+        logger.debug("Opening browser window to log in...")
+        tokens = await authenticate_interactively(
+            config=self.config,
+            session=self.session,
+        )
+        self._apply_tokens(tokens)
+
+    def _apply_tokens(self, tokens: dict) -> None:
+        """
+        Adds the access token to the session headers and persists the
+        tokens in the token store.
+
+        Args:
+            tokens (dict): Tokens returned by the token endpoint.
+        """
+        self.session.headers.update(
+            {"Authorization": f"Bearer {tokens['access_token']}"}
+        )
+        self.token_store.save(tokens)
+
+    async def aclose(self) -> None:
+        """
+        Closes the underlying httpx session.
+        """
+        await self.session.aclose()
+
+    async def run_async_tasks(
+        self,
+        items: Iterable,
+        function: Callable,
+        thread_count: int = 1,
+    ) -> None:
+        """
+        Executes the given function. 'Parallelizes' the tasks if the
+        thread count is greater than 1.
+
+        Args:
+            items (Iterable): List of all arguments to be passed to the
+                              function.
+            function (Callable): Function to be executed.
+            thread_count (int, optional): Amount of concurrent
+                                          asynchronous tasks.
+                                          Default is 1.
+        """
+        if thread_count > 1:
+            semaphore = asyncio.Semaphore(thread_count)
+            tasks = []
+            for item in items:
+
+                async def process_item(item):
+                    async with semaphore:
+                        if isinstance(item, list | tuple):
+                            await function(*item)
+                        else:
+                            await function(item)
+
+                task = asyncio.create_task(process_item(item))
+                tasks.append(task)
+            await asyncio.gather(*tasks)
+
+        else:
+            for item in items:
+                if isinstance(item, list | tuple):
+                    await function(*item)
+                else:
+                    await function(item)
+
+    @property
+    def analytical_models(self) -> "AnalyticalModels":
+        """
+        Returns:
+            AnalyticalModels: Resource for the analytical model APIs.
+        """
+        if self._analytical_models is None:
+            from datasphere_api.resources.analytical_models import (
+                AnalyticalModels,
+            )
+            self._analytical_models = AnalyticalModels(self)
+        return self._analytical_models
+
+    @property
+    def remote_tables(self) -> "RemoteTables":
+        """
+        Returns:
+            RemoteTables: Resource for the remote table APIs.
+        """
+        if self._remote_tables is None:
+            from datasphere_api.resources.remote_tables import RemoteTables
+            self._remote_tables = RemoteTables(self)
+        return self._remote_tables
+
+    @property
+    def task_chains(self) -> "TaskChains":
+        """
+        Returns:
+            TaskChains: Resource for the task chain APIs.
+        """
+        if self._task_chains is None:
+            from datasphere_api.resources.task_chains import TaskChains
+            self._task_chains = TaskChains(self)
+        return self._task_chains
+
+    @property
+    def views(self) -> "Views":
+        """
+        Returns:
+            Views: Resource for the view APIs.
+        """
+        if self._views is None:
+            from datasphere_api.resources.views import Views
+            self._views = Views(self)
+        return self._views

datasphere_api/config.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+# Browsers supported for the interactive OAuth login
+type Browser = Literal["CHROME", "EDGE"]
+
+# Mapping of browser names to Playwright channel identifiers
+BROWSER_MAPPING: dict[str, str] = {
+    "CHROME": "chrome",
+    "EDGE": "msedge",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class DatasphereConfig:
+    """
+    Configuration for the Datasphere client. All URLs and credentials can
+    be found in the SAP Datasphere tenant under
+    System > Administration > App Integration.
+
+    Args:
+        base_url (str): URL of the SAP Datasphere tenant.
+        authorization_url (str): OAuth authorization URL of the tenant.
+        token_url (str): OAuth token URL of the tenant.
+        client_id (str): OAuth client ID of an "Interactive Usage" client.
+        client_secret (str): OAuth client secret of the client.
+        browser (Browser, optional): Browser to use for the interactive
+                                     login. Has to be installed on the
+                                     system. Defaults to "CHROME".
+        session_file (Path | None, optional): Path of the file used to
+                                              cache the OAuth tokens.
+                                              Defaults to None, which
+                                              resolves to 'session.json'
+                                              in the user data directory
+                                              of 'Datasphere'.
+        redirect_uri (str, optional): Redirect URI configured for the
+                                      OAuth client. Defaults to
+                                      "http://localhost:8080".
+        timeout (float, optional): Timeout for HTTP requests in seconds.
+                                   Defaults to 60 seconds.
+    """
+
+    base_url: str
+    authorization_url: str
+    token_url: str
+    client_id: str
+    client_secret: str
+    browser: Browser = "CHROME"
+    session_file: Path | None = None
+    redirect_uri: str = "http://localhost:8080"
+    timeout: float = 60.0

datasphere_api/exceptions.py

@@ -0,0 +1,22 @@
+class DatasphereException(Exception):
+    """Common base class for all exceptions raised by this library."""
+
+
+class AuthenticationFailed(DatasphereException):
+    pass
+
+
+class InvalidConfiguration(DatasphereException):
+    pass
+
+
+class MissingCredentials(DatasphereException):
+    def __init__(self) -> None:
+        super().__init__(
+            "Client secret not found. Please provide a client secret in "
+            "the configuration."
+        )
+
+
+class UnexpectedResponse(DatasphereException):
+    pass