icmd-python 3.3.0__py3-none-any.whl → 3.3.5__py3-none-any.whl

icmd/apps/agent.py

@@ -212,5 +212,16 @@ class AgentApp:
         return self._client.request_json("get", "agent/providers")
 
     def usage(self) -> dict | list[dict]:
-        """Get the group's monthly Assist token usage (``GET agent/assist/usage``)."""
+        """Get the group's Assist credit balance (``GET agent/assist/usage``).
+
+        Group admins only.
+
+        Returns
+        -------
+        dict
+            ``granted``, ``used``, ``balance`` and ``month_used`` in credits,
+            and ``status`` (``"ok"`` / ``"low"`` / ``"out"``).  ``balance``
+            can be negative.  An unmetered group returns ``None`` for all five
+            keys, ``status`` included.
+        """
         return self._client.request_json("get", "agent/assist/usage")

icmd/apps/jobs.py

@@ -29,7 +29,7 @@ if TYPE_CHECKING:
     from .types import JobLogResponse
 
 
-_TERMINAL_STATUSES = frozenset({"successful", "failed", "partial", "cancelled"})
+_TERMINAL_STATUSES = frozenset({"successful", "failed", "partial", "cancelled", "aborted"})
 
 #: Consecutive transient failures :meth:`JobResource.poll` absorbs before
 #: giving up.  A training job outlives the 15-minute access token several
@@ -223,11 +223,12 @@ class JobResource(ReadOnlyResource):
             The design-level CALPHAD engine, written to
             ``input_dict["engine"]`` — qt-designer reads it from there and
             substitutes it into every model input spelled ``use_global``.
-            One of ``"thermocalc"``, ``"pandat"``, ``"panengine"``,
-            ``"pycalphad"``, ``"prisms"``; anything else is rejected by the
-            backend with ``400 invalid_engine``.  Optional when
+            One of ``"thermocalc"``, ``"pandat"``, ``"pycalphad"``; anything
+            else is rejected by the backend with ``400 invalid_engine``.  Optional when
             *input_dict* already carries an ``engine``; supplying both is an
-            error unless they agree, and supplying neither is an error too.
+            error unless they agree.  Omit both when no model defers to the
+            job-level engine; if one does, the backend refuses the job with
+            ``400 missing_engine``.
         folder : str
             UUID of the job folder this job belongs to.
         name : str | None
@@ -265,7 +266,7 @@ class JobResource(ReadOnlyResource):
         ------
         ICMDValidationError
             If *engine* and a non-empty ``input_dict["engine"]`` disagree, if
-            neither supplies an engine, if ``input_dict["engine"]`` holds
+            ``input_dict["engine"]`` holds
             something other than a string, or if a model named by name alone
             matches more than one catalog model.
         """
@@ -285,12 +286,10 @@ class JobResource(ReadOnlyResource):
                 "Pass one or the other, or make them agree."
             )
         resolved = engine or document_engine
-        if resolved is None:
-            raise ICMDValidationError(
-                "No engine given: pass engine= or set input_dict['engine'] "
-                "(thermocalc, pandat, panengine, pycalphad, prisms)."
-            )
-        inputs["engine"] = resolved
+        if resolved is not None:
+            inputs["engine"] = resolved
+        else:
+            inputs.pop("engine", None)
         # Before the advisory, which needs a uuid per model to fetch a contract,
         # and regardless of ``check`` -- completing the reference is what makes
         # the document submittable, not a check on it.
@@ -432,9 +431,10 @@ class JobResource(ReadOnlyResource):
         Returns
         -------
         str | None
-            The terminal status reached -- ``"failed"`` and ``"cancelled"``
-            are terminal too, so a caller that needs the job to have *worked*
-            must check this. ``None`` only when polling was interrupted.
+            The terminal status reached -- ``"failed"``, ``"partial"``,
+            ``"cancelled"`` and ``"aborted"`` are terminal too, so a caller that
+            needs the job to have *worked* must check this. ``None`` only when
+            polling was interrupted.
 
         Raises
         ------
@@ -646,7 +646,7 @@ class JobResource(ReadOnlyResource):
     # -----------------------------------------------------------------
 
     def resubmit(self, uuid: str) -> dict:
-        """Re-run a completed/failed/cancelled job as-is (``POST {uuid}/resubmit``).
+        """Re-run a successful/failed/partial/cancelled/aborted job (``POST {uuid}/resubmit``).
 
         Takes no inputs, because the endpoint accepts none: it declares no request
         body and re-resolves the job's *stored* ``input_dict`` against the owning

icmd/cli/__init__.py

@@ -5,6 +5,7 @@ Entry point: ``icmd`` (installed via ``[project.scripts]``).
 
 from __future__ import annotations
 
+import contextlib
 from typing import Any
 
 import click
@@ -23,7 +24,7 @@ from icmd.version import __version__
 from .account import agent_usage, register_account_commands
 from .auth import CLIAuthenticator
 from .auth_status import auth_cmd
-from .client import _build_account_client
+from .client import _build_account_client, build_client
 from .commands import (
     _domain_option,
     _format,
@@ -139,12 +140,21 @@ def login() -> None:
 @cli.command()
 @_domain_option
 def logout() -> None:
-    """Clear cached credentials for an ICMD® instance."""
+    """Sign out of an ICMD® instance and clear its cached credentials."""
     ctx = click.get_current_context()
-    normalized = normalize_domain(_require_domain(ctx))
-    # Straight to the store, not through ``ICMD.logout``: that path treats a
-    # developer-token client differently on purpose.
-    CredentialManager().clear_domain_credentials(normalized)
+    domain = _require_domain(ctx)
+    normalized = normalize_domain(domain)
+    store = CredentialManager()
+    # Revoke a saved login on the server first, or its refresh token stays
+    # usable until it expires. Gated on a stored refresh token so that with
+    # nothing saved no client is built (no request, no prompt). Best effort:
+    # the local clear runs whatever the server does, Ctrl-C included.
+    try:
+        if store.get_refresh_token(normalized):
+            with contextlib.suppress(Exception):
+                build_client(domain).logout(clear_saved_credentials=True)
+    finally:
+        store.clear_domain_credentials(normalized)
     write_output({"status": "ok", "domain": normalized}, fmt=_format(ctx))
 
 

icmd/cli/account.py

@@ -371,7 +371,10 @@ def invite_cancel(uuid: str, yes: bool) -> None:
 @click.command("usage")
 @_global_options
 def agent_usage() -> None:
-    """Get the group's monthly ICMD® Assist token usage.
+    """Get the group's ICMD® Assist credit balance.
+
+    Prints ``granted`` / ``used`` / ``balance`` / ``month_used`` (credits) and
+    ``status``; ``null`` values mean the group is unmetered.
 
     Unlike the account commands, this is group-scoped: it honours ``--group``
     and injects ``owner_group`` (the backend gates on group-admin membership).

icmd/cli/commands.py

@@ -1148,8 +1148,8 @@ def _make_submit_cmd(path: str) -> click.Command:
         default=None,
         help=(
             "Design-level CALPHAD engine written to input_dict['engine'] "
-            "(thermocalc, pandat, panengine, pycalphad, prisms). Omit when "
-            "the input_dict already carries one."
+            "(thermocalc, pandat, pycalphad). Omit when the input_dict "
+            "already carries one or no model defers to the job-level engine."
         ),
     )
     @click.option("--folder", required=True, help="UUID of the destination job folder.")

icmd/client.py

@@ -148,11 +148,9 @@ class ICMD:
     def _save_credentials(self) -> None:
         """Persist the credentials produced by an interactive login.
 
-        Only ever called after an interactive flow, and deliberately so: it
-        writes ``self._session.refresh_token``, which a *refresh* has replaced
-        with the server's rotated token.  Persisting a rotation would roll the
-        backend's absolute session cap forward on every refresh, so the refresh
-        path saves the access token alone (:meth:`_cache_access_token`).
+        Only ever called after an interactive flow: it replaces the whole
+        record unconditionally, whereas a refresh must write only while the
+        record still holds the token it presented (:meth:`_cache_access_token`).
         """
         issued = self._session.refresh_token
         self._credentials.save_domain_credentials(
@@ -167,8 +165,9 @@ class ICMD:
     def _cache_access_token(self, refresh_token: str | None = None) -> None:
         """Cache the session's access token for the next process to reuse.
 
-        Writes only the access-token fields — never a refresh token — which is
-        what keeps a rotated token off disk.
+        A refresh token the server rotated in exchange for *refresh_token* is
+        written with it, in the same compare-and-swap, so the next process
+        presents the current token rather than a superseded one.
 
         Parameters
         ----------
@@ -185,11 +184,13 @@ class ICMD:
         """
         if not self._session.has_valid_token():
             return
+        current = self._session.refresh_token
         self._credentials.save_access_token(
             self._session.domain,
             self._session.access_token,
-            expires_at=self._session.access_token_expires_at,
+            expires=self._session.access_token_expires_at,
             expected_refresh_token=refresh_token,
+            rotated_refresh_token=current if current and current != refresh_token else None,
         )
 
     def _adopt_cached_access_token(self) -> bool:
@@ -347,8 +348,11 @@ class ICMD:
         """Clear cached credentials for a domain.
 
         Removes the whole record — refresh token and cached access token
-        alike — unconditionally: this is the explicit sign-out path, not a
-        reaction to a token the server rejected.
+        alike — unconditionally, not as a reaction to a token the server
+        rejected.  Local only: the server session stays live; use
+        :meth:`logout` to end it.  Processes already running on that login
+        may then sign it out, since each rotates its refresh token on its
+        own once the record is gone.
 
         Can be called without an ``ICMD`` instance, which is useful when
         instantiation itself fails (e.g. after a server-side auth-method
@@ -506,10 +510,13 @@ class ICMD:
         Parameters
         ----------
         clear_saved_credentials : bool
-            Also clear the stored refresh token, so the next client
-            authenticates interactively.  The cached access token is dropped
-            either way — it belongs to the session just ended, and leaving it
-            behind would let another process keep using it.
+            Also clear the stored refresh token.  Every refresh token of a
+            login belongs to the session just ended, so once the server has
+            ended it the stored one is dead either way; clearing it only spares
+            the next client one rejected refresh before it authenticates
+            interactively.  The cached access
+            token is dropped either way — it belongs to the session just ended,
+            and leaving it behind would let another process keep using it.
 
         Notes
         -----

icmd/compose.py

@@ -93,11 +93,11 @@ def compose_input_dict(
 
     ``databases`` and ``engine`` are the design-level values, written at the top
     of the document rather than on any one model: a sequence of wire mappings or
-    :class:`~icmd.types.Database` objects, and one of the catalog engine names
-    (``thermocalc``, ``pandat``, ``panengine``, ``pycalphad``, ``prisms``). They
-    are what a model input spelled ``use_global`` resolves against. Omitting
-    either emits no key for it, which is what leaves the value unset -- an empty
-    list or an empty string reads downstream as no value at all.
+    :class:`~icmd.types.Database` objects, and one of the CALPHAD engine names
+    ``thermocalc``, ``pandat``, ``pycalphad``. They are what a model input
+    spelled ``use_global`` resolves against. Omitting either emits no key for
+    it, which is what leaves the value unset -- an empty list or an empty string
+    reads downstream as no value at all.
 
     :class:`~icmd.types.FromVariable` and :class:`~icmd.types.FromModel` hold
     the object they reference, and resolve here to the variable's name and the

icmd/core/credentials.py

@@ -41,7 +41,7 @@ Per-domain record::
 
     {
       "auth_method": "SAML",              # required for auth-method detection
-      "refresh_token": "…",               # long-lived; never rotated on disk
+      "refresh_token": "…",               # long-lived; replaced when a refresh rotates it
       "access_token": "…",                # optional cache, short-lived
       "access_token_expires_at": "…",     # absolute UTC ISO-8601 timestamp
       "saved_at": "…"
@@ -717,18 +717,15 @@ class CredentialManager:
         domain: str,
         access_token: str,
         *,
-        expires_in: float | None = None,
-        expires_at: datetime | None = None,
+        expires: float | datetime | None = None,
         expected_refresh_token: str | None = None,
+        rotated_refresh_token: str | None = None,
     ) -> bool:
-        """Cache an access token for *domain* without touching the refresh token.
+        """Cache an access token for *domain*, with the refresh token rotated beside it.
 
         This is the only writer of the access-token fields, and it merges into
-        the existing record rather than replacing it.  That is deliberate: the
-        stored refresh token must stay exactly as it is on disk, because the
-        server mints a *new* refresh token on every exchange and persisting the
-        rotation would roll the backend's absolute session cap forward
-        indefinitely.
+        the existing record rather than replacing it, so the auth method and
+        the rest of the record survive.
 
         Parameters
         ----------
@@ -736,11 +733,10 @@ class CredentialManager:
             Normalised ICMD domain the token belongs to.
         access_token : str
             The access token to cache.
-        expires_in : float | None
-            Lifetime in seconds as reported by the server, measured from now.
-        expires_at : datetime | None
-            Absolute expiry; wins over *expires_in* when both are given.  A
-            naive value is interpreted as UTC.
+        expires : float | datetime | None
+            A number is the lifetime in seconds as reported by the server,
+            measured from now; a datetime is the absolute expiry, and a naive
+            one is interpreted as UTC.
         expected_refresh_token : str | None
             When given, cache only while the stored refresh token is still
             exactly this value — the compare-and-swap counterpart to
@@ -751,6 +747,12 @@ class CredentialManager:
             would resurrect a signed-out record (an access-token-only leftover
             that the next process happily adopts) or file one account's token
             under another's.  ``None`` merges unconditionally.
+        rotated_refresh_token : str | None
+            The refresh token the server returned with *access_token*, when it
+            differs from the one presented.  Written in the same rewrite, after
+            the *expected_refresh_token* check, so both tokens land or neither
+            does.  A failed write is logged at WARNING: the stored token is then
+            one the server has already superseded.
 
         Returns
         -------
@@ -765,24 +767,26 @@ class CredentialManager:
         Raises
         ------
         ValueError
-            If neither *expires_in* nor *expires_at* is given.
+            If *expires* is not given.
         """
-        if expires_in is None and expires_at is None:
-            raise ValueError("save_access_token requires either expires_in or expires_at")
+        if expires is None:
+            raise ValueError("save_access_token requires expires")
 
         if not access_token or not isinstance(access_token, str):
             logger.debug("Refusing to cache an empty access token for %s", domain)
             return False
 
-        resolved = self._resolve_expiry(expires_in, expires_at)
+        resolved = self._resolve_expiry(expires)
         if resolved is None:
             logger.debug("Access token for %s has no usable expiry; not caching", domain)
             return False
 
         stamp = resolved.isoformat()
         canonical = canonical_domain(domain)
+        attempted = False
 
         def mutate(records: dict[str, Any]) -> bool:
+            nonlocal attempted
             # Folded before the compare-and-swap, so the token compared against
             # is the one this domain's single surviving record holds.  Refusing
             # below writes nothing and discards the fold with it; the next
@@ -804,23 +808,32 @@ class CredentialManager:
                 records[canonical] = record
             record[_ACCESS_TOKEN_KEY] = access_token
             record[_ACCESS_TOKEN_EXPIRES_AT_KEY] = stamp
+            if rotated_refresh_token:
+                record[_REFRESH_TOKEN_KEY] = rotated_refresh_token
+            attempted = True
             return True
 
-        return self._mutate_store(mutate)
+        saved = self._mutate_store(mutate)
+        if attempted and not saved and rotated_refresh_token:
+            logger.warning(
+                "Could not save the rotated refresh token for %s; this process's next "
+                "refresh and any later process will present a superseded one, which "
+                "signs the login out.",
+                domain,
+            )
+        return saved
 
     @staticmethod
-    def _resolve_expiry(expires_in: float | None, expires_at: datetime | None) -> datetime | None:
-        """Resolve the two expiry forms into one absolute UTC timestamp."""
-        if expires_at is not None:
-            if not isinstance(expires_at, datetime):
-                return None
-            return expires_at.replace(tzinfo=UTC) if expires_at.tzinfo is None else expires_at
+    def _resolve_expiry(expires: float | datetime) -> datetime | None:
+        """Resolve either expiry form into one absolute UTC timestamp."""
+        if isinstance(expires, datetime):
+            return expires.replace(tzinfo=UTC) if expires.tzinfo is None else expires
 
-        if not isinstance(expires_in, int | float) or isinstance(expires_in, bool):
+        if not isinstance(expires, int | float) or isinstance(expires, bool):
             return None
-        if expires_in <= 0:
+        if expires <= 0:
             return None
-        return datetime.now(UTC) + timedelta(seconds=float(expires_in))
+        return datetime.now(UTC) + timedelta(seconds=float(expires))
 
     def _mutate_store(self, mutate: Callable[[dict[str, Any]], bool]) -> bool:
         """Read, mutate, and atomically rewrite the store under the credential lock.

icmd/core/session.py

@@ -9,6 +9,7 @@ this module only manages token state.
 
 from __future__ import annotations
 
+import logging
 import os
 import re
 import warnings
@@ -60,6 +61,8 @@ if TYPE_CHECKING:
     from .constants import HTTPMethod
     from .contracts import ContractClient
 
+logger = logging.getLogger(__name__)
+
 
 class ResourceClient(Protocol):
     """Structural type for objects that can make JSON API requests."""
@@ -622,6 +625,16 @@ class BearerAuth(AuthBase):
         return r
 
 
+def _no_auth(r: requests.PreparedRequest) -> requests.PreparedRequest:
+    """Send one request without the session's bearer.
+
+    Passed as a per-request ``auth=``, which displaces ``Session.auth``;
+    ``auth=None`` would not, since ``requests`` falls back to the session's.
+    """
+    r.headers.pop("Authorization", None)
+    return r
+
+
 # ---------------------------------------------------------------------------
 # Session
 # ---------------------------------------------------------------------------
@@ -708,7 +721,6 @@ class Session:
     EXCLUDED_ENDPOINTS: ClassVar[set[str]] = {
         LOGIN,
         AUTH_REFRESH,
-        AUTH_LOGOUT,
         MFA_VERIFY,
         MFA_EMAIL_GENERATE,
         SAML_LOGIN,
@@ -716,6 +728,11 @@ class Session:
         PUBLIC_CONFIG,
     }
 
+    #: ``AllowAny`` endpoints that never carry the bearer: DRF rejects a stale one
+    #: before the view runs.  The refresh POST opts out itself in
+    #: :meth:`refresh_access_token`; everything else, logout included, keeps it.
+    _BEARERLESS_ENDPOINTS: ClassVar[frozenset[str]] = frozenset({LOGIN, PUBLIC_CONFIG})
+
     def __init__(self, domain: str) -> None:
         """Initialise the session with a validated domain.
 
@@ -910,6 +927,7 @@ class Session:
                 f"{self.api_root}/{AUTH_REFRESH}/",
                 json={"refresh_token": self._refresh_token},
                 timeout=self._REFRESH_TIMEOUT,
+                auth=_no_auth,
             )
         except requests.RequestException as exc:
             # Nothing came back, so nothing implicates the stored token.
@@ -1026,6 +1044,9 @@ class Session:
 
             if "timeout" not in kwargs:
                 kwargs["timeout"] = self._timeout
+            if endpoint in self._BEARERLESS_ENDPOINTS:
+                # A default, so a caller's own ``auth=`` still wins.
+                kwargs.setdefault("auth", _no_auth)
 
             renewal_failure = self._renew_expired_token(endpoint)
 
@@ -1143,15 +1164,11 @@ class Session:
 
         # The server already refused this exact access token on a 401 that a
         # refresh did not fix, so exchanging again cannot help — and would not
-        # be free: the on-disk refresh token is deliberately never rotated, so
-        # every attempt presents the same one and lands in the same
-        # ``(client IP, sha256(refresh token))`` throttle bucket.  Without this,
-        # a 401 that is not about expiry (an authorization failure, a proxy
-        # stripping ``Authorization``) costs one refresh POST per *request* and
-        # exhausts the bucket after 30 — the same refresh lockout the
-        # empty-token guard above prevents, reached by another door.  No reset
-        # is needed: the guard compares against the token currently held, so
-        # any path that installs a new one clears it.
+        # be free.  Without this, a 401 that is not about expiry (an
+        # authorization failure, a proxy stripping ``Authorization``) costs one
+        # refresh POST per *request*, each counted by the server's refresh
+        # throttle.  No reset is needed: the guard compares against the token
+        # currently held, so any path that installs a new one clears it.
         if self._access_token and self._access_token == self._refresh_rejected_token:
             return response
 
@@ -1306,18 +1323,34 @@ class Session:
     # -----------------------------------------------------------------
 
     def logout(self) -> None:
-        """Logout from the server and clear in-memory tokens.
+        """Revoke the server session and clear in-memory tokens.
 
-        Returns silently — callers decide how to communicate success.
+        The server revokes the session named by the bearer, so the POST takes
+        the same renew-then-send path as any authenticated request, including
+        the single refresh-and-retry on a ``401``.  Best effort: it never
+        raises, and the outcome is logged at DEBUG — callers decide how to
+        communicate success.
         """
         try:
             if self._access_token:
-                self._raw_request(
-                    "POST",
-                    f"{self.api_root}/{AUTH_LOGOUT}/",
-                    timeout=5,
-                )
-        except Exception:
-            pass
+                self._renew_expired_token(AUTH_LOGOUT)
+                if (
+                    self._refresh_coordinator is not None
+                    and self._proactive_renewal
+                    and self.is_token_expired()
+                ):
+                    # Renewal had its chance and failed; the server would only
+                    # answer this token with a 401.
+                    logger.debug("Logout skipped: the access token expired and was not renewed")
+                else:
+                    url = f"{self.api_root}/{AUTH_LOGOUT}/"
+                    response = self._raw_request("POST", url, timeout=5)
+                    if response.status_code == HTTPStatus.UNAUTHORIZED:
+                        response = self._retry_on_unauthorized(
+                            response, AUTH_LOGOUT, "POST", url, timeout=5
+                        )
+                    logger.debug("Logout answered HTTP %s", response.status_code)
+        except Exception as exc:
+            logger.debug("Logout request failed: %s", exc)
 
         self.clear_tokens()

icmd/types.py

@@ -22,6 +22,7 @@ import csv
 import math
 from collections.abc import Mapping, Sequence
 from copy import deepcopy
+from decimal import Decimal
 from io import StringIO
 from typing import TYPE_CHECKING, Any, Protocol, Self, runtime_checkable
 
@@ -458,6 +459,9 @@ class DatasetCompositionalVariable(_Envelope):
     per element -- nothing downstream reads a dataset reference on the
     composition itself. :meth:`DatasetSource.composition` mints the composition
     and its variables together, which is the only way they stay consistent.
+    Constructing one here normalizes nothing and qt-designer samples on the
+    composition's own unit rather than the one labelled here, so fraction values
+    are unsupported: express them in percent through that method instead.
 
     The component is keyed ``name`` on the wire: that is the key the sampler
     matches against the composition's components.
@@ -550,6 +554,49 @@ _BALANCE = "bal"
 #: 9958180, lines 106-109).
 _PERCENT_UNITS = frozenset({"mass_percent", "mole_percent"})
 
+#: The unit a fraction-labelled dataset's cells are in once expressed in
+#: percent. A dataset may be labelled in fractions and a job may not, so these
+#: are read off the dataset rather than added to :data:`_PERCENT_UNITS`.
+_FRACTION_TO_PERCENT = {"mass_fraction": "mass_percent", "mole_fraction": "mole_percent"}
+
+
+class _CompositionUnitUnset:
+    """The type of :data:`_COMPOSITION_UNIT_UNSET`, so it renders as prose.
+
+    ``inspect.signature`` renders a default by ``repr``, so a bare ``object()``
+    puts a memory address in :meth:`DatasetSource.composition`'s signature --
+    in ``help()`` and in every IDE tooltip on a public method.
+    """
+
+    def __repr__(self) -> str:
+        """Return what the signature shows where no unit was passed."""
+        return "<from the dataset>"
+
+
+#: :meth:`DatasetSource.composition`'s "not given" default, and nothing else's.
+#: Not ``None`` (:data:`_UNSET`): a plain parameter keeps no record of what the
+#: caller passed, the way a Pydantic field's ``model_fields_set`` does, so
+#: ``composition_unit=None`` is a value passed -- refused rather than resolved
+#: from the dataset.
+_COMPOSITION_UNIT_UNSET: Any = _CompositionUnitUnset()
+
+
+def _as_percent(values: list[_Number | str]) -> list[_Number | str]:
+    """Return one composition column's fraction cells in percent, exactly.
+
+    ``Decimal(str(value)) * 100`` rather than ``value * 100``: the web app
+    multiplies in BigNumber, so ``0.07`` becomes ``7`` there and must not become
+    ``7.000000000000001`` here. Neither side scales the decimal the CSV cell was
+    written with -- both round it through a binary float first (``Number(value)``
+    there, :func:`_composition_values` here, and :func:`_as_numbers` before it
+    where the whole column parses) -- so what this buys is that the two agree,
+    cell for cell. ``bal`` markers are the strings here, and pass through
+    untouched.
+    """
+    return [
+        value if isinstance(value, str) else float(Decimal(str(value)) * 100) for value in values
+    ]
+
 
 def _composition_values(column: str, values: list[_Number | str]) -> list[_Number | str]:
     """Return one composition column as numbers, keeping its ``bal`` markers.
@@ -564,15 +611,75 @@ def _composition_values(column: str, values: list[_Number | str]) -> list[_Numbe
             coerced.append(_BALANCE)
             continue
         try:
-            coerced.append(float(value))
+            number = float(value)
         except ValueError:
             raise ValueError(
                 f"Composition column {column!r} holds {value!r}, which is neither a "
                 f"number nor the {_BALANCE!r} balance marker."
             ) from None
+        # ``float`` reads ``nan`` and ``inf`` and ``Decimal`` scales them, so
+        # unguarded the balance element's remainder of 100 comes out ``nan`` and
+        # the cell reaches the wire as JSON no strict parser accepts.
+        if not math.isfinite(number):
+            raise ValueError(
+                f"Composition column {column!r} holds {value!r}, which is not a finite "
+                "number. Drop the row, or fill the cell in."
+            )
+        coerced.append(number)
     return coerced
 
 
+def _resolve_composition_unit(
+    dataset_name: str, declared_unit: str | None, passed_unit: str
+) -> tuple[str, str | None]:
+    """Return the percent unit a composition carries, and the one its cells are in.
+
+    The second is the percent unit a fraction-labelled dataset's cells reach
+    once scaled, and ``None`` for every other label, including none -- which is
+    what tells the caller whether to scale them at all.
+
+    ``passed_unit`` left at :data:`_COMPOSITION_UNIT_UNSET` resolves from the
+    dataset: a fraction label through its matching percent unit, a percent label
+    as it stands, ``mass_percent`` only where the dataset declares nothing at
+    all. A label this SDK cannot read is refused with the dataset blamed -- an
+    empty one included, since a dataset carrying an empty label has declared a
+    value -- where a unit passed is refused with the caller blamed.
+    """
+    scaled_unit = _FRACTION_TO_PERCENT.get(declared_unit or "")
+    from_dataset = passed_unit is _COMPOSITION_UNIT_UNSET
+    composition_unit = passed_unit
+    if from_dataset:
+        # A fraction label resolves through its scaled percent unit; every
+        # other label stands and is checked below, as a passed one is.
+        declared = scaled_unit or declared_unit
+        composition_unit = "mass_percent" if declared is None else declared
+    if composition_unit not in _PERCENT_UNITS:
+        if from_dataset:
+            raise ValueError(
+                f"Dataset {dataset_name!r} declares composition_unit "
+                f"{declared_unit!r}, which is neither one of "
+                f"{sorted(_PERCENT_UNITS)} nor a fraction of one, so its cells cannot "
+                "be read. Pass the unit they are in: "
+                "composition(name, composition_unit=...)."
+            )
+        raise ValueError(
+            f"composition_unit must be one of {sorted(_PERCENT_UNITS)}; got "
+            f"{composition_unit!r}. The balance element is filled in as what is left "
+            "of 100, which is a wrong number in any other unit."
+        )
+    # Both units are now one of the two in ``_PERCENT_UNITS``, so they differ
+    # only in basis. Scaling the cells cannot change what they measure, so a
+    # caller naming the other basis has the dataset wrong.
+    if scaled_unit is not None and composition_unit != scaled_unit:
+        raise ValueError(
+            f"Dataset {dataset_name!r} is labelled {declared_unit!r}, so its "
+            f"cells are {scaled_unit!r} once expressed in percent; "
+            f"composition_unit={composition_unit!r} is the other basis. Pass "
+            f"{scaled_unit!r}, or leave composition_unit unset."
+        )
+    return composition_unit, scaled_unit
+
+
 class DatasetSource:
     """One uploaded dataset, read once, minting variables from its columns.
 
@@ -598,6 +705,13 @@ class DatasetSource:
         Its name, carried onto every variable minted here.
     columns : Mapping[str, list[int | float | str]]
         The parsed columns, by column name.
+    composition_unit : str | None
+        The unit the dataset itself declares its composition columns are in, as
+        :meth:`load` reads it off the dataset's metadata. :meth:`composition`
+        scales fraction cells on the strength of it, and resolves the
+        composition's own unit from it when none is passed. Omit it on a
+        hand-built source, which then behaves as a dataset carrying no unit
+        does.
     """
 
     def __init__(
@@ -605,16 +719,29 @@ class DatasetSource:
         dataset_uuid: str,
         dataset_name: str,
         columns: Mapping[str, list[_Number | str]],
+        *,
+        composition_unit: str | None = None,
     ) -> None:
         self.uuid = dataset_uuid
         self.name = dataset_name
         self._columns = dict(columns)
+        self._composition_unit = composition_unit
 
     @classmethod
     def load(cls, client: "ICMD", dataset_uuid: str) -> Self:
         """Fetch one dataset and return the source minting its variables."""
         body = client.workspace.dataset.get(dataset_uuid, inject_group=True)
-        return cls(dataset_uuid, body["name"], _parse_columns(body["csv_data"]))
+        # This server always sends ``metadata`` as a dict; the inner ``dataset``
+        # block is the one that is really null, on a dataset saved without a
+        # unit. The outer guard is insurance for a tenant on an older backend.
+        metadata = body.get("metadata") or {}
+        declared_unit = (metadata.get("dataset") or {}).get("composition_unit")
+        return cls(
+            dataset_uuid,
+            body["name"],
+            _parse_columns(body["csv_data"]),
+            composition_unit=declared_unit,
+        )
 
     def _column(self, column: str) -> list[_Number | str]:
         """Return one column's values, naming the ones there are when it is absent."""
@@ -641,7 +768,7 @@ class DatasetSource:
         self,
         name: str,
         *,
-        composition_unit: str = "mass_percent",
+        composition_unit: str = _COMPOSITION_UNIT_UNSET,
         columns: Sequence[str] | None = None,
     ) -> tuple["Composition", list["DatasetCompositionalVariable"]]:
         """Resolve this dataset's compositions into the pair the wire accepts.
@@ -653,16 +780,29 @@ class DatasetSource:
         app does too: a composition that only references a dataset is read by
         nothing, and the job runs with no composition columns at all.
 
+        The dataset's declared label decides the **cells**: a ``mass_fraction``
+        or ``mole_fraction`` label has every numeric cell scaled by 100, since
+        no fraction unit reaches the wire at all; a percent label leaves them as
+        they stand. ``composition_unit`` decides the **label** the composition
+        carries and nothing else -- passing one does not turn that scaling off.
+        Left unset it follows the dataset as well: a fraction label's matching
+        percent unit, a percent label as it stands, ``mass_percent`` for a
+        dataset declaring nothing, and an error for a label this SDK does not
+        know, which passing a unit overrides.
+
+        That unit is cross-checked only where this SDK converts: against a
+        fraction-labelled dataset the other basis is refused, since scaling
+        cannot change what the cells measure. A percent-labelled dataset takes
+        whatever is passed -- the label is free-form metadata the caller may be
+        correcting.
+
         ``columns`` defaults to every column named after an element. Each row
         must mark exactly one balance element with ``bal``, which is what the
         uploaded composition dataset carries.
         """
-        if composition_unit not in _PERCENT_UNITS:
-            raise ValueError(
-                f"composition_unit must be one of {sorted(_PERCENT_UNITS)}; got "
-                f"{composition_unit!r}. The balance element is filled in as what is left "
-                "of 100, which is a wrong number in any other unit."
-            )
+        composition_unit, scaled_unit = _resolve_composition_unit(
+            self.name, self._composition_unit, composition_unit
+        )
         selected = (
             list(columns)
             if columns is not None
@@ -677,6 +817,10 @@ class DatasetSource:
         composition_columns = {
             column: _composition_values(column, self._column(column)) for column in selected
         }
+        if scaled_unit is not None:
+            composition_columns = {
+                column: _as_percent(values) for column, values in composition_columns.items()
+            }
         if not all(composition_columns.values()):
             raise ValueError(
                 f"Dataset {self.name!r} has no rows, so there is no composition to "

icmd/version.py

@@ -1 +1 @@
-__version__ = "3.3.0"
+__version__ = "3.3.5"

{icmd_python-3.3.0.dist-info → icmd_python-3.3.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: icmd-python
-Version: 3.3.0
+Version: 3.3.5
 Summary: Python client app for ICMD®
 Author: QuesTek Innovations LLC
 License-Expression: LicenseRef-Proprietary

{icmd_python-3.3.0.dist-info → icmd_python-3.3.5.dist-info}/RECORD

@@ -1,31 +1,31 @@
 icmd/__init__.py,sha256=BoE6tl0PaBgXqXmL_QjebFos5eOvS91Dj6tjJwolezk,2739
-icmd/client.py,sha256=nqp6MZh2BdT2Qx1cv_Dg306BzvTcHJ1F2Dd0NU1Oh20,22150
-icmd/compose.py,sha256=WaZEF2JcrMbJK90nhGrL-0iyJRyuQgq6Nh1-OgK71K8,6960
+icmd/client.py,sha256=8PXqAskxzkuUwz2wtHYFp9kDAgQlyOxDNbEyVSKayeY,22643
+icmd/compose.py,sha256=V_B4EYuX01oJexnGGvhIwDUKgfx_Fyd0lPVvSRUoH8c,6931
 icmd/links.py,sha256=I8v8_xhI6lbUwrMjIUcYYcqKUi2PIPm6zQ7mXYP9A5E,6827
 icmd/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-icmd/types.py,sha256=pMAaQaMHolaiAYh_aBG0NZWf5yiqxY5XbRmekxCUREU,72026
-icmd/version.py,sha256=MPSbkJS_-QSkLK7sMlFXFf5iWlbcSL18Dj2ZiMCtS9c,22
+icmd/types.py,sha256=LizuU96hF7VRjl4OlyF0oPcao1cKe795YXEsLW9fKI4,79496
+icmd/version.py,sha256=QO4UWv5ZUgBpuBbLNKWKecIDPPTa5HfOdEYEe2q2Afo,22
 icmd/_vendor/__init__.py,sha256=VFA4EQd2l76sxgkHPUpgzZavFF6kFdpq9v71AZsPIdQ,579
 icmd/_vendor/assembler.py,sha256=U8VPlqN1605RJQ5qMVoNrL3uJ7NpUe8BVmD8q06IN5w,5282
 icmd/apps/__init__.py,sha256=ak2ch1UU-qaiyOT1eCdRwqSI0Avhzyw5DLkw-U2ivQQ,659
 icmd/apps/account.py,sha256=BWDO0Zysv0ygLVhbeIk82BjsvuDVb_vBdu6jqBPw3tc,14557
-icmd/apps/agent.py,sha256=oSgIjchkcWi83-1Bsqywe2yqzfz0cM0XTyidQPoo7IM,8037
+icmd/apps/agent.py,sha256=MmWuH1sYqo-hOhNNuTwh930H_BFXs7oMP0QgyzaC0Iw,8387
 icmd/apps/base.py,sha256=y4uvIiomCLia89UL2rV4oufLBUQaODZ8qwl-EwDtjhM,18979
 icmd/apps/constants.py,sha256=5xoIwFNGOaAp2cHAlVDlbzJ7ObQHYXJgVGMBfNLCHzI,757
 icmd/apps/documents.py,sha256=8_wFc7NLUFQMYZA5hqsciXniHECZEWS-egX_ni8F4LE,3720
-icmd/apps/jobs.py,sha256=TVSSR6HLmQuSc0mA0Zrax_LclncOmmAMfn7ITf-aT9E,35319
+icmd/apps/jobs.py,sha256=mUwV1wD4NlxOuYbK6a2HFZvZOtd1cXt-NQMZnmsYo1c,35282
 icmd/apps/navigation.py,sha256=mbEJG33Z-Nha5txvMpL63sT-UqsgFgZ-NMhTU7L7gI0,3738
 icmd/apps/results.py,sha256=lPs9iBoW49h0HTIYaUIau7QZVok7RdpSeawnxyA0ETU,7246
 icmd/apps/studio.py,sha256=XN6gVCqkTzp7qH9I-UOhW7UJ2RfkGv60H-G7ulkR850,2419
 icmd/apps/suite.py,sha256=04MIHUima_RGfnHyBPjyxcghcIMHhgDLWPcex6tIWls,2761
 icmd/apps/types.py,sha256=jOzykkXWj9e_lk805_ABCC-sWBwIpJGN3HEb2AyQ9vw,1290
 icmd/apps/workspace.py,sha256=BXCOLQo5BMu-okW2Ink8L_FPhU8r7OWy2jDsvilU3Oo,3055
-icmd/cli/__init__.py,sha256=fTmRemUAxPv5eksJEMtajM01WL0mnXEmrGBidkpyEbA,6944
-icmd/cli/account.py,sha256=8TM-zwOUIJVc11IePT0iL7RC7ZoTBBI5oBMIMW6Ms2Q,13723
+icmd/cli/__init__.py,sha256=mBpAlW1BCKglPzdDffTc4uLdr_2Ri7qnVC2I-Q9FjEA,7395
+icmd/cli/account.py,sha256=equTAGWR3NCCMYEPTw4IZKHEtBEdGD8F4Pp8cfiSNoU,13859
 icmd/cli/auth.py,sha256=UFpEf-lLlkbphivgBfd9NxAEqHcCsPmEl-DXet-NStg,3317
 icmd/cli/auth_status.py,sha256=6wkI3Q0c-t8DBOfuPaN_xXEUcL9HLZm1jX4lQ76X3Ag,13505
 icmd/cli/client.py,sha256=3iToPSABFYWWUPn-uDVFAv9GoBWQXP04l2Id_aYgd64,2186
-icmd/cli/commands.py,sha256=AvAvK9VNk7WydcpeB019ZetGDKuJqWN3bwhY3hcpSpc,54828
+icmd/cli/commands.py,sha256=JdEsIlsMvThWaMHbNmOWyESKWRbnpdTt_qxY56RHpxo,54852
 icmd/cli/diagnostics.py,sha256=1fXgKmpUMA5U-_79AzZ0uSibFmDTK_CLCe91YhBnM8s,2747
 icmd/cli/domain.py,sha256=MiGzdKwKaOEvMshsPPJTmdBm7pCTjGM98MOg9RhAL_k,874
 icmd/cli/links.py,sha256=7CMhKUJ-qKQmk2I-KCdn6oF06cdCq0v5jQDGU7gEJ30,14039
@@ -36,15 +36,15 @@ icmd/core/advisory.py,sha256=ErXByq5UgpSGkjIiAjnmVCBLdY76REiU-Ilf_HoJ06Y,20783
 icmd/core/auth.py,sha256=bG6eLbSkmyDWLyprx7NJMDwLTGsOIrsRdBZ3f6vz1vk,29480
 icmd/core/constants.py,sha256=P3a01sDt5WmGYqkp5hu4UqWbMgfp50o6rBV3q9jU4yA,2339
 icmd/core/contracts.py,sha256=0Dw7tq_IxQY5YC4CKtaubJ0Npa4Ae66-sm-0UuqH_no,9901
-icmd/core/credentials.py,sha256=Ow3S3RMfvMJL1iJsm_37ZX8T3spk-Rttt80TmsRhUUI,46297
+icmd/core/credentials.py,sha256=39vyoFH1_MrzD9TpTh4FVPhWbrY5X35zGCS22KeTi_8,46835
 icmd/core/display.py,sha256=RkgJhr2Bfw3-ZjGvE100ddD6oyAAUUAJfBAy6DvX5ik,13060
 icmd/core/exceptions.py,sha256=9iFCw93yZ0Eh1x_6-acPU8pVtaUy7EhSz-h1JkYS4M4,6985
 icmd/core/groups.py,sha256=OFbQce42DLDK0rDAdMbh8H7imNPAkBJMl7o7tbKQ4Iw,7211
 icmd/core/model_classes.py,sha256=lOwTwZzmQ247fddFMjPVo43Z_VZfdPhhM0NI8LfRqlc,40047
-icmd/core/session.py,sha256=JKlvzairnw9ZQBTzN1EyABM2OwgDX98-ZzwpHWa_2Ls,59188
-icmd_python-3.3.0.dist-info/licenses/LICENSE,sha256=644lGvCmDFa5hQl6xdhaYk3o-1oWqPXAIiiQlvqeZdE,1028
-icmd_python-3.3.0.dist-info/METADATA,sha256=NDMgci_LiXhHg7gN0vjCzu4wH6ygTIQ6_m9fN7M7dhM,4919
-icmd_python-3.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-icmd_python-3.3.0.dist-info/entry_points.txt,sha256=CFX537PlyyPQL3Q_3TKUFeiiDSkOAboqaLEy9AIEwVU,39
-icmd_python-3.3.0.dist-info/top_level.txt,sha256=olzM6Z_QEwg7RrFVOnkgO0I2Ps2m7vhSqYQZYeiawcw,5
-icmd_python-3.3.0.dist-info/RECORD,,
+icmd/core/session.py,sha256=_hdA3Yo_dH1A_qRH1xpyEB8sBkUNQKcUywc54WsPZos,60894
+icmd_python-3.3.5.dist-info/licenses/LICENSE,sha256=644lGvCmDFa5hQl6xdhaYk3o-1oWqPXAIiiQlvqeZdE,1028
+icmd_python-3.3.5.dist-info/METADATA,sha256=YXJOLdFBGc9bfWGYDvIWMAKdFNyPH_WSvSWU32oaBxY,4919
+icmd_python-3.3.5.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+icmd_python-3.3.5.dist-info/entry_points.txt,sha256=CFX537PlyyPQL3Q_3TKUFeiiDSkOAboqaLEy9AIEwVU,39
+icmd_python-3.3.5.dist-info/top_level.txt,sha256=olzM6Z_QEwg7RrFVOnkgO0I2Ps2m7vhSqYQZYeiawcw,5
+icmd_python-3.3.5.dist-info/RECORD,,