takflow 0.1.0__py3-none-any.whl

takflow/__init__.py

@@ -0,0 +1,13 @@
+"""takflow — unified workflow-generation framework.
+
+Phase 0 exposes the ``jobspec`` contract layer. Later phases add the engine
+abstraction, hooks, config base, job/resource/credential/util, and the CLI
+skeleton (see ``../TAKFLOW_DESIGN.md``).
+"""
+
+try:
+    from ._version import version as __version__
+except ImportError:  # pragma: no cover
+    __version__ = "unknown"
+
+__all__ = ["__version__"]

takflow/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

takflow/backends/__init__.py

@@ -0,0 +1,3 @@
+"""
+takflow 后端转换层。
+"""

takflow/backends/ecflow/__init__.py

@@ -0,0 +1,6 @@
+"""
+ecflow 后端：将 takflow 的抽象流程定义转换为 ecFlow ``.def`` 文件。
+"""
+from takflow.backends.ecflow.backend import EcflowBackend
+
+__all__ = ["EcflowBackend"]

takflow/backends/ecflow/backend.py

@@ -0,0 +1,140 @@
+"""
+ecflow 后端实现。
+
+将统一后端接口映射到 ``takflow.backends.ecflow.serializer`` API（一个纯 Python 的
+ecflow ``.def`` 生成库，由 ``light_ecflow`` 折叠而来）。
+"""
+from pathlib import Path
+from typing import Any, Dict, List, Union
+
+from takflow.flow import Node, NodeType, WorkflowBackend
+from takflow.backends.ecflow.serializer import (
+    Clock,
+    DState,
+    Defs,
+    Family,
+    RepeatDate,
+    RepeatDay,
+    Suite,
+    Task,
+)
+
+
+class EcflowBackend(WorkflowBackend):
+    """
+    ecflow 工作流引擎后端。
+    """
+
+    @property
+    def backend_type(self) -> str:
+        return "ecflow"
+
+    def create_suite(self, name: str) -> Any:
+        return Suite(name)
+
+    def create_family(self, name: str) -> Any:
+        return Family(name)
+
+    def create_task(self, name: str) -> Any:
+        return Task(name)
+
+    def add_family(self, parent: Node, family: Node) -> None:
+        parent.raw.add_family(family.raw)
+
+    def add_task(self, parent: Node, task: Node) -> None:
+        parent.raw.add_task(task.raw)
+
+    def add_variable(
+        self,
+        node: Node,
+        name: str,
+        value: Union[str, int, float, bool],
+    ) -> None:
+        node.raw.add_variable(name, str(value))
+
+    def add_variables(
+        self,
+        node: Node,
+        variables: Dict[str, Union[str, int, float, bool]],
+    ) -> None:
+        node.raw.add_variable({k: str(v) for k, v in variables.items()})
+
+    def add_trigger(self, node: Node, expression: str) -> None:
+        node.raw.add_trigger(expression)
+
+    def add_complete_trigger(self, node: Node, expression: str) -> None:
+        node.raw.add_complete(expression)
+
+    def add_event(self, node: Node, name: str) -> None:
+        node.raw.add_event(name)
+
+    def add_meter(
+        self,
+        node: Node,
+        name: str,
+        min_value: int,
+        max_value: int,
+    ) -> None:
+        node.raw.add_meter(name, min_value, max_value)
+
+    def add_limit(self, node: Node, name: str, limit: int) -> None:
+        node.raw.add_limit(name, limit)
+
+    def add_inlimit(self, node: Node, limit_name: str, tokens: int = 1) -> None:
+        node.raw.add_inlimit(limit_name, tokens)
+
+    def add_late(
+        self,
+        node: Node,
+        submitted: tuple[int, int] | None = None,
+        active: tuple[int, int] | None = None,
+        complete: tuple[int, int] | None = None,
+        complete_relative: bool = False,
+    ) -> None:
+        from takflow.backends.ecflow.serializer import Late
+
+        late = Late()
+        if submitted is not None:
+            late.submitted(*submitted)
+        if active is not None:
+            late.active(*active)
+        if complete is not None:
+            late.complete(*complete, relative=complete_relative)
+        node.raw.add_late(late)
+
+    def add_repeat_date(
+        self,
+        node: Node,
+        name: str,
+        start_date: int,
+        end_date: int,
+    ) -> None:
+        node.raw.add_repeat(RepeatDate(name, start_date, end_date))
+
+    def add_repeat_day(self, node: Node, step: int = 1, *, clock_kind: str = "hybrid") -> None:
+        node.raw.add_clock(Clock(clock_kind))
+        node.raw.add_repeat(RepeatDay(step))
+
+    def add_time(self, node: Node, time_str: str) -> None:
+        node.raw.add_time(time_str)
+
+    def set_defstatus_complete(self, node: Node) -> None:
+        node.raw.add_defstatus(DState.complete)
+
+    def set_defstatus_queued(self, node: Node) -> None:
+        node.raw.add_defstatus(DState.queued)
+
+    def save_suite(self, suite: Node, output_path: Path) -> None:
+        defs = Defs()
+        defs.add_suite(suite.raw)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        defs.save_as_defs(str(output_path))
+
+    def node_path(self, node: Node) -> str:
+        return node.raw.get_abs_node_path()
+
+    def list_children(self, node: Node) -> List[Any]:
+        return list(node.raw.nodes)
+
+    def get_node_name(self, raw_node: Any) -> str:
+        return raw_node.name()

takflow/backends/ecflow/serializer/__init__.py

@@ -0,0 +1,54 @@
+"""takflow.serialize.ecflow: pure-Python ecFlow ``.def`` file generator.
+
+Originally ``light_ecflow``; folded into takflow as one serialization backend.
+Exposes a small subset of the ecFlow Python API without the C++ dependency.
+"""
+
+try:
+    from takflow._version import version as __version__
+except ImportError:  # pragma: no cover
+    __version__ = "unknown"
+
+from .attributes import (
+    Clock,
+    Complete,
+    DState,
+    DefStatus,
+    Edit,
+    Event,
+    InLimit,
+    Late,
+    Limit,
+    Meter,
+    PartTrigger,
+    RepeatDate,
+    RepeatDay,
+    Time,
+    Trigger,
+)
+from .defs import Defs
+from .node import Family, Node, Suite, Task
+
+__all__ = [
+    "__version__",
+    "Clock",
+    "Complete",
+    "DState",
+    "DefStatus",
+    "Defs",
+    "Edit",
+    "Event",
+    "Family",
+    "InLimit",
+    "Late",
+    "Limit",
+    "Meter",
+    "Node",
+    "PartTrigger",
+    "RepeatDate",
+    "RepeatDay",
+    "Suite",
+    "Task",
+    "Time",
+    "Trigger",
+]

takflow/backends/ecflow/serializer/attributes.py

@@ -0,0 +1,314 @@
+"""
+ecFlow-style attribute objects for the light-ecflow stub.
+
+These classes represent the constructs that can be attached to a node, either
+via the method API (``add_trigger(...)``) or via the constructor-style API
+(``Task("t1", Trigger("..."))``).
+"""
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, Optional, Union
+
+
+class DState(str, Enum):
+    """Default node states supported by ``defstatus``."""
+
+    complete = "complete"
+    queued = "queued"
+    suspended = "suspended"
+    aborted = "aborted"
+    active = "active"
+    unknown = "unknown"
+
+
+class Edit:
+    """Represents one or more variables attached to a node."""
+
+    def __init__(self, **variables: Any):
+        self.variables: Dict[str, Any] = variables
+
+    def __repr__(self) -> str:
+        return f"Edit({self.variables!r})"
+
+
+class Trigger:
+    """Represents a trigger expression."""
+
+    def __init__(self, expression: str):
+        self.expression = expression
+
+    def to_def(self) -> str:
+        return f"trigger {self.expression}"
+
+    def __repr__(self) -> str:
+        return f"Trigger({self.expression!r})"
+
+
+class PartTrigger:
+    """Represents a partial trigger expression used with ``add_part_trigger``."""
+
+    def __init__(self, expression: str, and_flag: bool = True):
+        self.expression = expression
+        self.and_flag = and_flag
+
+    def __repr__(self) -> str:
+        return f"PartTrigger({self.expression!r}, and_flag={self.and_flag})"
+
+
+class Complete:
+    """Represents a complete expression."""
+
+    def __init__(self, expression: str):
+        self.expression = expression
+
+    def to_def(self) -> str:
+        return f"complete {self.expression}"
+
+    def __repr__(self) -> str:
+        return f"Complete({self.expression!r})"
+
+
+class DefStatus:
+    """Represents a default node status."""
+
+    def __init__(self, state: Union[DState, str]):
+        if isinstance(state, str):
+            state = DState(state)
+        self.state: DState = state
+
+    def to_def(self) -> str:
+        return f"defstatus {self.state.value}"
+
+    def __repr__(self) -> str:
+        return f"DefStatus({self.state.value!r})"
+
+
+class Event:
+    """Represents an event attached to a node."""
+
+    def __init__(self, name: str):
+        self.name = name
+
+    def to_def(self) -> str:
+        return f"event {self.name}"
+
+    def __repr__(self) -> str:
+        return f"Event({self.name!r})"
+
+
+class Meter:
+    """Represents a meter attached to a node."""
+
+    def __init__(self, name: str, min_value: int, max_value: int):
+        self.name = name
+        self.min_value = min_value
+        self.max_value = max_value
+
+    def to_def(self) -> str:
+        return f"meter {self.name} {self.min_value} {self.max_value}"
+
+    def __repr__(self) -> str:
+        return f"Meter({self.name!r}, {self.min_value}, {self.max_value})"
+
+
+class Limit:
+    """Represents a limit attached to a node."""
+
+    def __init__(self, name: str, value: int):
+        self.name = name
+        self.value = value
+
+    def to_def(self) -> str:
+        return f"limit {self.name} {self.value}"
+
+    def __repr__(self) -> str:
+        return f"Limit({self.name!r}, {self.value})"
+
+
+class InLimit:
+    """Represents an in-limit attached to a node."""
+
+    def __init__(self, name: str, tokens: int = 1):
+        self.name = name
+        self.tokens = tokens
+
+    def to_def(self) -> str:
+        if self.tokens == 1:
+            return f"inlimit {self.name}"
+        return f"inlimit {self.name} {self.tokens}"
+
+    def __repr__(self) -> str:
+        return f"InLimit({self.name!r}, tokens={self.tokens})"
+
+
+class Time:
+    """Represents a time dependency attached to a node."""
+
+    def __init__(self, time_str: str):
+        self.time_str = time_str
+
+    def to_def(self) -> str:
+        return f"time {self.time_str}"
+
+    def __repr__(self) -> str:
+        return f"Time({self.time_str!r})"
+
+
+class Late:
+    """Represents a "late" monitoring attribute attached to a node.
+
+    Mirrors the native ecFlow ``Late`` object used by GFS/MESO post
+    graph builders:
+
+    - ``late.submitted(h, m)``  -> ``late -s HH:MM``
+    - ``late.complete(h, m, relative=False)`` -> ``late -c HH:MM``;
+      with ``relative=True`` -> ``late -c +HH:MM``.
+    - ``late.active(h, m, relative=False)`` -> ``late -a HH:MM`` / ``late -a +HH:MM``.
+
+    Attributes are serialized in the order submitted/active/complete, matching
+    native ecFlow output.
+    """
+
+    def __init__(self):
+        self.submitted_time: Optional[tuple[int, int]] = None
+        self.active_time: Optional[tuple[int, int]] = None
+        self.complete_time: Optional[tuple[int, int]] = None
+        self.complete_relative: bool = False
+        self.active_relative: bool = False
+
+    def submitted(self, hours: int, minutes: int) -> "Late":
+        self.submitted_time = (hours, minutes)
+        return self
+
+    def active(self, hours: int, minutes: int, relative: bool = False) -> "Late":
+        self.active_time = (hours, minutes)
+        self.active_relative = relative
+        return self
+
+    def complete(self, hours: int, minutes: int, relative: bool = False) -> "Late":
+        self.complete_time = (hours, minutes)
+        self.complete_relative = relative
+        return self
+
+    @staticmethod
+    def _fmt(value: tuple[int, int]) -> str:
+        h, m = value
+        return f"{h:02d}:{m:02d}"
+
+    def to_def(self) -> str:
+        parts = ["late"]
+        if self.submitted_time is not None:
+            parts.append(f"-s {self._fmt(self.submitted_time)}")
+        if self.active_time is not None:
+            prefix = "+" if self.active_relative else ""
+            parts.append(f"-a {prefix}{self._fmt(self.active_time)}")
+        if self.complete_time is not None:
+            prefix = "+" if self.complete_relative else ""
+            parts.append(f"-c {prefix}{self._fmt(self.complete_time)}")
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        return f"Late({self.to_def()!r})"
+
+
+class Repeat:
+    """Base class for repeat attributes."""
+
+    def to_def(self) -> str:
+        raise NotImplementedError
+
+
+class RepeatDate(Repeat):
+    """Represents a date-based repeat attribute."""
+
+    def __init__(self, name: str, start: int, end: int, step: int = 1):
+        self.name = name
+        self.start = int(start)
+        self.end = int(end)
+        self.step = int(step)
+
+    def to_def(self) -> str:
+        return f"repeat date {self.name} {self.start} {self.end} {self.step}"
+
+    def __repr__(self) -> str:
+        return (
+            f"RepeatDate({self.name!r}, {self.start}, {self.end}, step={self.step})"
+        )
+
+
+class RepeatDay(Repeat):
+    """Represents a day-based repeat attribute (suite level, tied to clock)."""
+
+    def __init__(self, step: int = 1):
+        self.step = int(step)
+
+    def to_def(self) -> str:
+        return f"repeat day {self.step}"
+
+    def __repr__(self) -> str:
+        return f"RepeatDay({self.step})"
+
+
+class Clock:
+    """
+    Represents a suite clock.
+
+    Supports several calling conventions:
+
+    - ``Clock(True)``  -> hybrid clock, no initial date/time.
+    - ``Clock(False)`` -> real clock, no initial date/time.
+    - ``Clock("hybrid", date_str, time_str)``
+    - ``Clock("real", time_str)``
+    """
+
+    def __init__(self, *args: Any):
+        self.kind: str = "hybrid"
+        self.date: Optional[str] = None
+        self.time: Optional[str] = None
+
+        if not args:
+            return
+
+        first = args[0]
+        if isinstance(first, bool):
+            self.kind = "hybrid" if first else "real"
+            remaining = args[1:]
+        elif isinstance(first, str):
+            self.kind = first.lower()
+            remaining = args[1:]
+        else:
+            raise TypeError(f"Unexpected Clock argument type: {type(first)}")
+
+        if len(remaining) == 1:
+            self.time = str(remaining[0])
+        elif len(remaining) == 2:
+            self.date = str(remaining[0])
+            self.time = str(remaining[1])
+        elif len(remaining) > 2:
+            raise TypeError(f"Clock accepts at most 3 arguments, got {len(args)}")
+
+    def to_def(self) -> str:
+        parts = ["clock", self.kind]
+        if self.date:
+            parts.append(self.date)
+        if self.time:
+            parts.append(self.time)
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        return f"Clock({self.to_def()!r})"
+
+
+def _quote(value: str) -> str:
+    """
+    Quote a variable value in single quotes, matching the native ecflow output.
+
+    Values containing single quotes are wrapped in double quotes instead.
+    """
+    if "'" not in value:
+        return f"'{value}'"
+    if '"' not in value:
+        return f'"{value}"'
+    escaped = value.replace("'", "\\'")
+    return f"'{escaped}'"

takflow/backends/ecflow/serializer/defs.py

@@ -0,0 +1,51 @@
+"""
+Top-level ``Defs`` container that mimics ``ecflow.Defs``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Union
+
+from .node import Suite
+
+
+class Defs:
+    """
+    Container for one or more suites.
+
+    Example:
+
+        defs = Defs()
+        defs.add_suite(Suite("my_suite"))
+        defs.save_as_defs("my_suite.def")
+    """
+
+    def __init__(self, *suites: Suite):
+        self._suites: list[Suite] = list(suites)
+
+    def add_suite(self, suite: Suite) -> Suite:
+        """Add a suite to the definition."""
+        self._suites.append(suite)
+        return suite
+
+    def to_def(self) -> str:
+        """Return the full ``.def`` text."""
+        lines: list[str] = []
+        for suite in self._suites:
+            lines.extend(suite.to_def(0))
+        text = "\n".join(lines)
+        if text and not text.endswith("\n"):
+            text += "\n"
+        return text
+
+    def save_as_defs(self, path: Union[str, Path]) -> None:
+        """Write the definition tree to an ecFlow ``.def`` file."""
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(self.to_def(), encoding="utf-8")
+
+    def __str__(self) -> str:
+        return self.to_def()
+
+    def __repr__(self) -> str:
+        return f"Defs(suites={len(self._suites)})"