Skip to content

task_display

task_display

Task display types, lifecycle state, and status computation.

Provides display-oriented dataclasses (StatusInfo, ModeInfo), status/mode lookup tables, TaskState (the lifecycle fields needed for display), and functions for computing the effective status of a task.

Split from tasks.py to decouple presentation data from task lifecycle and metadata I/O.

TaskState(container_state=None, exit_code=None, deleting=False, initialized=False) dataclass

Container lifecycle state used for display status computation.

Orchestration-level TaskMeta inherits from this to add identity, configuration, and runtime metadata fields.

StatusInfo(label, emoji, color) dataclass

Display attributes for a task effective status.

ModeInfo(emoji, label) dataclass

Display attributes for a task mode.

ProjectBadge(emoji, label) dataclass

Display attributes for a project-level badge (security class, GPU, etc.).

has_gpu(project)

Check whether a project has GPU enabled in its project.yml.

Accepts any object with a root attribute pointing to the project directory (typically a Project instance). Returns False on any I/O or parse error.

Source code in src/terok/lib/core/task_display.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def has_gpu(project: Any) -> bool:
    """Check whether a project has GPU enabled in its ``project.yml``.

    Accepts any object with a ``root`` attribute pointing to the project
    directory (typically a ``Project`` instance).  Returns ``False`` on
    any I/O or parse error.
    """
    root = getattr(project, "root", None)
    if root is None:
        return False
    try:
        cfg = _yaml_load((root / "project.yml").read_text()) or {}
    except (OSError, TypeError, AttributeError, YAMLError):
        return False
    gpus = (cfg.get("run") or {}).get("gpus")
    if isinstance(gpus, str):
        return gpus.lower() == "all"
    if isinstance(gpus, bool):
        return gpus
    return False

effective_status(task)

Compute the display status from task lifecycle state.

Reads the following fields from a TaskState instance:

  • container_state (str | None): live podman state, or None
  • exit_code (int | None): process exit code, or None
  • deleting (bool): persisted to YAML before deletion starts
  • initialized (bool): True once ready_at is persisted to YAML

Returns one of: "deleting", "running", "init", "stopped", "completed", "failed", "created", "not found".

Source code in src/terok/lib/core/task_display.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def effective_status(task: TaskState) -> str:
    """Compute the display status from task lifecycle state.

    Reads the following fields from a ``TaskState`` instance:

    - ``container_state`` (str | None): live podman state, or None
    - ``exit_code`` (int | None): process exit code, or None
    - ``deleting`` (bool): persisted to YAML before deletion starts
    - ``initialized`` (bool): True once ``ready_at`` is persisted to YAML

    Returns one of: ``"deleting"``, ``"running"``, ``"init"``,
    ``"stopped"``, ``"completed"``, ``"failed"``, ``"created"``,
    ``"not found"``.
    """
    if task.deleting:
        return "deleting"

    cs = task.container_state

    if cs == "running":
        return "running" if task.initialized else "init"

    if cs is not None:
        return _exit_code_status(task.exit_code) or "stopped"

    # No container found
    if not task.initialized:
        return "created"
    return _exit_code_status(task.exit_code) or "not found"

mode_info(mode)

Return the display info for a task mode string.

Source code in src/terok/lib/core/task_display.py 
151
152
153
154
def mode_info(mode: str | None) -> ModeInfo:
    """Return the display info for a task mode string."""
    info = MODE_DISPLAY.get(mode if isinstance(mode, str) else None)
    return info if info else MODE_DISPLAY[None]