nexusflow-sdk 0.3.0__py3-none-any.whl

nexusflow_sdk/__init__.py

@@ -0,0 +1,36 @@
+from .client import NexusFlowClient
+from .component import Component, PortRef
+from .connection import Connection
+from .exceptions import APIError, AuthError, NexusFlowError, NotFoundError, ValidationError
+from .job import Job
+from .meta import MetaService
+from .model import Model
+from .result import (
+    ContainerMessage,
+    InspectMessage,
+    LogMessage,
+    PlotMessage,
+    ResultStream,
+    TableMessage,
+)
+
+__all__ = [
+    "APIError",
+    "AuthError",
+    "Component",
+    "Connection",
+    "ContainerMessage",
+    "NexusFlowClient",
+    "NexusFlowError",
+    "InspectMessage",
+    "Job",
+    "LogMessage",
+    "MetaService",
+    "Model",
+    "NotFoundError",
+    "PlotMessage",
+    "PortRef",
+    "ResultStream",
+    "TableMessage",
+    "ValidationError",
+]

nexusflow_sdk/_constraints.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from ._expression import evaluate_condition, evaluate_expression
+
+
+def _constraint_scope(
+    *,
+    value: Any,
+    params: Mapping[str, Any] | None,
+    global_params: Mapping[str, Any] | None,
+    context: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    return {
+        "value": value,
+        "params": dict(params or {}),
+        "global": dict(global_params or params or {}),
+        "context": dict(context or {}),
+    }
+
+
+def validate_constraints(
+    arg_def: Mapping[str, Any],
+    value: Any,
+    *,
+    params: Mapping[str, Any] | None,
+    global_params: Mapping[str, Any] | None = None,
+    context: Mapping[str, Any] | None = None,
+) -> list[str]:
+    constraints = arg_def.get("constraints", [])
+    if not isinstance(constraints, list):
+        return []
+
+    issues: list[str] = []
+    scope = _constraint_scope(
+        value=value,
+        params=params,
+        global_params=global_params,
+        context={
+            **dict(context or {}),
+            "key": arg_def.get("key", ""),
+            "type": arg_def.get("type", ""),
+        },
+    )
+    for constraint in constraints:
+        if not isinstance(constraint, Mapping):
+            continue
+        expr = str(constraint.get("expr", "")).strip()
+        if not expr:
+            continue
+        message = str(constraint.get("message") or "constraint failed")
+        when = str(constraint.get("when", "")).strip()
+        try:
+            if when and not evaluate_condition(when, scope):
+                continue
+            if not bool(evaluate_expression(expr, scope)):
+                issues.append(message)
+        except Exception as exc:
+            issues.append(f"constraint rule failed: {message} ({exc})")
+    return issues

nexusflow_sdk/_expression.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import re
+from types import SimpleNamespace
+from typing import Any, Mapping
+
+
+_NOT_PATTERN = re.compile(r"(?<![=!<>])!(?!=)")
+
+
+def _to_namespace(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return SimpleNamespace(**{key: _to_namespace(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return [_to_namespace(item) for item in value]
+    return value
+
+
+def _equal_text(left: Any, right: Any) -> bool:
+    return str(left) == str(right)
+
+
+def _as_list(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple):
+        return list(value)
+    return [value]
+
+
+def _stable_marker(value: Any) -> str:
+    if isinstance(value, Mapping):
+        return "dict:" + repr(sorted((str(key), _stable_marker(item)) for key, item in value.items()))
+    if isinstance(value, (list, tuple)):
+        return "list:" + repr([_stable_marker(item) for item in value])
+    return f"{type(value).__name__}:{value!r}"
+
+
+def _column(rows: Any, index: Any) -> list[Any]:
+    col_index = int(index)
+    result: list[Any] = []
+    for row in _as_list(rows):
+        if isinstance(row, Mapping):
+            result.append(row.get(col_index, row.get(str(col_index))))
+            continue
+        if isinstance(row, (list, tuple)) and -len(row) <= col_index < len(row):
+            result.append(row[col_index])
+        else:
+            result.append(None)
+    return result
+
+
+def _unique(items: Any) -> bool:
+    seen: set[str] = set()
+    for item in _as_list(items):
+        marker = _stable_marker(item)
+        if marker in seen:
+            return False
+        seen.add(marker)
+    return True
+
+
+def _empty(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, (str, list, tuple, dict, set)):
+        return len(value) == 0
+    return False
+
+
+def _not_empty(value: Any) -> bool:
+    return not _empty(value)
+
+
+def _matches(value: Any, pattern: Any) -> bool:
+    return re.search(str(pattern), "" if value is None else str(value)) is not None
+
+
+def _number(value: Any) -> float:
+    return float(value)
+
+
+def _string(value: Any) -> str:
+    return "" if value is None else str(value)
+
+
+def _transform(expr: str) -> str:
+    transformed = expr.strip()
+    transformed = transformed.replace("&&", " and ")
+    transformed = transformed.replace("||", " or ")
+    transformed = re.sub(r"\btrue\b", "True", transformed, flags=re.IGNORECASE)
+    transformed = re.sub(r"\bfalse\b", "False", transformed, flags=re.IGNORECASE)
+    transformed = re.sub(r"\bnull\b", "None", transformed, flags=re.IGNORECASE)
+    transformed = re.sub(r"\bglobal\b", "global_", transformed)
+    transformed = _NOT_PATTERN.sub(" not ", transformed)
+    return transformed
+
+
+def evaluate_expression(expr: str | None, scope: Mapping[str, Any] | None = None) -> Any:
+    if expr is None:
+        raise ValueError("expression is empty")
+    text = expr.strip()
+    if not text:
+        raise ValueError("expression is empty")
+    transformed = _transform(text)
+    locals_scope = {key: _to_namespace(value) for key, value in (scope or {}).items()}
+    if "global" in locals_scope and "global_" not in locals_scope:
+        locals_scope["global_"] = locals_scope["global"]
+    return eval(
+        transformed,
+        {
+            "__builtins__": {},
+            "equalText": _equal_text,
+            "min": min,
+            "max": max,
+            "abs": abs,
+            "len": len,
+            "empty": _empty,
+            "notEmpty": _not_empty,
+            "column": _column,
+            "unique": _unique,
+            "matches": _matches,
+            "number": _number,
+            "string": _string,
+        },
+        locals_scope,
+    )
+
+
+def evaluate_condition(expr: str | None, scope: Mapping[str, Any] | None = None) -> bool:
+    try:
+        result = evaluate_expression(expr, scope)
+    except Exception:
+        return False
+    return bool(result)

nexusflow_sdk/auth.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import requests
+
+from .exceptions import AuthError
+
+
+@dataclass(slots=True)
+class TokenPair:
+    access_token: str
+    refresh_token: str | None = None
+
+
+class TokenAuth:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        session: requests.Session,
+        access_token: str | None = None,
+        refresh_token: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._session = session
+        self._timeout = timeout
+        self._username = username
+        self._password = password
+        self._tokens = TokenPair(access_token or "", refresh_token)
+
+    @property
+    def access_token(self) -> str | None:
+        return self._tokens.access_token or None
+
+    @property
+    def refresh_token(self) -> str | None:
+        return self._tokens.refresh_token
+
+    @property
+    def authorization_header(self) -> dict[str, str]:
+        if not self.access_token:
+            return {}
+        return {"Authorization": f"Bearer {self.access_token}"}
+
+    @property
+    def can_refresh(self) -> bool:
+        return bool(self.refresh_token or (self._username and self._password))
+
+    def ensure_login(self) -> None:
+        if self.access_token:
+            return
+        if not (self._username and self._password):
+            raise AuthError("No access token or username/password was provided.")
+        self.login(self._username, self._password)
+
+    def login(self, username: str, password: str) -> TokenPair:
+        response = self._session.post(
+            f"{self._base_url}/api/token/",
+            json={"username": username, "password": password},
+            timeout=self._timeout,
+        )
+        payload = _parse_json(response)
+        if response.status_code >= 400:
+            raise AuthError(_extract_error_message(payload, response.text))
+
+        access = payload.get("access") or payload.get("access_token")
+        refresh = payload.get("refresh") or payload.get("refresh_token")
+        if not access:
+            raise AuthError("Token endpoint did not return an access token.")
+        self._username = username
+        self._password = password
+        self._tokens = TokenPair(access, refresh)
+        return self._tokens
+
+    def refresh(self) -> TokenPair:
+        if self.refresh_token:
+            response = self._session.post(
+                f"{self._base_url}/api/token/refresh/",
+                json={"refresh": self.refresh_token},
+                timeout=self._timeout,
+            )
+            payload = _parse_json(response)
+            if response.status_code < 400:
+                access = payload.get("access") or payload.get("access_token")
+                refresh = payload.get("refresh") or payload.get("refresh_token") or self.refresh_token
+                if access:
+                    self._tokens = TokenPair(access, refresh)
+                    return self._tokens
+
+        if self._username and self._password:
+            return self.login(self._username, self._password)
+        raise AuthError("Unable to refresh access token.")
+
+
+def _parse_json(response: requests.Response) -> dict[str, Any]:
+    try:
+        payload = response.json()
+    except ValueError:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _extract_error_message(payload: dict[str, Any], fallback: str) -> str:
+    for key in ("detail", "message", "error", "msg"):
+        value = payload.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return fallback or "Authentication failed."

nexusflow_sdk/client.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+from .auth import TokenAuth
+from .http import HttpClient
+from .job import Job
+from .meta import MetaService
+from .model import Model
+
+
+class NexusFlowClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str | None = None,
+        refresh_token: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        timeout: float = 30.0,
+        session: requests.Session | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        self.auth = TokenAuth(
+            base_url=self.base_url,
+            session=self.session,
+            access_token=token,
+            refresh_token=refresh_token,
+            username=username,
+            password=password,
+            timeout=timeout,
+        )
+        self.http = HttpClient(base_url=self.base_url, auth=self.auth, timeout=timeout, session=self.session)
+        self.meta = MetaService(self.http)
+
+    def __enter__(self) -> "NexusFlowClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self.session.close()
+
+    def login(self, username: str, password: str) -> None:
+        self.auth.login(username, password)
+
+    def list_models(self, **params: Any) -> list[Model]:
+        return Model.list(self, **params)
+
+    def get_model(self, model_id: str) -> Model:
+        return Model.get(self, model_id)
+
+    def create_model(
+        self,
+        *,
+        name: str,
+        workspace_type: str,
+        description: str = "",
+        publicity: str = "private",
+        global_params: dict[str, Any] | None = None,
+    ) -> Model:
+        return Model.create(
+            self,
+            name=name,
+            workspace_type=workspace_type,
+            description=description,
+            publicity=publicity,
+            global_params=global_params,
+        )
+
+    def list_jobs(self, **params: Any) -> list[Job]:
+        return Job.list(self, **params)
+
+    def get_job(self, job_id: str) -> Job:
+        return Job.get(self, job_id)

nexusflow_sdk/component.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Iterable
+
+from ._constraints import validate_constraints
+from ._expression import evaluate_condition
+from .exceptions import ValidationError
+from .types import NodeData, NodeViewStatus, PortDirection, PortType
+
+if TYPE_CHECKING:
+    from .model import Model
+
+
+def default_view_status(position: tuple[float, float] | None = None) -> NodeViewStatus:
+    x, y = position or (0.0, 0.0)
+    return {
+        "flip": False,
+        "angle": 0.0,
+        "size": {"width": 120.0, "height": 80.0},
+        "position": {"x": float(x), "y": float(y)},
+        "zIndex": 0,
+    }
+
+
+def iter_arg_definitions(args_group: Any) -> Iterable[dict[str, Any]]:
+    if not isinstance(args_group, list):
+        return []
+    definitions: list[dict[str, Any]] = []
+    for group in args_group:
+        if not isinstance(group, dict):
+            continue
+        for item in group.get("argsDefinition", []) or []:
+            if isinstance(item, dict):
+                definitions.append(item)
+    return definitions
+
+
+def build_default_params(component_definition: dict[str, Any]) -> dict[str, Any]:
+    defaults: dict[str, Any] = {}
+    for arg_def in iter_arg_definitions(component_definition.get("argsGroup", [])):
+        key = arg_def.get("key")
+        if not key:
+            continue
+        if "defaultValue" in arg_def:
+            defaults[key] = arg_def.get("defaultValue")
+        elif "default" in arg_def:
+            defaults[key] = arg_def.get("default")
+        elif arg_def.get("type") == "table":
+            defaults[key] = []
+        else:
+            defaults[key] = ""
+    return defaults
+
+
+def validate_parameter_value(
+    arg_def: dict[str, Any],
+    value: Any,
+    *,
+    params: dict[str, Any],
+    global_params: dict[str, Any] | None = None,
+    context: dict[str, Any] | None = None,
+    subject: str = "property",
+) -> list[str]:
+    issues: list[str] = []
+    key = arg_def.get("key")
+    label = arg_def.get("label", key)
+    arg_type = arg_def.get("type")
+    prefix = f"{subject} {label}"
+
+    if arg_type in {"real", "integer"}:
+        try:
+            numeric = float(value)
+        except (TypeError, ValueError):
+            issues.append(f"{prefix} must be numeric")
+        else:
+            if arg_type == "integer" and int(numeric) != numeric:
+                issues.append(f"{prefix} must be an integer")
+            minimum = arg_def.get("min")
+            maximum = arg_def.get("max")
+            range_type = str(arg_def.get("rangeType", "CLOSE")).upper()
+            if minimum is not None:
+                if range_type in {"LEFT_OPEN", "OPEN"} and not numeric > float(minimum):
+                    issues.append(f"{prefix} must be > {minimum}")
+                if range_type not in {"LEFT_OPEN", "OPEN"} and not numeric >= float(minimum):
+                    issues.append(f"{prefix} must be >= {minimum}")
+            if maximum is not None:
+                if range_type in {"RIGHT_OPEN", "OPEN"} and not numeric < float(maximum):
+                    issues.append(f"{prefix} must be < {maximum}")
+                if range_type not in {"RIGHT_OPEN", "OPEN"} and not numeric <= float(maximum):
+                    issues.append(f"{prefix} must be <= {maximum}")
+    elif arg_type == "choice":
+        choices = arg_def.get("choices", []) or []
+        allowed = {item.get("key") for item in choices if isinstance(item, dict) and "key" in item}
+        if allowed and value not in allowed:
+            issues.append(f"{prefix} must be one of {sorted(allowed)!r}")
+    elif arg_type == "table":
+        if not isinstance(value, list):
+            issues.append(f"{prefix} must be a list")
+        else:
+            min_row = arg_def.get("minRow")
+            max_row = arg_def.get("maxRow")
+            if min_row is not None and len(value) < int(min_row):
+                issues.append(f"{prefix} must contain at least {min_row} rows")
+            if max_row is not None and len(value) > int(max_row):
+                issues.append(f"{prefix} must contain no more than {max_row} rows")
+    elif arg_type in {"text", "datetime", "signal", "color", "python-script"}:
+        if value is None:
+            issues.append(f"{prefix} cannot be null")
+
+    if not issues:
+        issues.extend(
+            f"{prefix} {item}"
+            for item in validate_constraints(
+                arg_def,
+                value,
+                params=params,
+                global_params=global_params,
+                context=context,
+            )
+        )
+    return issues
+
+
+@dataclass(slots=True)
+class PortRef:
+    component: "Component"
+    key: str
+    name: str
+    type: PortType
+    condition: str
+    direction: PortDirection | None = None
+
+    @property
+    def is_active(self) -> bool:
+        return evaluate_condition(self.condition or "true", {**self.component.params, "context": {}})
+
+
+class Component:
+    def __init__(
+        self,
+        *,
+        model: "Model",
+        component_id: str,
+        class_id: str,
+        label: str,
+        params: dict[str, Any] | None = None,
+        pins_label: dict[str, str] | None = None,
+        view_status: NodeViewStatus | None = None,
+    ) -> None:
+        self.model = model
+        self.id = component_id
+        self.class_id = class_id
+        self.label = label
+        self.params = dict(params or {})
+        self.pins_label = dict(pins_label or {})
+        self.view_status = view_status or default_view_status()
+
+    @property
+    def definition(self) -> dict[str, Any]:
+        return self.model.client.meta.get_component_definition(self.model.workspace_type, self.class_id)
+
+    @property
+    def commands(self) -> Any:
+        return self.definition.get("commands", [])
+
+    @property
+    def ports(self) -> list[PortRef]:
+        ports: list[PortRef] = []
+        for port in self.definition.get("portsDefinition", []) or []:
+            if not isinstance(port, dict):
+                continue
+            ports.append(
+                PortRef(
+                    component=self,
+                    key=str(port.get("key", "")),
+                    name=str(port.get("name", port.get("label", port.get("key", "")))),
+                    type=port.get("type", "FLUID"),
+                    condition=str(port.get("condition", "true")),
+                    direction=port.get("direction"),
+                )
+            )
+        return ports
+
+    @property
+    def active_ports(self) -> list[PortRef]:
+        return [port for port in self.ports if port.is_active]
+
+    def port(self, key: str) -> PortRef:
+        for port in self.ports:
+            if port.key == key:
+                return port
+        raise ValidationError(f"Component {self.id} does not have port {key!r}.")
+
+    def set_param(self, key: str, value: Any) -> "Component":
+        self.params[key] = value
+        return self
+
+    def set_params(self, **kwargs: Any) -> "Component":
+        self.params.update(kwargs)
+        return self
+
+    def get_param(self, key: str, default: Any = None) -> Any:
+        return self.params.get(key, default)
+
+    def set_pin_label(self, port_key: str, label: str) -> "Component":
+        self.port(port_key)
+        self.pins_label[port_key] = label
+        return self
+
+    def get_pin_label(self, port_key: str, default: str = "") -> str:
+        return str(self.pins_label.get(port_key, default))
+
+    def signal_values(self) -> dict[str, str]:
+        values: dict[str, str] = {}
+        for arg_def in iter_arg_definitions(self.definition.get("argsGroup", [])):
+            if arg_def.get("type") != "signal":
+                continue
+            key = arg_def.get("key")
+            if not key:
+                continue
+            if not evaluate_condition(arg_def.get("condition", "true"), {**self.params, "context": {}}):
+                continue
+            value = str(self.params.get(key, "")).strip()
+            if value:
+                values[key] = value
+        return values
+
+    def validate(self) -> list[str]:
+        issues: list[str] = []
+        for arg_def in iter_arg_definitions(self.definition.get("argsGroup", [])):
+            key = arg_def.get("key")
+            if not key:
+                continue
+            if not evaluate_condition(arg_def.get("condition", "true"), {**self.params, "context": {}}):
+                continue
+            value = self.params.get(key)
+            issues.extend(
+                validate_parameter_value(
+                    arg_def,
+                    value,
+                    params=self.params,
+                    global_params=self.model.global_params,
+                    context={
+                        "scope": "component",
+                        "componentID": self.id,
+                        "componentClassID": self.class_id,
+                    },
+                )
+            )
+        return issues
+
+    def to_node_data(self) -> NodeData:
+        return {
+            "id": self.id,
+            "label": self.label,
+            "nodeClassID": self.class_id,
+            "viewStatus": self.view_status,
+            "data": self.params,
+            "pinsLabel": self.pins_label,
+        }