icmd-python 1.5.8__py3-none-any.whl → 1.7.1__py3-none-any.whl

icmd/__init__.py

@@ -1,5 +1,15 @@
-"""Python client app for ICMD® API."""
+"""Python client for the ICMD® API."""
 
-from .core import ICMD
+from .client import ICMD
+from .core.exceptions import (
+    ICMDAuthenticationError,
+    ICMDConnectionError,
+    ICMDValidationError,
+)
 
-__all__ = ["ICMD"]
+__all__ = [
+    "ICMD",
+    "ICMDAuthenticationError",
+    "ICMDConnectionError",
+    "ICMDValidationError",
+]

icmd/apps/__init__.py

@@ -0,0 +1,18 @@
+"""Composition-based resource access for ICMD® API.
+
+Provides a clean nested-attribute API::
+
+    icmd = ICMD("icmd.questek.com")
+    icmd.alloy_design.job.list(page=1, page_size=10)
+    icmd.workspace.dataset.get("uuid-123")
+"""
+
+from .design import DesignApp
+from .fatigue import FatigueApp
+from .workspace import WorkspaceApp
+
+__all__ = [
+    "DesignApp",
+    "FatigueApp",
+    "WorkspaceApp",
+]

icmd/apps/base.py

@@ -0,0 +1,254 @@
+"""Base resource classes for ICMD® API access.
+
+Provides generic CRUD resources and specialized subclasses for designs
+and jobs.  App modules compose these to expose a clean nested-attribute
+API through the :class:`~icmd.client.ICMD` facade.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from icmd.core.exceptions import ICMDRequestError
+
+if TYPE_CHECKING:
+    from icmd.core.session import ResourceClient
+
+    from .types import JobLogResponse, PaginatedResponse
+
+
+def _expect_dict(data: dict | list[dict], endpoint: str) -> dict:
+    """Narrow a transport-layer response to a single object dict."""
+    if isinstance(data, dict):
+        return data
+    raise ICMDRequestError(f"Expected object response from '{endpoint}', got list")
+
+
+_DEFAULT_PAGE_SIZE = 10
+
+
+def _expect_paginated(
+    data: dict | list[dict],
+    endpoint: str,
+    params: dict[str, Any] | None = None,
+) -> PaginatedResponse:
+    """Narrow a transport-layer response to a paginated envelope.
+
+    Some endpoints (e.g. ``qt_model``) return a plain list instead of a
+    paginated envelope.  When that happens the list is client-side
+    paginated using ``page`` and ``page_size`` from *params* (defaulting
+    to page 1 / 10 items) so callers can treat every list response
+    uniformly.
+    """
+    if isinstance(data, list):
+        total = len(data)
+        return {  # type: ignore[return-value]
+            "count": total,
+            "page_count": 1,
+            "page": 1,
+            "page_size": total or _DEFAULT_PAGE_SIZE,
+            "next": None,
+            "previous": None,
+            "data": data,
+        }
+    if isinstance(data, dict) and "data" in data and "count" in data:
+        return data  # type: ignore[return-value]
+    raise ICMDRequestError(
+        f"Expected paginated response from '{endpoint}', got {type(data).__name__}"
+    )
+
+
+class Resource:
+    """Generic CRUD resource bound to an API path.
+
+    Parameters
+    ----------
+    client : ResourceClient
+        Any object satisfying the :class:`ResourceClient` protocol
+        (i.e. :class:`~icmd.client.ICMD`).
+    path : str
+        The API endpoint path (e.g. ``"design_alloy/job"``).
+    """
+
+    def __init__(self, client: ResourceClient, path: str) -> None:
+        self._client = client
+        self._path = path
+
+    def list(
+        self,
+        *,
+        display: Literal["auto", "off"] = "off",
+        **params: Any,
+    ) -> PaginatedResponse:
+        """List resources with pagination.
+
+        Parameters
+        ----------
+        display : ``"auto"`` | ``"off"``
+            ``"auto"`` renders an interactive paginated table after fetching
+            (ipywidgets in Jupyter, text table in terminal).  ``"off"``
+            returns data with no side effects.
+        **params
+            Query parameters forwarded to the API (e.g. ``page``, ``page_size``).
+        """
+        raw = self._client.request_json("get", self._path, params=params or None)
+        data = _expect_paginated(raw, self._path, params or None)
+        if display == "auto":
+            from icmd.core.display import display as _display
+
+            _display(
+                self._client,
+                self._path,
+                dict(data),
+                params or None,
+                local_pagination=isinstance(raw, list),
+            )
+        return data
+
+    def get(self, uuid: str) -> dict:
+        """Get a single resource by UUID.
+
+        Group injection is skipped so the backend resolves access across
+        all groups the caller belongs to (cross-group retrieval).
+        """
+        endpoint = f"{self._path}/{uuid}"
+        return _expect_dict(
+            self._client.request_json("get", endpoint, inject_group=False), endpoint
+        )
+
+    def add(self, data: Any = None) -> dict:
+        """Create a new resource."""
+        return _expect_dict(
+            self._client.request_json("post", self._path, json=data),
+            self._path,
+        )
+
+
+_TERMINAL_STATUSES = frozenset({"successful", "failed", "partial", "cancelled"})
+
+
+class JobResource(Resource):
+    """Job resource with log retrieval and status polling."""
+
+    def check_status(self, uuid: str) -> tuple[str, dict]:
+        """Check the current status of a job.
+
+        Returns (status, job_data) where status is the job_status string.
+        """
+        job_data = self.get(uuid)
+        status = job_data.get("job_status", "unknown")
+        return status, job_data
+
+    def poll(
+        self,
+        uuid: str,
+        *,
+        interval: int = 5,
+        quiet: bool = False,
+        logs: bool = True,
+    ):
+        """Poll until the job reaches a terminal status, streaming logs.
+
+        Parameters
+        ----------
+        uuid : str
+            The job UUID.
+        interval : int
+            Seconds between poll attempts (default 5).
+        quiet : bool
+            When True, suppress all printed output and skip log fetching.
+        logs : bool
+            When True (default), fetch and print job logs each poll cycle.
+            When False, only print status transitions. Ignored if *quiet* is True.
+        """
+        import time
+
+        last_status = None
+        next_ts: str | None = None
+
+        try:
+            while True:
+                job_data = self.get(uuid)
+                status = job_data.get("job_status", "unknown").lower()
+
+                if not quiet and status != last_status:
+                    print(f"Job {uuid}: {status}")
+                    last_status = status
+
+                if not quiet and logs:
+                    log_resp = self.log(uuid, from_timestamp=next_ts)
+                    log_text = log_resp.get("logs", "")
+                    if log_text:
+                        print(log_text, end="")
+                    next_ts = log_resp.get("next_timestamp")
+
+                if status in _TERMINAL_STATUSES:
+                    return
+
+                time.sleep(interval)
+        except KeyboardInterrupt:
+            if not quiet:
+                print(f"\nPolling interrupted. Last status: {last_status}")
+            return
+
+    def log(
+        self,
+        uuid: str,
+        *,
+        from_timestamp: str | None = None,
+    ) -> JobLogResponse:
+        """Retrieve logs for a job.
+
+        Parameters
+        ----------
+        uuid : str
+            The job UUID.
+        from_timestamp : str | None
+            ISO 8601 timestamp for incremental log fetching.
+            When provided, only logs created after this timestamp are returned.
+
+        Returns
+        -------
+        JobLogResponse
+            Dict with ``logs``, ``next_timestamp``, ``logs_finished``,
+            and ``is_full_log`` keys.
+        """
+        endpoint = f"{self._path}/{uuid}/get_job_log"
+        params: dict[str, str] = {}
+        if from_timestamp is not None:
+            params["from_timestamp"] = from_timestamp
+        return _expect_dict(  # type: ignore[return-value]
+            self._client.request_json("get", endpoint, inject_group=False, params=params or None),
+            endpoint,
+        )
+
+
+class DesignResource(Resource):
+    """Design resource with create-time metadata."""
+
+    def add(
+        self,
+        data: dict | None = None,
+        *,
+        design_name: str | None = None,
+        share_with_group: bool = True,
+    ) -> dict:
+        """Create a new design.
+
+        Parameters
+        ----------
+        data : dict | None
+            Payload for the design. If None, an empty dict is used.
+        design_name : str | None
+            Optional name for the design (sets 'name' key).
+        share_with_group : bool
+            Whether to share with the owner group (default True).
+        """
+        payload: dict[str, Any] = dict(data) if data else {}
+        if design_name is not None:
+            payload["name"] = design_name
+        payload["share_with_group"] = share_with_group
+        return _expect_dict(
+            self._client.request_json("post", self._path, json=payload),
+            self._path,
+        )

icmd/apps/design.py

@@ -0,0 +1,35 @@
+"""Design Alloy toolkit resources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import DesignResource, JobResource, Resource
+
+if TYPE_CHECKING:
+    from icmd.core.session import ResourceClient
+
+
+class DesignApp:
+    """Design Alloy toolkit resources."""
+
+    __slots__ = (
+        "design",
+        "folder",
+        "job",
+        "material_family",
+        "model",
+        "model_workflow",
+        "result",
+        "settings",
+    )
+
+    def __init__(self, client: ResourceClient) -> None:
+        self.job = JobResource(client, "design_alloy/job")
+        self.design = DesignResource(client, "design_alloy/design")
+        self.model = Resource(client, "design_alloy/qt_model")
+        self.result = Resource(client, "design_alloy/results")
+        self.model_workflow = Resource(client, "design_alloy/model_workflow")
+        self.settings = Resource(client, "design_alloy/settings")
+        self.folder = Resource(client, "design_alloy/folders")
+        self.material_family = Resource(client, "design_alloy/material_family")

icmd/apps/fatigue.py

@@ -0,0 +1,33 @@
+"""Fatigue Simulation toolkit resources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import DesignResource, JobResource, Resource
+
+if TYPE_CHECKING:
+    from icmd.core.session import ResourceClient
+
+
+class FatigueApp:
+    """Fatigue Simulation toolkit resources."""
+
+    __slots__ = (
+        "design",
+        "folder",
+        "job",
+        "material_family",
+        "model",
+        "model_workflow",
+        "result",
+    )
+
+    def __init__(self, client: ResourceClient) -> None:
+        self.job = JobResource(client, "simulation_fatigue/job")
+        self.design = DesignResource(client, "simulation_fatigue/design")
+        self.model = Resource(client, "simulation_fatigue/qt_model")
+        self.result = Resource(client, "simulation_fatigue/results")
+        self.model_workflow = Resource(client, "simulation_fatigue/model_workflow")
+        self.folder = Resource(client, "simulation_fatigue/folders")
+        self.material_family = Resource(client, "simulation_fatigue/material_family")

icmd/apps/types.py

@@ -0,0 +1,39 @@
+"""Response types for ICMD® app resources."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class PaginatedResponse(TypedDict):
+    """Pagination envelope returned by all list endpoints.
+
+    Mirrors the backend's ``StandardPagination.get_paginated_response()``.
+    The ``data`` key contains the page items; ``count``, ``page_count``,
+    ``page``, and ``page_size`` describe pagination metadata.
+    """
+
+    count: int
+    page_count: int
+    page: int
+    page_size: int
+    next: str | None
+    previous: str | None
+    data: list[dict]
+
+
+class JobLogResponse(TypedDict):
+    """Response from the job log endpoint.
+
+    ``logs`` contains the log text (may be a partial chunk when using
+    ``from_timestamp`` for incremental fetching).  ``next_timestamp``
+    is the cursor for the next incremental request (``None`` when no
+    more logs are available).  ``logs_finished`` indicates whether the
+    job has completed logging.  ``is_full_log`` indicates whether the
+    response contains the complete combined log.
+    """
+
+    logs: str
+    next_timestamp: str | None
+    logs_finished: bool
+    is_full_log: bool

icmd/apps/workspace.py

@@ -0,0 +1,41 @@
+"""Workspace resources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import Resource
+
+if TYPE_CHECKING:
+    from icmd.core.session import ResourceClient
+
+
+class WorkspaceApp:
+    """Workspace resources."""
+
+    __slots__ = (
+        "composition",
+        "composition_group",
+        "database",
+        "dataset",
+        "document",
+        "document_folder",
+        "ml_model",
+        "plot",
+        "project",
+        "specification",
+        "specification_group",
+    )
+
+    def __init__(self, client: ResourceClient) -> None:
+        self.dataset = Resource(client, "workspace/dataset")
+        self.ml_model = Resource(client, "workspace/mlmodels")
+        self.project = Resource(client, "workspace/project")
+        self.database = Resource(client, "workspace/database")
+        self.document = Resource(client, "workspace/document")
+        self.document_folder = Resource(client, "workspace/document_folder")
+        self.composition = Resource(client, "workspace/composition")
+        self.composition_group = Resource(client, "workspace/composition_group")
+        self.specification = Resource(client, "workspace/specification")
+        self.specification_group = Resource(client, "workspace/specification_group")
+        self.plot = Resource(client, "workspace/plot")

icmd/cli/__init__.py

@@ -0,0 +1,177 @@
+"""ICMD® command-line interface.
+
+Entry point: ``icmd`` (installed via ``[project.scripts]``).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from icmd.client import ICMD
+from icmd.core.credentials import CredentialManager
+from icmd.core.exceptions import (
+    ICMDAuthenticationError,
+    ICMDConnectionError,
+    ICMDRequestError,
+    ICMDValidationError,
+)
+from icmd.core.session import normalize_domain
+from icmd.version import __version__
+
+from .auth import CLIAuthenticator, NullAuthenticator
+from .commands import _global_options, register_commands
+from .domain import expand_domain
+from .output import write_error, write_output
+
+
+class _ICMDGroup(click.Group):
+    """Root group with ICMD® error handling."""
+
+    def invoke(self, ctx: click.Context) -> Any:
+        """Invoke the command, catching SDK exceptions as JSON errors."""
+        try:
+            return super().invoke(ctx)
+        except click.exceptions.Exit:
+            raise
+        except click.ClickException:
+            raise
+        except (
+            ICMDAuthenticationError,
+            ICMDValidationError,
+            ICMDConnectionError,
+            ICMDRequestError,
+        ) as exc:
+            name = type(exc).__name__.removeprefix("ICMD")
+            write_error(name, str(exc))
+            ctx.exit(1)
+        except KeyboardInterrupt:
+            ctx.exit(130)
+        return None
+
+
+@click.group(cls=_ICMDGroup)
+@click.version_option(__version__, prog_name="icmd")
+@click.option(
+    "--domain",
+    envvar="ICMD_DOMAIN",
+    default=None,
+    help="ICMD® domain (e.g. 'dev' or 'dev.icmd.questek.com').",
+)
+@click.option(
+    "--token",
+    envvar="ICMD_TOKEN",
+    default=None,
+    help="Developer API token (alternative to 'icmd login').",
+)
+@click.option(
+    "--group",
+    envvar="ICMD_GROUP",
+    default=None,
+    help="Owner group ID or name.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["json", "text"]),
+    default="json",
+    show_default=True,
+    help="Output format.",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    domain: str | None,
+    token: str | None,
+    group: str | None,
+    output_format: str,
+) -> None:
+    """ICMD® command-line interface."""
+    ctx.ensure_object(dict)
+    ctx.obj["domain"] = expand_domain(domain) if domain else domain
+    ctx.obj["token"] = token
+    ctx.obj["group"] = group
+    ctx.obj["format"] = output_format
+
+
+# ---------------------------------------------------------------------------
+# Top-level commands
+# ---------------------------------------------------------------------------
+
+
+@cli.command()
+@click.option(
+    "--domain",
+    envvar="ICMD_DOMAIN",
+    required=True,
+    help="ICMD® domain (e.g. 'dev' or 'dev.icmd.questek.com').",
+)
+@click.pass_context
+def login(ctx: click.Context, domain: str) -> None:
+    """Authenticate with an ICMD® instance.
+
+    Triggers interactive authentication (SAML or password) and caches
+    credentials for subsequent commands.
+    """
+    domain = expand_domain(domain)
+    ICMD(domain, authenticator=CLIAuthenticator(), skip_slim=True)
+    fmt = ctx.obj.get("format", "json")
+    write_output({"status": "ok", "domain": domain}, fmt=fmt)
+
+
+@cli.command()
+@click.option(
+    "--domain",
+    envvar="ICMD_DOMAIN",
+    required=True,
+    help="ICMD® domain (e.g. 'dev' or 'dev.icmd.questek.com').",
+)
+@click.pass_context
+def logout(ctx: click.Context, domain: str) -> None:
+    """Clear cached credentials for an ICMD® instance."""
+    domain = expand_domain(domain)
+    normalized = normalize_domain(domain)
+    CredentialManager().clear_domain_credentials(normalized)
+    fmt = ctx.obj.get("format", "json")
+    write_output({"status": "ok", "domain": normalized}, fmt=fmt)
+
+
+# ---------------------------------------------------------------------------
+# Top-level account commands (no owner-group injection)
+# ---------------------------------------------------------------------------
+
+
+@cli.group("group")
+def group_cmd() -> None:
+    """Manage user groups."""
+
+
+@group_cmd.command("list")
+@_global_options
+def group_list() -> None:
+    """List groups the current user belongs to."""
+    ctx = click.get_current_context()
+    domain = ctx.obj.get("domain")
+    if not domain:
+        raise click.UsageError("Missing --domain option or ICMD_DOMAIN environment variable.")
+    client = ICMD(
+        domain=domain,
+        developer_token=ctx.obj.get("token"),
+        authenticator=NullAuthenticator(),
+        skip_slim=True,
+    )
+    groups = client.get_groups()
+    write_output(groups, fmt=ctx.obj.get("format", "json"))
+
+
+# ---------------------------------------------------------------------------
+# Register resource commands from the registry
+# ---------------------------------------------------------------------------
+
+register_commands(cli)
+
+
+def main() -> None:
+    """CLI entry point."""
+    cli()