deeporigin-sdk 4.7.0__py3-none-any.whl

deeporigin_sdk/VERSION

@@ -0,0 +1 @@
+4.7.0

deeporigin_sdk/__init__.py

@@ -0,0 +1,49 @@
+import os
+import pathlib
+from pathlib import Path
+import subprocess
+
+from deeporigin_sdk.exceptions import DeepOriginException
+
+__all__ = ["__version__", "DeepOriginException"]
+
+SRC_DIR = pathlib.Path(__file__).parent
+
+version_filename = os.path.join(SRC_DIR, "VERSION")
+
+
+def _get_pep440_version():
+    """get a pep440-compliant local version number"""
+    result = subprocess.run(
+        ["git", "describe", "--tags", "--dirty", "--long"],
+        capture_output=True,
+        universal_newlines=True,
+        cwd=Path(__file__).parent.parent,
+    )
+    describe_str = result.stdout.strip()
+
+    # Parse the git describe output
+    tag, commits, commit_hash_dirty = describe_str.rsplit("-", 2)
+    commit_hash, dirty = (commit_hash_dirty.split("-") + [""])[:2]
+
+    # Format to PEP 440
+    if dirty:
+        local_version = f"+{commits}.g{commit_hash}.dirty"
+    else:
+        local_version = f"+{commits}.g{commit_hash}"
+
+    pep440_version = f"{tag}{local_version}"
+
+    return pep440_version
+
+
+with open(version_filename, "r") as file:
+    __version__ = file.read().strip()
+
+    if __version__ == "0.0.0.dev0":
+        # in dev mode. we use git to get a "version number"
+        # that will change with tags and commits, if possible
+        try:
+            __version__ = _get_pep440_version()
+        except Exception:
+            pass

deeporigin_sdk/auth.py

@@ -0,0 +1,290 @@
+"""this module handles authentication actions and interactions
+with tokens"""
+
+import json
+import os
+from pathlib import Path
+import time
+
+from beartype import beartype
+import httpx
+import jwt
+
+from deeporigin_sdk.config import get_value as get_config
+from deeporigin_sdk.exceptions import DeepOriginException
+from deeporigin_sdk.utils.constants import ENV_VARIABLES, ENVS
+from deeporigin_sdk.utils.core import (
+    _ensure_do_folder,
+    _supports_unicode_output,
+)
+
+__all__ = [
+    "get_token",
+    "save_token",
+]
+
+AUTH_DOMAIN = {
+    "dev": "https://login.dev.deeporigin.io",
+    "prod": "https://login.deeporigin.io",
+    "staging": "https://login.staging.deeporigin.io",
+}
+
+
+@beartype
+def _get_api_tokens_filepath() -> Path:
+    """get location of the api tokens file"""
+
+    return _ensure_do_folder() / "api_tokens.json"
+
+
+@beartype
+def read_cached_token(*, env: ENVS | None = None) -> str | None:
+    """Read cached API access token for a specific environment.
+
+    Args:
+        env: Environment name (e.g., 'prod', 'staging', 'edge').
+            If None, reads from config.
+
+    Returns:
+        Access token string for the specified environment.
+        Returns None if token does not exist for that environment.
+    """
+    if env is None:
+        env = get_config()["env"]
+
+    filepath = _get_api_tokens_filepath()
+
+    if not filepath.exists():
+        return None
+
+    with open(filepath, "r") as file:
+        all_tokens = json.load(file)
+
+    # Return access token for the specific environment
+    return all_tokens.get(env)
+
+
+@beartype
+def tokens_exist(*, env: ENVS | None = None) -> bool:
+    """Check if cached API token exist for a specific environment.
+
+    Args:
+        env: Environment name. If None, checks for current config environment.
+
+    Returns:
+        True if token exists for the environment, False otherwise.
+    """
+    if env is None:
+        env = get_config()["env"]
+
+    filepath = _get_api_tokens_filepath()
+
+    if not filepath.exists():
+        return False
+
+    with open(filepath, "r") as file:
+        all_tokens = json.load(file)
+
+    return bool(env in all_tokens and all_tokens[env])
+
+
+@beartype
+def get_token(*, env: ENVS | None = None) -> str:
+    """Get access token for accessing the Deep Origin API
+
+    Gets token to access Deep Origin API.
+
+
+    If an access token exists in the ENV, then it is used before
+    anything else. If not, then the tokens file is
+    checked for access token, and used if they exist.
+
+    Args:
+        env: Environment name. If None, uses current config environment.
+
+    Returns:
+        API access token string
+    """
+    if env is None:
+        env = get_config()["env"]
+
+    token = None
+
+    # Try to read from disk first
+    if tokens_exist(env=env):
+        token = read_cached_token(env=env)
+
+    # tokens in env override tokens on disk
+    if ENV_VARIABLES["access_token"] in os.environ:
+        token = os.environ[ENV_VARIABLES["access_token"]]
+
+    if not token:
+        raise DeepOriginException(
+            "No access token found. Failed to get a token from the environment or disk."
+        )
+
+    # check if the access token is expired
+    if is_token_expired(token):
+        raise DeepOriginException(
+            title="Token Expired",
+            message="Token is expired. Please refer to https://client-docs.deeporigin.io/how-to/auth.html to get a new token.",
+            level="danger",
+        )
+
+    return token
+
+
+@beartype
+def token_to_env(token: str) -> ENVS:
+    """Determine the environment from a token's issuer.
+
+    Args:
+        token: Access token string.
+
+    Returns:
+        Environment name ('dev', 'staging', or 'prod').
+    """
+    decoded_token = decode_access_token(token)
+    if "dev" in decoded_token["iss"]:
+        return "dev"
+    elif "staging" in decoded_token["iss"]:
+        return "staging"
+    elif "local" in decoded_token["iss"]:
+        return "local"
+    else:
+        return "prod"
+
+
+@beartype
+def save_token(token: str) -> None:
+    """Save a long-lived token from the UI to disk.
+
+    This function validates and saves a long-lived token obtained from the
+    Deep Origin UI. The token will be stored in the api_tokens.json file
+    and used by get_token() and client initialization.
+
+    Args:
+        token: Long-lived token string obtained from the UI.
+
+
+    Raises:
+        DeepOriginException: If token is invalid or cannot be decoded.
+    """
+
+    env = token_to_env(token)
+    decoded_token = decode_access_token(token)
+
+    # Save tokens to disk
+    filepath = _get_api_tokens_filepath()
+
+    # Load existing tokens for all environments
+    all_tokens = {}
+    if filepath.exists():
+        with open(filepath, "r") as file:
+            all_tokens = json.load(file)
+
+    # Update tokens for the specific environment
+    all_tokens[env] = token
+
+    # Write back all environments
+    with open(filepath, "w") as file:
+        json.dump(all_tokens, file, indent=2)
+
+    name = decoded_token.get("name", "Unknown User")
+
+    # Print confirmation
+    if _supports_unicode_output():
+        check = "✔︎"
+    else:
+        check = "OK"
+    print(
+        f"{check} Long-lived token for {name} saved successfully for environment '{env}'"
+    )
+
+
+@beartype
+def is_token_expired(token: str) -> bool:
+    """
+    Check if the JWT token is expired. The token is expected to have an 'exp' field as a Unix timestamp.
+
+    Args:
+        token: The JWT token string to check.
+
+    Returns:
+        bool: True if the token is expired, False otherwise.
+    """
+    decoded_token = decode_access_token(token)
+    # Get the expiration time from the token, defaulting to 0 if not found.
+    exp_time = decoded_token.get("exp", 0)
+    current_time = time.time()  # Get current time in seconds since the epoch.
+
+    # If current time is greater than the expiration time, it's expired.
+    return current_time > exp_time
+
+
+@beartype
+def decode_access_token(token: str) -> dict:
+    """decode access token into human readable data"""
+
+    # Get the JWT header
+    header = jwt.get_unverified_header(token)
+
+    # Decode the JWT using the public key
+    return jwt.decode(
+        token, algorithms=header["alg"], options={"verify_signature": False}
+    )
+
+
+@beartype
+def _get_keycloak_token(
+    *,
+    email: str,
+    password: str,
+    realm: str = "deeporigin",
+    base_url: str = "https://login.dev.deeporigin.io",
+    scope: str = "openid email super-user",
+) -> dict:
+    """get a token, with optional super user scope from keycloak
+
+    This returns a super-user token (if possible) from keycloak. Do not use this function.
+
+    Args:
+        email: the email of the super user
+        password: the password of the super user
+        realm: the realm to get the token from
+        base_url: the base url of the keycloak instance
+        scope: the scope of the token
+
+    Raises:
+        DeepOriginException: If email or password is empty or not a string.
+    """
+    # Validate input parameters
+    if not email.strip():
+        raise DeepOriginException(
+            title="Invalid email parameter",
+            message="Email must be a non-empty string.",
+        )
+    if not password.strip():
+        raise DeepOriginException(
+            title="Invalid password parameter",
+            message="Password must be a non-empty string.",
+        )
+
+    keycloak_url = f"{base_url}/realms/{realm}/protocol/openid-connect/token"
+
+    data = {
+        "grant_type": "password",
+        "username": email,
+        "password": password,
+        "client_id": "do-app",
+        "scope": scope,
+    }
+
+    response = httpx.post(
+        keycloak_url,
+        data=data,  # sent as application/x-www-form-urlencoded
+        # Let httpx set Content-Type automatically for form data
+    )
+
+    response.raise_for_status()
+    return response.json()

deeporigin_sdk/config.py

@@ -0,0 +1,184 @@
+"""Simplified configuration management for Deep Origin client.
+
+This module stores and retrieves only two configuration values:
+`env` and `org_key`.
+
+Behavior:
+- If the config file does not exist, it is created with `env=prod` and an
+  empty `org_key`.
+- If the config file exists, it is read and a dictionary is returned.
+"""
+
+import json
+import os
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+from deeporigin_sdk.utils.constants import ENV_VARIABLES
+from deeporigin_sdk.utils.core import _ensure_do_folder, _supports_unicode_output
+
+CONFIG_JSON_LOCATION = _ensure_do_folder() / "config.json"
+
+__all__ = [
+    "get_org",
+    "set_org",
+    "get_env",
+    "set_env",
+    "get_value",
+    "CONFIG_JSON_LOCATION",
+]
+
+
+def _ensure_config_file_exists() -> None:
+    """Ensure the configuration file exists; create with defaults if missing."""
+
+    if not os.path.isfile(CONFIG_JSON_LOCATION):
+        default_data: dict = {"env": "prod", "org_key": ""}
+        os.makedirs(os.path.dirname(CONFIG_JSON_LOCATION), exist_ok=True)
+        with open(CONFIG_JSON_LOCATION, "w") as file:
+            json.dump(default_data, file, indent=2)
+
+
+def get_org() -> str | None:
+    """Get the organization key.
+
+    Creates the config file with defaults if it doesn't exist.
+
+    Returns:
+        The organization key, or None if not set. Environment variables
+        override the config file value.
+    """
+    return get_value()["org_key"]
+
+
+def set_org(value: str) -> None:
+    """Set the organization key.
+
+    Args:
+        value: The organization key to set.
+
+    Raises:
+        DeepOriginException: If the organization key does not exist in the
+            list of accessible organizations.
+    """
+    from deeporigin_sdk.exceptions import DeepOriginException
+
+    # Validate that the org key exists
+    orgs_df = list_orgs()
+    if value not in orgs_df["key"].values:
+        available_keys = ", ".join(orgs_df["key"].tolist())
+        raise DeepOriginException(
+            title="Invalid organization key",
+            message=f"Organization key '{value}' not found in accessible organizations.",
+            fix=f"Available organization keys: {available_keys}",
+            level="danger",
+        )
+
+    _set_value("org_key", value)
+
+
+def get_env() -> str:
+    """Get the environment.
+
+    Creates the config file with defaults if it doesn't exist.
+
+    Returns:
+        The environment (e.g., 'prod', 'staging', 'edge', 'dev', 'local'). Defaults to 'prod'.
+        Environment variables override the config file value.
+    """
+    return get_value()["env"]
+
+
+def set_env(value: str) -> None:
+    """Set the environment.
+
+    Args:
+        value: The environment to set (e.g., 'prod', 'staging', 'edge', 'dev', 'local').
+    """
+    _set_value("env", value)
+
+
+def _set_value(key: Literal["env", "org_key"], value) -> None:
+    """Internal helper to set a configuration value.
+
+    Args:
+        key: Configuration key to set (must be 'env' or 'org_key').
+        value: Value to set.
+    """
+    _ensure_config_file_exists()
+
+    with open(CONFIG_JSON_LOCATION, "r") as file:
+        data = json.load(file) or {}
+
+    data[key] = value
+
+    # Persist updated data
+    with open(CONFIG_JSON_LOCATION, "w") as file:
+        json.dump(data, file, indent=2)
+
+    # Prefer Unicode on capable terminals; fall back to ASCII-safe symbols
+    if _supports_unicode_output():
+        check, arrow = "✔︎", "→"
+    else:
+        check, arrow = "OK", "->"
+    print(f"{check} {key} {arrow} {value}")
+
+
+def get_value() -> dict:
+    """Get the configuration values.
+
+    Creates the file with defaults if it doesn't exist, then returns a dict
+    with keys `env` and `org_key`.
+
+    Args:
+        config_file_location: Optional custom path for the config file.
+
+    Returns:
+        A dictionary with keys `env` and `org_key`.
+    """
+
+    _ensure_config_file_exists()
+
+    with open(CONFIG_JSON_LOCATION, "r") as file:
+        data = json.load(file) or {}
+
+    # Fill defaults if missing
+    env = data.get("env", "prod")
+    org_key = data.get("org_key", None)
+
+    # env variables override config file
+    if ENV_VARIABLES["env"] in os.environ:
+        env = os.environ[ENV_VARIABLES["env"]]
+    if ENV_VARIABLES["org_key"] in os.environ:
+        org_key = os.environ[ENV_VARIABLES["org_key"]]
+
+    return {"env": env, "org_key": org_key}
+
+
+def list_orgs() -> "pd.DataFrame":
+    """List all organizations accessible to the authenticated user.
+
+    Returns:
+        A pandas DataFrame with columns: name, key, autoApproveMaxAmount, threshold.
+    """
+    import pandas as pd
+
+    from deeporigin_sdk.platform.client import DeepOriginClient
+
+    client = DeepOriginClient.get()
+    orgs = client.organizations.list()
+
+    # Extract only the required columns and map orgKey to key
+    data = [
+        {
+            "name": org["name"],
+            "key": org["orgKey"],
+            "autoApproveMaxAmount": org["autoApproveMaxAmount"],
+            "threshold": org["threshold"],
+        }
+        for org in orgs
+    ]
+
+    return pd.DataFrame(data)

deeporigin_sdk/exceptions.py

@@ -0,0 +1,125 @@
+"""custom exceptions to surface better errors in notebooks"""
+
+import sys
+
+from deeporigin_sdk.utils.core import _supports_color
+
+__all__ = ["DeepOriginException", "install_silent_error_handler"]
+
+
+class DeepOriginException(Exception):
+    """Stops execution without showing a traceback, displays a styled error card."""
+
+    def __init__(self, title="Error", message=None, fix=None, level="danger"):
+        super().__init__(message or title)
+        self.title = title
+        self.body = message or ""
+        self.footer = fix
+        # accepted: danger | warning | info | success | secondary
+        self.level = level
+
+    def __str__(self) -> str:
+        """Format exception for display. Returns minimal output in notebooks (where HTML rendering is handled separately) or formatted console output otherwise."""
+        # Try to use IPython display if available (for notebooks)
+        try:
+            from IPython import get_ipython
+
+            ip = get_ipython()
+            if ip is not None and "pytest" not in sys.modules:
+                # In notebook, let the custom handler display HTML
+                # Return minimal string to avoid double display
+                return self.title
+        except ImportError:
+            # IPython is not available; fall back to console output formatting below.
+            pass
+
+        # Format for console output
+        lines = []
+
+        # Add colored title if terminal supports it
+        if _supports_color():
+            level_colors = {
+                "danger": "\033[91m",  # Red
+                "warning": "\033[93m",  # Yellow
+                "info": "\033[94m",  # Blue
+                "success": "\033[92m",  # Green
+                "secondary": "\033[90m",  # Gray
+            }
+            reset = "\033[0m"
+            color = level_colors.get(self.level, reset)
+            lines.append(f"{color}╔═ {self.title} ═╗{reset}")
+        else:
+            lines.append(f"╔═ {self.title} ═╗")
+
+        # Add body
+        if self.body:
+            lines.append(self.body)
+
+        # Add footer/fix if present
+        if self.footer:
+            if _supports_color():
+                lines.append(f"\033[2m{self.footer}\033[0m")  # Dimmed text
+            else:
+                lines.append(self.footer)
+
+        return "\n".join(lines)
+
+
+def _silent_error_handler(shell, etype, evalue, tb, tb_offset=None):
+    """Display a styled error card using Bootstrap 5.3.0."""
+    try:
+        from IPython.display import HTML, display
+    except ImportError:
+        # Fallback to console output if IPython not available
+        print(str(evalue), file=sys.stderr)
+        return []
+
+    footer_html = (
+        f'<div class="card-footer text-muted">{evalue.footer}</div>'
+        if evalue.footer
+        else ""
+    )
+
+    html = f"""
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
+    </head>
+    <body>
+        <div class="container-fluid px-0">
+            <div class="card border-{evalue.level} mb-3 shadow-sm" style="max-width: 42rem;">
+                <div class="card-header bg-{evalue.level} text-white fw-bold">
+                    {evalue.title}
+                </div>
+                <div class="card-body">
+                    <div class="card-text">
+                        {evalue.body}
+                    </div>
+                </div>
+                {footer_html}
+            </div>
+        </div>
+    </body>
+    </html>
+    """
+    display(HTML(html))
+    return []  # suppress traceback completely
+
+
+def install_silent_error_handler() -> bool:
+    """Install a custom error handler for IPython notebooks that displays a styled error card."""
+    try:
+        from IPython import get_ipython
+    except ImportError:
+        return False
+    ip = get_ipython()
+    if ip is None or "pytest" in sys.modules:
+        return False
+    ip.set_custom_exc((DeepOriginException,), _silent_error_handler)
+    return True
+
+
+install_silent_error_handler()

deeporigin_sdk/platform/__init__.py

@@ -0,0 +1,23 @@
+"""Platform client module.
+
+Provides the `DeepOriginClient` used to interact with the Deep Origin platform.
+
+This module supports configuration via keyword arguments or the following
+environment variables when keywords are omitted:
+
+- `DEEPORIGIN_TOKEN`
+- `DEEPORIGIN_ENV` (defaults to "prod" if not provided)
+- `DEEPORIGIN_ORG_KEY`
+
+The client automatically caches instances based on (base_url, token, org_key, tag),
+so calling `DeepOriginClient()` multiple times with the same parameters returns
+the same cached instance, reusing connection pools.
+
+Example:
+    client = DeepOriginClient()  # Uses singleton cache automatically
+    client.tag = "my-tag"  # Set tag for all function runs
+"""
+
+from deeporigin_sdk.platform.client import DeepOriginClient
+
+__all__ = ["DeepOriginClient"]