stabilize 0.9.2__py3-none-any.whl

stabilize/models/stage.py

@@ -0,0 +1,389 @@
+"""
+StageExecution model.
+
+A stage represents a logical unit of work in a pipeline. Stages can have:
+- Prerequisites (other stages that must complete first)
+- Tasks (sequential work units)
+- Synthetic stages (before/after stages injected by builders)
+
+The DAG structure is represented via requisite_stage_ref_ids, which contains
+the ref_ids of all stages this stage depends on.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from stabilize.models.status import (
+    CONTINUABLE_STATUSES,
+    WorkflowStatus,
+)
+from stabilize.models.task import TaskExecution
+
+if TYPE_CHECKING:
+    from stabilize.models.workflow import Workflow
+
+
+def _generate_stage_id() -> str:
+    """Generate a unique stage ID using ULID."""
+    import ulid
+
+    return str(ulid.new())
+
+
+class SyntheticStageOwner(Enum):
+    """
+    Indicates the relationship of a synthetic stage to its parent.
+
+    STAGE_BEFORE: Runs before the parent's tasks
+    STAGE_AFTER: Runs after the parent completes
+    """
+
+    STAGE_BEFORE = "STAGE_BEFORE"
+    STAGE_AFTER = "STAGE_AFTER"
+
+
+@dataclass
+class StageExecution:
+    """
+    Represents a stage execution within a pipeline.
+
+    The DAG structure is encoded in requisite_stage_ref_ids:
+    - Empty set = initial stage (no dependencies)
+    - Single ref_id = sequential dependency
+    - Multiple ref_ids = join point (waits for all)
+
+    Attributes:
+        id: Unique identifier (ULID)
+        ref_id: Reference identifier used for DAG relationships
+        type: Stage type (e.g., "deploy", "bake", "wait")
+        name: Human-readable stage name
+        status: Current execution status
+        context: Input parameters and runtime state (stage-scoped)
+        outputs: Values available to downstream stages (pipeline-scoped)
+        tasks: List of tasks to execute in this stage
+        requisite_stage_ref_ids: Set of ref_ids this stage depends on (DAG edges)
+        parent_stage_id: Parent stage ID for synthetic stages
+        synthetic_stage_owner: STAGE_BEFORE or STAGE_AFTER for synthetic stages
+        start_time: Epoch milliseconds when stage started
+        end_time: Epoch milliseconds when stage completed
+        start_time_expiry: If stage not started by this time, skip it
+        scheduled_time: When stage is scheduled to execute
+    """
+
+    id: str = field(default_factory=_generate_stage_id)
+    ref_id: str = ""
+    type: str = ""
+    name: str = ""
+    status: WorkflowStatus = WorkflowStatus.NOT_STARTED
+    context: dict[str, Any] = field(default_factory=dict)
+    outputs: dict[str, Any] = field(default_factory=dict)
+    tasks: list[TaskExecution] = field(default_factory=list)
+    requisite_stage_ref_ids: set[str] = field(default_factory=set)
+    parent_stage_id: str | None = None
+    synthetic_stage_owner: SyntheticStageOwner | None = None
+    start_time: int | None = None
+    end_time: int | None = None
+    start_time_expiry: int | None = None
+    scheduled_time: int | None = None
+
+    # Back-reference to parent execution (set after construction)
+    _execution: Workflow | None = field(default=None, repr=False)
+
+    @property
+    def execution(self) -> Workflow:
+        """Get the parent pipeline execution."""
+        if self._execution is None:
+            raise ValueError("Stage is not attached to an execution")
+        return self._execution
+
+    @execution.setter
+    def execution(self, value: Workflow) -> None:
+        """Set the parent pipeline execution."""
+        self._execution = value
+
+    def has_execution(self) -> bool:
+        """Check if this stage is attached to an execution."""
+        return self._execution is not None
+
+    # ========== DAG Navigation Methods ==========
+
+    def is_initial(self) -> bool:
+        """Check if this is an initial stage (no dependencies)."""
+        return len(self.requisite_stage_ref_ids) == 0
+
+    def is_join(self) -> bool:
+        """
+        Check if this is a join point (multiple dependencies).
+
+        A join point waits for multiple upstream stages to complete.
+        """
+        return len(self.requisite_stage_ref_ids) > 1
+
+    def upstream_stages(self) -> list[StageExecution]:
+        """
+        Get all stages directly upstream of this stage.
+
+        Returns stages whose ref_id is in this stage's requisite_stage_ref_ids.
+        """
+        return [stage for stage in self.execution.stages if stage.ref_id in self.requisite_stage_ref_ids]
+
+    def downstream_stages(self) -> list[StageExecution]:
+        """
+        Get all stages directly downstream of this stage.
+
+        Returns stages that have this stage's ref_id in their requisite_stage_ref_ids.
+        """
+        return [stage for stage in self.execution.stages if self.ref_id in stage.requisite_stage_ref_ids]
+
+    def all_upstream_stages_complete(self) -> bool:
+        """
+        Check if all upstream stages have completed successfully.
+
+        Returns True if all upstream stages have status in CONTINUABLE_STATUSES
+        (SUCCEEDED, FAILED_CONTINUE, or SKIPPED).
+        """
+        return all(stage.status in CONTINUABLE_STATUSES for stage in self.upstream_stages())
+
+    def any_upstream_stages_failed(self) -> bool:
+        """
+        Check if any upstream stages have failed with a halt status.
+
+        Returns True if any upstream stage has TERMINAL, STOPPED, or CANCELED status.
+        """
+        halt_statuses = {
+            WorkflowStatus.TERMINAL,
+            WorkflowStatus.STOPPED,
+            WorkflowStatus.CANCELED,
+        }
+        for upstream in self.upstream_stages():
+            if upstream.status in halt_statuses:
+                return True
+            # Check recursively for NOT_STARTED stages
+            if upstream.status == WorkflowStatus.NOT_STARTED and upstream.any_upstream_stages_failed():
+                return True
+        return False
+
+    # ========== Synthetic Stage Methods ==========
+
+    def synthetic_stages(self) -> list[StageExecution]:
+        """Get all synthetic stages (children) of this stage."""
+        return [stage for stage in self.execution.stages if stage.parent_stage_id == self.id]
+
+    def before_stages(self) -> list[StageExecution]:
+        """Get synthetic stages that run before this stage's tasks."""
+        return [
+            stage
+            for stage in self.synthetic_stages()
+            if stage.synthetic_stage_owner == SyntheticStageOwner.STAGE_BEFORE
+        ]
+
+    def after_stages(self) -> list[StageExecution]:
+        """Get synthetic stages that run after this stage completes."""
+        return [
+            stage for stage in self.synthetic_stages() if stage.synthetic_stage_owner == SyntheticStageOwner.STAGE_AFTER
+        ]
+
+    def first_before_stages(self) -> list[StageExecution]:
+        """Get initial before stages (those with no dependencies among before stages)."""
+        return [stage for stage in self.before_stages() if stage.is_initial()]
+
+    def first_after_stages(self) -> list[StageExecution]:
+        """Get initial after stages (those with no dependencies among after stages)."""
+        return [stage for stage in self.after_stages() if stage.is_initial()]
+
+    def parent(self) -> StageExecution:
+        """
+        Get the parent stage for this synthetic stage.
+
+        Raises:
+            ValueError: If this is not a synthetic stage
+        """
+        if self.parent_stage_id is None:
+            raise ValueError("Not a synthetic stage")
+        for stage in self.execution.stages:
+            if stage.id == self.parent_stage_id:
+                return stage
+        raise ValueError(f"Parent stage {self.parent_stage_id} not found")
+
+    def is_synthetic(self) -> bool:
+        """Check if this is a synthetic stage."""
+        return self.parent_stage_id is not None
+
+    # ========== Task Methods ==========
+
+    def first_task(self) -> TaskExecution | None:
+        """Get the first task in this stage."""
+        return self.tasks[0] if self.tasks else None
+
+    def next_task(self, task: TaskExecution) -> TaskExecution | None:
+        """Get the task that follows the given task."""
+        if task.is_stage_end:
+            return None
+        try:
+            index = self.tasks.index(task)
+            return self.tasks[index + 1]
+        except (ValueError, IndexError):
+            return None
+
+    def has_tasks(self) -> bool:
+        """Check if this stage has any tasks."""
+        return len(self.tasks) > 0
+
+    # ========== Status Methods ==========
+
+    def determine_status(self) -> WorkflowStatus:
+        """Determine the stage status based on synthetic stages and tasks."""
+        synthetic_statuses = [s.status for s in self.synthetic_stages()]
+        task_statuses = [t.status for t in self.tasks]
+        all_statuses = synthetic_statuses + task_statuses
+        after_stage_statuses = [s.status for s in self.after_stages()]
+
+        if not all_statuses:
+            return WorkflowStatus.NOT_STARTED
+
+        if WorkflowStatus.TERMINAL in all_statuses:
+            return self.failure_status()
+        if WorkflowStatus.STOPPED in all_statuses:
+            return WorkflowStatus.STOPPED
+        if WorkflowStatus.CANCELED in all_statuses:
+            return WorkflowStatus.CANCELED
+        if WorkflowStatus.FAILED_CONTINUE in all_statuses:
+            return WorkflowStatus.FAILED_CONTINUE
+        if all(s in {WorkflowStatus.SUCCEEDED, WorkflowStatus.SKIPPED} for s in all_statuses):
+            return WorkflowStatus.SUCCEEDED
+        if WorkflowStatus.NOT_STARTED in after_stage_statuses:
+            return WorkflowStatus.RUNNING
+
+        return WorkflowStatus.TERMINAL
+
+    def failure_status(self, default: WorkflowStatus = WorkflowStatus.TERMINAL) -> WorkflowStatus:
+        """Get the appropriate failure status based on stage configuration."""
+        if self.continue_pipeline_on_failure:
+            return WorkflowStatus.FAILED_CONTINUE
+        if self.should_fail_pipeline():
+            return default
+        return WorkflowStatus.STOPPED
+
+    @property
+    def continue_pipeline_on_failure(self) -> bool:
+        """Check if pipeline should continue on stage failure."""
+        return bool(self.context.get("continuePipelineOnFailure", False))
+
+    def should_fail_pipeline(self) -> bool:
+        """Check if stage failure should fail the pipeline."""
+        return bool(self.context.get("failPipeline", True))
+
+    @property
+    def allow_sibling_stages_to_continue_on_failure(self) -> bool:
+        """Check if sibling stages can continue on this stage's failure."""
+        return bool(self.context.get("allowSiblingStagesToContinueOnFailure", False))
+
+    # ========== Ancestor Traversal ==========
+
+    def ancestors(self) -> list[StageExecution]:
+        """
+        Get all ancestor stages in dependency order.
+
+        Includes requisite stages and parent stages.
+        """
+        visited: set[str] = set()
+        result: list[StageExecution] = []
+
+        def visit(stage: StageExecution) -> None:
+            if stage.id in visited:
+                return
+            visited.add(stage.id)
+            result.append(stage)
+
+            # Visit requisite stages
+            for upstream in stage.upstream_stages():
+                visit(upstream)
+
+            # Visit parent stage
+            if stage.parent_stage_id:
+                try:
+                    visit(stage.parent())
+                except ValueError:
+                    pass
+
+        # Start with upstream stages (not self)
+        for upstream in self.upstream_stages():
+            visit(upstream)
+        if self.parent_stage_id:
+            try:
+                visit(self.parent())
+            except ValueError:
+                pass
+
+        return result
+
+    # ========== Factory Methods ==========
+
+    @classmethod
+    def create(
+        cls,
+        type: str,
+        name: str,
+        ref_id: str,
+        context: dict[str, Any] | None = None,
+        requisite_stage_ref_ids: set[str] | None = None,
+    ) -> StageExecution:
+        """
+        Factory method to create a new stage execution.
+
+        Args:
+            type: Stage type
+            name: Human-readable name
+            ref_id: Reference ID for DAG relationships
+            context: Initial context/parameters
+            requisite_stage_ref_ids: Dependencies (empty = initial stage)
+
+        Returns:
+            A new StageExecution instance
+        """
+        return cls(
+            type=type,
+            name=name,
+            ref_id=ref_id,
+            context=context or {},
+            requisite_stage_ref_ids=requisite_stage_ref_ids or set(),
+        )
+
+    @classmethod
+    def create_synthetic(
+        cls,
+        type: str,
+        name: str,
+        parent: StageExecution,
+        owner: SyntheticStageOwner,
+        context: dict[str, Any] | None = None,
+    ) -> StageExecution:
+        """
+        Factory method to create a synthetic stage.
+
+        Args:
+            type: Stage type
+            name: Human-readable name
+            parent: Parent stage
+            owner: STAGE_BEFORE or STAGE_AFTER
+            context: Initial context/parameters
+
+        Returns:
+            A new synthetic StageExecution
+        """
+        import ulid
+
+        stage = cls(
+            type=type,
+            name=name,
+            ref_id=str(ulid.new()),  # Synthetic stages get unique ref_ids
+            context=context or {},
+            parent_stage_id=parent.id,
+            synthetic_stage_owner=owner,
+        )
+        if parent.has_execution():
+            stage.execution = parent.execution
+        return stage

stabilize/models/status.py

@@ -0,0 +1,146 @@
+"""
+WorkflowStatus enum.
+
+This enum represents all possible states for executions, stages, and tasks.
+Each status has two boolean properties:
+- complete: Whether the entity has finished its work (successfully or not)
+- halt: Whether downstream execution should be blocked
+"""
+
+from enum import Enum
+
+
+class WorkflowStatus(Enum):
+    """
+    Execution status enum.
+
+    Each value is a tuple of (name, complete, halt).
+    """
+
+    # The task has yet to start
+    NOT_STARTED = ("NOT_STARTED", False, False)
+
+    # The task is still running and may be re-executed to continue
+    RUNNING = ("RUNNING", False, False)
+
+    # The task is paused and may be resumed to continue
+    PAUSED = ("PAUSED", False, False)
+
+    # The task is complete but pipeline should stop pending a trigger
+    SUSPENDED = ("SUSPENDED", False, False)
+
+    # The task executed successfully and pipeline may proceed
+    SUCCEEDED = ("SUCCEEDED", True, False)
+
+    # The task failed but pipeline may proceed to the next task
+    FAILED_CONTINUE = ("FAILED_CONTINUE", True, False)
+
+    # The task failed terminally - pipeline will not progress further
+    TERMINAL = ("TERMINAL", True, True)
+
+    # The task was canceled - pipeline will not progress further
+    CANCELED = ("CANCELED", True, True)
+
+    # The step completed but indicates a decision path should be followed
+    REDIRECT = ("REDIRECT", False, False)
+
+    # The task was stopped - pipeline will not progress further
+    STOPPED = ("STOPPED", True, True)
+
+    # The task was skipped and pipeline will proceed to next task
+    SKIPPED = ("SKIPPED", True, False)
+
+    # The task is not started and must transition to NOT_STARTED
+    BUFFERED = ("BUFFERED", False, False)
+
+    def __init__(self, name: str, complete: bool, halt: bool) -> None:
+        self._name = name
+        self._complete = complete
+        self._halt = halt
+
+    @property
+    def is_complete(self) -> bool:
+        """
+        Indicates that the task/stage/pipeline has finished its work.
+
+        Returns True for: CANCELED, SUCCEEDED, STOPPED, SKIPPED, TERMINAL, FAILED_CONTINUE
+        """
+        return self._complete
+
+    @property
+    def is_halt(self) -> bool:
+        """
+        Indicates an abnormal completion - nothing downstream should run.
+
+        Returns True for: TERMINAL, CANCELED, STOPPED
+        """
+        return self._halt
+
+    @property
+    def is_successful(self) -> bool:
+        """Check if this status represents a successful completion."""
+        return self in _SUCCESSFUL_STATUSES
+
+    @property
+    def is_failure(self) -> bool:
+        """Check if this status represents a failure."""
+        return self in _FAILURE_STATUSES
+
+    @property
+    def is_skipped(self) -> bool:
+        """Check if this status is SKIPPED."""
+        return self == WorkflowStatus.SKIPPED
+
+    def __str__(self) -> str:
+        return self._name
+
+    def __repr__(self) -> str:
+        return f"WorkflowStatus.{self.name}"
+
+
+# Status sets for quick membership testing (matching Orca's ImmutableSets)
+COMPLETED_STATUSES: frozenset[WorkflowStatus] = frozenset(
+    {
+        WorkflowStatus.CANCELED,
+        WorkflowStatus.SUCCEEDED,
+        WorkflowStatus.STOPPED,
+        WorkflowStatus.SKIPPED,
+        WorkflowStatus.TERMINAL,
+        WorkflowStatus.FAILED_CONTINUE,
+    }
+)
+
+_SUCCESSFUL_STATUSES: frozenset[WorkflowStatus] = frozenset(
+    {
+        WorkflowStatus.SUCCEEDED,
+        WorkflowStatus.STOPPED,
+        WorkflowStatus.SKIPPED,
+    }
+)
+
+_FAILURE_STATUSES: frozenset[WorkflowStatus] = frozenset(
+    {
+        WorkflowStatus.TERMINAL,
+        WorkflowStatus.STOPPED,
+        WorkflowStatus.FAILED_CONTINUE,
+    }
+)
+
+# Statuses that allow downstream stages to continue
+CONTINUABLE_STATUSES: frozenset[WorkflowStatus] = frozenset(
+    {
+        WorkflowStatus.SUCCEEDED,
+        WorkflowStatus.FAILED_CONTINUE,
+        WorkflowStatus.SKIPPED,
+    }
+)
+
+# Statuses that indicate the entity is still actively processing
+ACTIVE_STATUSES: frozenset[WorkflowStatus] = frozenset(
+    {
+        WorkflowStatus.NOT_STARTED,
+        WorkflowStatus.RUNNING,
+        WorkflowStatus.PAUSED,
+        WorkflowStatus.SUSPENDED,
+    }
+)

stabilize/models/task.py

@@ -0,0 +1,125 @@
+"""
+TaskExecution model.
+
+A task is the smallest unit of work within a stage. Each stage contains
+one or more tasks that execute sequentially.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from stabilize.models.status import WorkflowStatus
+
+if TYPE_CHECKING:
+    from stabilize.models.stage import StageExecution
+
+
+def _generate_task_id() -> str:
+    """Generate a unique task ID using ULID."""
+    import ulid
+
+    return str(ulid.new())
+
+
+@dataclass
+class TaskExecution:
+    """
+    Represents a single task within a stage execution.
+
+    Tasks are the atomic units of work in a pipeline. They execute sequentially
+    within a stage, and each task produces a result that can include:
+    - Status updates
+    - Context modifications (stage-scoped)
+    - Output values (pipeline-scoped)
+
+    Attributes:
+        id: Unique identifier for this task execution
+        name: Human-readable name for this task
+        implementing_class: Fully qualified class name of the task implementation
+        status: Current execution status
+        start_time: Epoch milliseconds when task started
+        end_time: Epoch milliseconds when task completed
+        stage_start: True if this is the first task in the stage
+        stage_end: True if this is the last task in the stage
+        loop_start: True if this task starts a loop
+        loop_end: True if this task ends a loop
+        task_exception_details: Exception information if task failed
+    """
+
+    id: str = field(default_factory=_generate_task_id)
+    name: str = ""
+    implementing_class: str = ""
+    status: WorkflowStatus = WorkflowStatus.NOT_STARTED
+    start_time: int | None = None
+    end_time: int | None = None
+    stage_start: bool = False
+    stage_end: bool = False
+    loop_start: bool = False
+    loop_end: bool = False
+    task_exception_details: dict[str, Any] = field(default_factory=dict)
+
+    # Back-reference to parent stage (set after construction)
+    _stage: StageExecution | None = field(default=None, repr=False)
+
+    @property
+    def stage(self) -> StageExecution | None:
+        """Get the parent stage for this task."""
+        return self._stage
+
+    @stage.setter
+    def stage(self, value: StageExecution) -> None:
+        """Set the parent stage for this task."""
+        self._stage = value
+
+    @property
+    def is_stage_start(self) -> bool:
+        """Check if this task starts the stage."""
+        return self.stage_start
+
+    @property
+    def is_stage_end(self) -> bool:
+        """Check if this task ends the stage."""
+        return self.stage_end
+
+    @property
+    def is_loop_start(self) -> bool:
+        """Check if this task starts a loop."""
+        return self.loop_start
+
+    @property
+    def is_loop_end(self) -> bool:
+        """Check if this task ends a loop."""
+        return self.loop_end
+
+    def set_exception_details(self, exception: dict[str, Any]) -> None:
+        """Store exception details for this task."""
+        self.task_exception_details["exception"] = exception
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        implementing_class: str,
+        stage_start: bool = False,
+        stage_end: bool = False,
+    ) -> TaskExecution:
+        """
+        Factory method to create a new task execution.
+
+        Args:
+            name: Human-readable task name
+            implementing_class: Class name or callable reference for task
+            stage_start: Whether this is the first task
+            stage_end: Whether this is the last task
+
+        Returns:
+            A new TaskExecution instance
+        """
+        return cls(
+            name=name,
+            implementing_class=implementing_class,
+            stage_start=stage_start,
+            stage_end=stage_end,
+        )