icmd-python 1.1.4__py3-none-any.whl

icmd/__init__.py

@@ -0,0 +1,3 @@
+"""Python client app for ICMD® API."""
+
+from .core import Session

icmd/clients/__init__.py

@@ -0,0 +1 @@
+"""Client apps for ICMD API."""

icmd/clients/calphad_client.py

@@ -0,0 +1,93 @@
+"""Client for the CALPHAD Simulation Toolkit."""
+
+import warnings
+from http import HTTPStatus
+
+import pandas as pd
+from pandas.io.formats.style import Styler
+
+from icmd.core import BaseClient
+from icmd.core.job_table_format import qt_job_table_style
+
+try:
+    import qt_calphad
+except ImportError:
+    qt_calphad = None
+
+
+class CalphadClient(BaseClient):
+    """Client for the CALPHAD Simulation Toolkit."""
+
+    app_name = "simulation_calphad"
+
+    def __init__(self):
+        super().__init__()
+
+        if qt_calphad is None:
+            raise NotImplementedError("qt_calphad is not installed in current Python.")
+
+    def submit_job(self, name: str, input_dict: dict, send_email: bool = True) -> str:
+        """Submit a job to the queue."""
+        data = {"name": name, "input_dict": input_dict, "send_email": send_email}
+        self.send_request("post", "job", data)
+
+        if self.response.status_code != HTTPStatus.CREATED:
+            raise ValueError("Job submission failed. Check out client.request for more info.")
+
+        data = self.response.json()
+        return data["uuid"]
+
+    def retrieve_job(self, uuid: str):
+        """Retrieve a job from server with given id and load job as calculation object."""
+        self.send_request("get", f"job/{uuid}/get_full_job/")
+
+        if self.response.status_code != HTTPStatus.OK:
+            raise ValueError(
+                "Job retrieval failed. Check out client.session.request for more info."
+            )
+
+        data = self.response.json()
+
+        if data.get("job_status") != "successful" or not data.get("results", {}).get("data"):
+            warnings.warn(
+                "This job is not completed or successful. Loading only input-dict...", stacklevel=2
+            )
+            calculation = qt_calphad.load_calculation(data.get("input_dict"), {}, [])
+        else:
+            try:
+                calculation = qt_calphad.load_calculation(
+                    data.get("input_dict"), data.get("results", {}).get("data"), plots=[]
+                )
+            except Exception as e:
+                warnings.warn(f"Failed to load full calculation: {e}", stacklevel=2)
+                warnings.warn("Loading only input-dict...", stacklevel=2)
+                calculation = qt_calphad.load_calculation(data.get("input_dict"), {}, [])
+
+        return calculation
+
+    def delete_job(self, uuid: str) -> None:
+        """Delete a job with known id."""
+        self.send_request("delete", f"job/{uuid}")
+
+        if self.response.status_code != HTTPStatus.NO_CONTENT:
+            raise ValueError("Job deletion failed. Make sure you have the permission to delete.")
+
+    def list_my_jobs(self, jupyter=True) -> pd.DataFrame | Styler:
+        """List all jobs belong to current user."""
+        self.send_request("get", "job/my_jobs")
+        data = self.response.json()
+        df_data = pd.DataFrame(data)
+
+        if jupyter:
+            df_data.insert(0, "icmd", "")
+            df_data["icmd"] = df_data.apply(lambda row: get_icmd_url(row), axis=1)
+
+            return df_data.style.format(qt_job_table_style).hide(axis="index")
+        return df_data
+
+
+def get_icmd_url(row):
+    """Generate url endpoints for each df row."""
+    if row["type"] in ["point", "step", "grid"]:
+        return f'/simulation_calphad/equilibrium/{row["uuid"]}'
+    return f'/simulation_calphad/{row["type"]}/{row["uuid"]}'

icmd/core/__init__.py

@@ -0,0 +1,4 @@
+"""Core module for icmd package."""
+
+from .base_client import BaseClient
+from .session import Session

icmd/core/base_client.py

@@ -0,0 +1,29 @@
+"""Base class for ICMD API clients."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import requests
+
+from .session import Session
+
+
+class BaseClient:
+    """Client to facilitate user workflows with QuesTek IDE APIs."""
+
+    app_name = ""  # app name in Django urls, provide in subclasses
+
+    def __init__(self):
+        self.session: Session = Session()
+        self.response: requests.Response | None = None
+
+    def send_request(self, method: str, endpoint: str, data: dict | None = None, **kwargs):
+        """Send a request to the ICMD API."""
+        url = self._get_url(endpoint)
+        self.response = self.session.checked_request(method, url, json=data, **kwargs)
+
+    def _get_url(self, endpoint: str) -> str:
+        """Get the full url for a request with app-specific endpoint."""
+        _app_name = self.app_name.strip("/")
+        _endpoint = endpoint.strip("/")
+        return f"{_app_name}/{_endpoint}/"

icmd/core/job_table_format.py

@@ -0,0 +1,48 @@
+"""Format strings in the job table."""
+
+
+def make_clickable(url):
+    """Make a URL clickable."""
+    url = url.lstrip("/")
+    return f'<a href="https://server.questek.com/icmd/{url}">Link</a>'
+
+
+def beautify_job_status(status: str):
+    """Beautify job status."""
+    if status == "successful":
+        return (
+            '<span style="color:white; display:inline-block; padding:5px; '
+            'background-color:rgb(46, 125, 50)">Successful</span>'
+        )
+    if status == "failed":
+        return (
+            '<span style="color:white; display:inline-block; padding:5px; '
+            'background-color:rgb(211, 47, 47)">Failed</span>'
+        )
+    if status == "running":
+        return (
+            '<span style="color:white; display:inline-block; padding:5px; '
+            'background-color:rgb(237, 108, 2)">Running</span>'
+        )
+    if status == "submitted":
+        return (
+            '<span style="color:white; display:inline-block; padding:5px; '
+            'background-color:rgb(55, 111, 208)">Submitted</span>'
+        )
+    return status
+
+
+def beautify_datetime(value: str) -> str:
+    """Beautify datetime string."""
+    if isinstance(value, str):
+        return value.split(".")[0].replace("T", " ")
+    return str(value)
+
+
+qt_job_table_style = {
+    "icmd": make_clickable,
+    "job_status": beautify_job_status,
+    "job_started_at": beautify_datetime,
+    "job_finished_at": beautify_datetime,
+    "created_at": beautify_datetime,
+}

icmd/core/session.py

@@ -0,0 +1,347 @@
+"""Session class to handle ICMD API requests."""
+
+import json
+import logging
+import re
+import socket
+import socketserver
+import webbrowser
+from datetime import datetime, timedelta
+from getpass import getpass
+from http import HTTPStatus
+from pathlib import Path
+
+import requests.auth
+from IPython.display import HTML, display
+
+from .token_handler import TokenHandler
+
+TOKEN_EXPIRE_BUFFER: timedelta = timedelta(milliseconds=5000)
+CREDENTIAL_FILE = str(Path.home() / ".icmd_cred.json")
+
+SIGN_IN_METHODS = {"SAML", "PASSWORD"}
+AUTH_PORTS = [8001, 8002, 8003, 8004, 8005]
+
+def _find_available_port(port_list: list) -> int:
+    """Find the first available port from the predefined list."""
+    for port in port_list:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                s.bind(("127.0.0.1", port))
+                return port
+            except OSError:
+                continue
+    raise RuntimeError(f"No available ports found in the predefined list: {port_list}")
+
+class ThreadedTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
+    """Handle requests in a separate thread."""
+
+    allow_reuse_address = True
+
+class Session(requests.Session):
+    """Wrapper around requests.Session that auto refresh token."""
+
+    def __init__(self, jupyterlite: bool = False):
+        super().__init__()
+        self.api_version = "v1"
+
+        self.sign_in_method: str = ""
+        self.icmd_domain: str = ""
+        self.username: str = ""
+        self.password: str = ""
+        self.mfa_code: str = ""
+        self.auth_code: str = ""
+        self.jupyterlite = jupyterlite
+
+        self.refresh_token: str = ""
+        self.id_token: str = ""
+        self.id_token_expiration: datetime = datetime.utcnow()
+        self.headers.update({"Content-Type": "application/json"})
+
+        self._load_credential_file()
+        if not jupyterlite:
+            self._refresh_id_token()
+
+    @property
+    def api_root(self) -> str:
+        """Return the root of the ICMD API, e.g., https://icmd.questek.com/api/v1."""
+        if not self._is_valid_icmd_domain:
+            self.icmd_domain = input("Your ICMD® domain (e.g., icmd.questek.com): ")
+            if not self.icmd_domain.startswith("http"):
+                self.icmd_domain = "https://" + self.icmd_domain
+            self.sign_in_method = input(
+                'If you use SSO, please enter "saml"; otherwise, leave empty: '
+            )
+            self.sign_in_method = self.sign_in_method.strip().upper()
+            if self.sign_in_method == "":
+                self.sign_in_method = "SAML"
+            if self.sign_in_method not in SIGN_IN_METHODS:
+                raise ValueError("Invalid sign-in method.")
+
+        self._write_credential_file()
+        return f"{self.icmd_domain}/api/{self.api_version}"
+
+    def _load_credential_file(self) -> None:
+        """Load icmd_domain and refresh_token from the CREDENTIAL_FILE."""
+        if not Path(CREDENTIAL_FILE).is_file():
+            return
+        try:
+            with open(CREDENTIAL_FILE) as file:
+                data = json.load(file)
+            self.icmd_domain = data.get("ICMD_DOMAIN", "")
+            self.sign_in_method = data.get("ICMD_SIGN_IN_METHOD", "")
+            self.refresh_token = data.get("ICMD_REFRESH_TOKEN", "")
+        except OSError:
+            logging.warning(f"Cannot open credential file: {CREDENTIAL_FILE}")
+        except json.JSONDecodeError:
+            logging.warning(f"Cannot decode credential file in JSON: {CREDENTIAL_FILE}")
+
+    def _write_credential_file(self) -> None:
+        """Write current values to the CREDENTIAL_FILE."""
+        data = {
+            "ICMD_DOMAIN": self.icmd_domain,
+            "ICMD_SIGN_IN_METHOD": self.sign_in_method,
+            "ICMD_REFRESH_TOKEN": self.refresh_token,
+        }
+        with open(CREDENTIAL_FILE, "w") as file:
+            json.dump(data, file)
+
+    @property
+    def _is_valid_icmd_domain(self) -> bool:
+        """Check if the given domain matches the pattern of ICMD domains."""
+        if not self.icmd_domain.startswith("http"):
+            self.icmd_domain = "https://" + self.icmd_domain
+        if self.icmd_domain.endswith("server.questek.com"):
+            return True
+        if self.icmd_domain.startswith("https"):
+            pattern = r"^https://(\w*.)?icmd\.questek\.com"
+            return bool(re.match(pattern, self.icmd_domain))
+        return self.icmd_domain.startswith("http")  # ignore local development
+
+    @property
+    def _is_id_token_expired(self):
+        return self.id_token_expiration - TOKEN_EXPIRE_BUFFER <= datetime.utcnow()
+
+    def _refresh_id_token(self) -> None:
+        """Optionally refresh our id token."""
+        url = f"{self.api_root}/account/auth/refresh/"
+        response = self.request("post", url, json={"refreshToken": self.refresh_token})
+        if response.status_code != HTTPStatus.OK:
+            if self.sign_in_method.strip().upper() == "SAML":
+                self._user_saml_sign_in()
+            else:
+                self._user_sign_in()
+        else:
+            self._handle_cookies(response)
+            self._assign_tokens(response.json())
+
+    def checked_request(self, method: str, path: str, **kwargs) -> requests.Response:
+        """Make a request to the ICMD API and handle token expiration."""
+        clean_path = path.strip("/")
+        if self._is_id_token_expired:
+            self._refresh_id_token()
+
+        url = f"{self.api_root}/{clean_path}/"
+        response = self.request(method, url, **kwargs)
+
+        if response.status_code == HTTPStatus.UNAUTHORIZED and response.reason == "Unauthorized":
+            self._refresh_id_token()
+            response = self.request(method, url, **kwargs)
+
+        return response
+
+    def _assign_tokens(self, auth: dict) -> None:
+        """Assign tokens from auth response."""
+        self.headers.update({"X-User-Context": auth.get("userFingerprint")})
+        self.id_token = auth.get("idToken")
+        if auth.get("refreshToken"):
+            self.refresh_token = auth.get("refreshToken")
+        self.id_token_expiration = datetime.fromisoformat(auth.get("expiresAt"))
+        self.auth = BearerAuth(auth.get("idToken"))
+
+    def _handle_cookies(self, response: requests.Response) -> None:
+        """Handle cookies from response."""
+        for cookie in response.cookies:
+            if cookie.name == "Secure-Fgp":
+                self.cookies.set("Secure-Fgp", cookie.value)
+
+    def _mfa_sign_in(self, challenge, username, challenge_name) -> None:
+        """Sign in with MFA code."""
+        session = challenge["Session"]
+        if not self.mfa_code:
+            self.mfa_code = input("Your MFA Code: ")
+        if username is None:
+            username = input("Your ICMD® email: ")
+        url = f"{self.api_root}/account/auth/mfa/"
+        response = self.request(
+            "post",
+            url,
+            json={
+                "mfa_code": self.mfa_code,
+                "session": session,
+                "username": username,
+                "challenge_name": challenge_name,
+            },
+        )
+        if response.status_code != HTTPStatus.OK:
+            raise ValueError(str(response.json()))
+        self._handle_cookies(response)
+        self._assign_tokens(response.json())
+
+    def _handle_sign_in_response(self, username, response: requests.Response) -> None:
+        """Handle response from login API endpoint."""
+        if response.status_code != HTTPStatus.OK:
+            raise ValueError("Cannot sign into ICMD®: " + str(response.json()))
+        self._handle_cookies(response)
+        auth = response.json()
+        if auth and auth.get("challenge"):
+            challenge = auth["challenge"]
+            challenge_name = challenge.get("ChallengeName")
+            if challenge_name in {"SOFTWARE_TOKEN_MFA", "SMS_MFA"}:
+                self._mfa_sign_in(challenge, username, challenge_name)
+            else:
+                raise ValueError("Unknown challenge - " + challenge_name)
+        else:
+            self._assign_tokens(auth)
+
+    def _user_sign_in(self):
+        """Let user sign in with password to fetch a refresh token."""
+        if not self.username:
+            self.username = input("Your ICMD® email: ")
+            self.password = getpass("Your ICMD® password: ")
+            self.mfa_code = input("Your MFA Code (if enabled): ")
+
+        try:
+            url = f"{self.api_root}/account/auth/login/"
+            response = self.request(
+                "post", url, json={"username": self.username, "password": self.password}
+            )
+            self._handle_sign_in_response(self.username, response)
+        except Exception as e:
+            raise ValueError("Cannot sign into ICMD®: " + str(e)) from e
+
+        self._write_credential_file()
+
+    def _user_saml_sign_in(self):
+        """Let user sign in with SAML to fetch a refresh token."""
+        try:
+            if self.jupyterlite:
+                self._browser_env_saml_sign_in()
+            else:
+                print("\n\033[94mSigning into ICMD® with SAML SSO...\033[0m\n")
+
+                LOCAL_PORT = _find_available_port(AUTH_PORTS)
+                consent_login_url = f"{self.api_root}/account/auth/consent?redirect_uri=http://localhost:{LOCAL_PORT}/callback"
+
+                print("\n\033[94mConsent granted. Proceeding with SSO authentication...\033[0m\n")
+
+                print("Automatically opening the SSO authorization page in your default browser. "
+                    "If it doesn't open or you prefer to use a different browser, "
+                    "go to this URL:")
+
+                print(f"\n{consent_login_url}\n")
+                webbrowser.open(consent_login_url)
+
+                # Start a local server to capture the auth_code
+                with socketserver.TCPServer(("localhost", LOCAL_PORT), TokenHandler) as httpd:
+                    httpd.handle_request()  # Wait for a single request, blocking
+                    auth_code = httpd.auth_code
+                    if not auth_code:
+                        raise ValueError("Authentication code was not received.")
+
+                login_url = f"{self.api_root}/account/auth/login/"
+                response = self.request("post", login_url, json=
+                    {
+                        "code": auth_code,
+                        "redirect_uri": f"http://localhost:{LOCAL_PORT}/callback"
+                    })
+                self._handle_sign_in_response(None, response)
+                print("\n\033[92mSigned in successfully.\033[0m\n")
+        except Exception as e:
+            print("\nCannot sign into ICMD®: " + str(e) + "\n")
+        finally:
+            pass
+
+    def _browser_env_saml_sign_in(self):
+        """Show a button for signing in with SAML in JupyterLite."""
+        try:
+            # Create a sign-in button
+            consent_login_url = f"{self.api_root}/account/auth/consent"
+            buttomHTML = f"""
+            <a type="button" href="{consent_login_url}" target="_blank">Sign in with SAML SSO</a>
+            """
+            display(HTML(buttomHTML))
+        except Exception as e:
+            print(f"\nCannot sign in: {e}\n")
+
+    def complete_saml_sign_in(self):
+        """Complete the SAML sign in process."""
+        if not self.auth_code:
+            print("\033[91mPlease enter an authorization code.\033[0m")
+            return
+        try:
+            login_url = f"{self.api_root}/account/auth/login/"
+            response = self.request("post", login_url, json={
+                "code": self.auth_code,
+                "redirect_uri": f"{self.api_root}/account/auth/exchange"
+            })
+            self._handle_sign_in_response(None, response)
+            print("\n\033[92mSigned in successfully.\033[0m\n")
+        except Exception as e:
+            print(f"\n\033[91mError during sign in: {e!s}\033[0m\n")
+
+    def jupyterlite_sign_in(self):
+        """Sign in on JupyterLite."""
+        if not self.icmd_domain or not self.sign_in_method:
+            raise ValueError(
+                "Please provide all following necessary information to sign in:\n"
+                "session.icmd_domain = await input('icmd_domain'), e.g., icmd.questek.com\n"
+                "session.sign_in_method = await input('sign_in_method'), e.g., PASSWORD or SAML\n"
+            )
+
+        if self.sign_in_method == "PASSWORD" and not all(
+            [
+                self.username,
+                self.password,
+                self.mfa_code,
+            ]
+        ):
+            raise ValueError(
+                "Please provide all following necessary information to sign in:\n"
+                "session.username = await input('username'), i.e., your email\n"
+                "session.password = await getpass('password'), i.e., your password\n"
+                "session.mfa_code = await input('mfa_code'), i.e., the 6 digit code for MFA\n"
+            )
+
+        if self.sign_in_method == "SAML" and not all(
+            [self.username]
+        ):
+            raise ValueError(
+                "Please provide all following necessary information to sign in:\n"
+                "session.username = await input('username'), i.e., your email\n"
+            )
+        self._refresh_id_token()
+
+    @staticmethod
+    def extract_code(url):
+        """Extract authorization code from the url."""
+        start = url.find("code=")
+        if start == -1:
+            return None
+        start += len("code=")
+        end = url.find(" ", start)
+        if end == -1:
+            end = len(url)
+        return url[start:end]
+
+
+class BearerAuth(requests.auth.AuthBase):
+    """A lightweight Auth class to support Bearer token auth header."""
+
+    def __init__(self, token):
+        self.token = token
+
+    def __call__(self, r):
+        """Attach an Authorization header to the given Request object."""
+        r.headers["Authorization"] = f"Bearer {self.token}"
+        return r

icmd/core/token_handler.py

@@ -0,0 +1,36 @@
+"""
+TokenHandler class for processing SAML callbacks.
+
+This module implements a custom HTTP request handler for processing
+SAML callbacks. It listens for authorization codes in the callback
+requests and responds with an HTML template indicating success.
+"""
+
+import os
+from http.server import SimpleHTTPRequestHandler
+
+
+class TokenHandler(SimpleHTTPRequestHandler):
+    """Custom HTTP request handler to process the SAML callback."""
+
+    def do_GET(self):
+        """Handle GET request to capture the auth code."""
+        if "/callback?" in self.path:
+            query_data = self.path.split("?")[1]
+            token_info = dict(qc.split("=") for qc in query_data.split("&"))
+            auth_code = token_info.get("code")
+
+            if auth_code:
+                # Send a response back to the browser indicating success
+                self.send_response(200)
+                self.send_header("Content-type", "text/html")
+                self.end_headers()
+
+                file_path = os.path.join(os.path.dirname(__file__), "template/callback.html")
+                with open(file_path, "rb") as file:
+                    html_content = file.read()
+
+                self.wfile.write(html_content)
+                self.server.auth_code = auth_code
+            else:
+                self.send_error(400, "Authorization code not found")

icmd/version.py

@@ -0,0 +1 @@
+__version__ = "1.1.4"

icmd_python-1.1.4.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.1
+Name: icmd-python
+Version: 1.1.4
+Summary: Python client app for ICMD®
+Author: QuesTek Innovations LLC
+Requires-Python: >=3.10
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: myst-nb; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx-rtd-theme; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"

icmd_python-1.1.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+icmd/__init__.py,sha256=RKbCk0KLWswT4w2Ahfg15MGBhtOG70godi63UAQmjng,67
+icmd/version.py,sha256=XxXhu8-QnuD9hA8Ah0WX5rgpt_DwOQmAwcK-FtpngyQ,22
+icmd/clients/__init__.py,sha256=cKiAGFDou9bwES19V6qwlMtG1rZVi963SoqCWzqQn2Y,32
+icmd/clients/calphad_client.py,sha256=TTMOJilkIRHdTsSuyn3QMOcCCZ-H_W6ebKpBp9z6Kq8,3387
+icmd/core/__init__.py,sha256=11bBl3MBG106aN3VhYi24CqNKMhE2eAjhvQ4cFVmXsc,102
+icmd/core/base_client.py,sha256=1u-BJd3vzcG0MWAmhQbxwyzhpsPp7wj8pRfdJmW9R44,934
+icmd/core/job_table_format.py,sha256=USo0eN40EnE9esfcscP0EWRK-6Zo8_8FIcjGRNvhruc,1473
+icmd/core/session.py,sha256=mMWO5a8IzFn_bUcjpdetZaDtStAZLKzN6sqInHThuDw,13934
+icmd/core/token_handler.py,sha256=mVMJSnQ2Y5smytykdxcBrgkMWpfP8nw0oIYdY23hGrc,1343
+icmd_python-1.1.4.dist-info/METADATA,sha256=6glHN1VBRl7jPzkXxD0BnoBQF0nDM6WOvy1biE1kDCQ,478
+icmd_python-1.1.4.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+icmd_python-1.1.4.dist-info/top_level.txt,sha256=olzM6Z_QEwg7RrFVOnkgO0I2Ps2m7vhSqYQZYeiawcw,5
+icmd_python-1.1.4.dist-info/RECORD,,

icmd_python-1.1.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

icmd_python-1.1.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+icmd