ddeutil-workflow 0.0.81__py3-none-any.whl → 0.0.82__py3-none-any.whl

ddeutil/workflow/stages.py

@@ -36,16 +36,6 @@ the stage execution method.
 execute method receives a `params={"params": {...}}` value for passing template
 searching.
 
-    All stages model inherit from `BaseStage` or `AsyncBaseStage` models that has the
-base fields:
-
-| field     | alias | data type   | default  | description                                                           |
-|-----------|-------|-------------|:--------:|-----------------------------------------------------------------------|
-| id        |       | str \| None |  `None`  | A stage ID that use to keep execution output or getting by job owner. |
-| name      |       | str         |          | A stage name that want to log when start execution.               |
-| condition | if    | str \| None |  `None`  | A stage condition statement to allow stage executable.                |
-| extras    |       | dict        | `dict()` | An extra parameter that override core config values.                  |
-
     It has a special base class is `BaseRetryStage` that inherit from `AsyncBaseStage`
 that use to handle retry execution when it got any error with `retry` field.
 """
@@ -92,9 +82,18 @@ from pydantic import BaseModel, Field, ValidationError
 from pydantic.functional_validators import field_validator, model_validator
 from typing_extensions import Self
 
+from .__about__ import __python_version__
 from .__types import DictData, DictStr, StrOrInt, StrOrNone, TupleStr
 from .conf import dynamic, pass_env
-from .errors import StageCancelError, StageError, StageSkipError, to_dict
+from .errors import (
+    StageCancelError,
+    StageError,
+    StageNestedCancelError,
+    StageNestedError,
+    StageNestedSkipError,
+    StageSkipError,
+    to_dict,
+)
 from .result import (
     CANCEL,
     FAILED,
@@ -114,7 +113,7 @@ from .reusables import (
     not_in_template,
     param2template,
 )
-from .traces import TraceManager, get_trace
+from .traces import Trace, get_trace
 from .utils import (
     delay,
     dump_all,
@@ -155,13 +154,11 @@ class BaseStage(BaseModel, ABC):
         process: Main execution logic that must be implemented by subclasses
 
     Example:
-        ```python
-        class CustomStage(BaseStage):
-            custom_param: str = Field(description="Custom parameter")
-
-            def process(self, params: dict, **kwargs) -> Result:
-                # Custom execution logic
-                return Result(status=SUCCESS)
+        >>> class CustomStage(BaseStage):
+        ...     custom_param: str = Field(description="Custom parameter")
+        ...
+        ...     def process(self, params: DictData, **kwargs) -> Result:
+        ...         return Result(status=SUCCESS)
         ```
     """
 
@@ -208,7 +205,8 @@ class BaseStage(BaseModel, ABC):
     def ___prepare_desc__(cls, value: str) -> str:
         """Prepare description string that was created on a template.
 
-        :rtype: str
+        Returns:
+            str: A dedent and left strip newline of description string.
         """
         return dedent(value.lstrip("\n"))
 
@@ -218,16 +216,17 @@ class BaseStage(BaseModel, ABC):
         method will validate name and id fields should not contain any template
         parameter (exclude matrix template).
 
-        :raise ValueError: When the ID and name fields include matrix parameter
-            template with the 'matrix.' string value.
+        Raises:
+            ValueError: When the ID and name fields include matrix parameter
+                template with the 'matrix.' string value.
 
-        :rtype: Self
+        Returns: Self
         """
         # VALIDATE: Validate stage id and name should not dynamic with params
         #   template. (allow only matrix)
         if not_in_template(self.id) or not_in_template(self.name):
             raise ValueError(
-                "Stage name and ID should only template with 'matrix.'"
+                "Stage name and ID should only template with 'matrix.?'."
             )
         return self
 
@@ -302,9 +301,9 @@ class BaseStage(BaseModel, ABC):
         """
         ts: float = time.monotonic()
         parent_run_id: str = run_id
-        run_id: str = run_id or gen_id(self.iden, unique=True)
+        run_id: str = gen_id(self.iden, unique=True, extras=self.extras)
         context: DictData = {"status": WAIT}
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         try:
@@ -349,13 +348,21 @@ class BaseStage(BaseModel, ABC):
         #   this exception class at other location.
         except (
             StageSkipError,
-            StageCancelError,
+            StageNestedSkipError,
+            StageNestedError,
             StageError,
         ) as e:  # pragma: no cov
-            trace.info(
-                f"[STAGE]: Handler:||{e.__class__.__name__}: {e}||"
-                f"{traceback.format_exc()}"
-            )
+            if isinstance(e, StageNestedError):
+                trace.info(f"[STAGE]: Handler: {e}")
+            else:
+                emoji: str = (
+                    "⏭️"
+                    if isinstance(e, (StageSkipError, StageNestedSkipError))
+                    else "🚨"
+                )
+                trace.info(
+                    f"[STAGE]: Handler:||{emoji} {traceback.format_exc()}"
+                )
             st: Status = get_status_from_error(e)
             return Result(
                 run_id=run_id,
@@ -366,7 +373,7 @@ class BaseStage(BaseModel, ABC):
                     status=st,
                     updated=(
                         None
-                        if isinstance(e, StageSkipError)
+                        if isinstance(e, (StageSkipError, StageNestedSkipError))
                         else {"errors": e.to_dict()}
                     ),
                 ),
@@ -374,10 +381,7 @@ class BaseStage(BaseModel, ABC):
                 extras=self.extras,
             )
         except Exception as e:
-            trace.error(
-                f"[STAGE]: Error Handler:||{e.__class__.__name__}: {e}||"
-                f"{traceback.format_exc()}"
-            )
+            trace.error(f"[STAGE]: Error Handler:||🚨 {traceback.format_exc()}")
             return Result(
                 run_id=run_id,
                 parent_run_id=parent_run_id,
@@ -632,9 +636,9 @@ class BaseAsyncStage(BaseStage, ABC):
         """
         ts: float = time.monotonic()
         parent_run_id: StrOrNone = run_id
-        run_id: str = run_id or gen_id(self.iden, unique=True)
+        run_id: str = gen_id(self.iden, unique=True, extras=self.extras)
         context: DictData = {}
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         try:
@@ -677,13 +681,21 @@ class BaseAsyncStage(BaseStage, ABC):
         #   this exception class at other location.
         except (
             StageSkipError,
-            StageCancelError,
+            StageNestedSkipError,
+            StageNestedError,
             StageError,
         ) as e:  # pragma: no cov
-            await trace.ainfo(
-                f"[STAGE]: Skip Handler:||{e.__class__.__name__}: {e}||"
-                f"{traceback.format_exc()}"
-            )
+            if isinstance(e, StageNestedError):
+                await trace.ainfo(f"[STAGE]: Handler: {e}")
+            else:
+                emoji: str = (
+                    "⏭️"
+                    if isinstance(e, (StageSkipError, StageNestedSkipError))
+                    else "🚨"
+                )
+                await trace.ainfo(
+                    f"[STAGE]:Handler:||{emoji} {traceback.format_exc()}"
+                )
             st: Status = get_status_from_error(e)
             return Result(
                 run_id=run_id,
@@ -703,8 +715,7 @@ class BaseAsyncStage(BaseStage, ABC):
             )
         except Exception as e:
             await trace.aerror(
-                f"[STAGE]: Error Handler:||{e.__class__.__name__}: {e}||"
-                f"{traceback.format_exc()}"
+                f"[STAGE]: Error Handler:||🚨 {traceback.format_exc()}"
             )
             return Result(
                 run_id=run_id,
@@ -777,7 +788,7 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
         current_retry: int = 0
         exception: Exception
         catch(context, status=WAIT)
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
 
@@ -823,6 +834,7 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
                     f"( {e.__class__.__name__} )"
                 )
                 exception = e
+                time.sleep(1.2**current_retry)
 
         trace.error(
             f"[STAGE]: Reach the maximum of retry number: {self.retry}."
@@ -850,7 +862,7 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
         current_retry: int = 0
         exception: Exception
         catch(context, status=WAIT)
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
 
@@ -896,6 +908,7 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
                     f"( {e.__class__.__name__} )"
                 )
                 exception = e
+                await asyncio.sleep(1.2**current_retry)
 
         await trace.aerror(
             f"[STAGE]: Reach the maximum of retry number: {self.retry}."
@@ -908,19 +921,15 @@ class EmptyStage(BaseAsyncStage):
 
     EmptyStage is a utility stage that performs no actual work but provides
     logging output and optional delays. It's commonly used for:
-    - Debugging workflow execution flow
-    - Adding informational messages to workflows
-    - Creating delays between stages
-    - Testing template parameter resolution
+        - Debugging workflow execution flow
+        - Adding informational messages to workflows
+        - Creating delays between stages
+        - Testing template parameter resolution
 
     The stage outputs the echo message to stdout and can optionally sleep
     for a specified duration, making it useful for workflow timing control
     and debugging scenarios.
 
-    Attributes:
-        echo (str, optional): Message to display during execution
-        sleep (float): Duration to sleep after logging (0-1800 seconds)
-
     Example:
         ```yaml
         stages:
@@ -932,24 +941,25 @@ class EmptyStage(BaseAsyncStage):
             echo: "Processing file: ${{ params.filename }}"
         ```
 
-        ```python
-        stage = EmptyStage(
-            name="Status Update",
-            echo="Processing completed successfully",
-            sleep=1.0
-        )
-        ```
+        >>> stage = EmptyStage(
+        ...     name="Status Update",
+        ...     echo="Processing completed successfully",
+        ...     sleep=1.0
+        ... )
     """
 
     echo: StrOrNone = Field(
         default=None,
-        description="A message that want to show on the stdout.",
+        description=(
+            "A message that want to display on the stdout during execution. "
+            "By default, it do not show any message."
+        ),
     )
     sleep: float = Field(
         default=0,
         description=(
-            "A second value to sleep before start execution. This value should "
-            "gather or equal 0, and less than 1800 seconds."
+            "A duration in second value to sleep after logging. This value "
+            "should between 0 - 1800 seconds."
         ),
         ge=0,
         lt=1800,
@@ -982,7 +992,7 @@ class EmptyStage(BaseAsyncStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         message: str = (
@@ -1035,7 +1045,7 @@ class EmptyStage(BaseAsyncStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         message: str = (
@@ -1200,7 +1210,7 @@ class BashStage(BaseRetryStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         bash: str = param2template(
@@ -1264,7 +1274,7 @@ class BashStage(BaseRetryStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         bash: str = param2template(
@@ -1394,21 +1404,21 @@ class PyStage(BaseRetryStage):
         to globals argument on `exec` build-in function.
 
         Args:
-            params: A parameter data that want to use in this
+            params (DictData): A parameter data that want to use in this
                 execution.
-            run_id: A running stage ID.
+            run_id (str): A running stage ID.
             context: A context data.
-            parent_run_id: A parent running ID. (Default is None)
+            parent_run_id (str | None, default None): A parent running ID.
             event: An event manager that use to track parent process
                 was not force stopped.
 
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
-        trace.info("[STAGE]: Prepare `globals` and `locals` variables.")
+        trace.debug("[STAGE]: Prepare `globals` and `locals` variables.")
         lc: DictData = {}
         gb: DictData = (
             globals()
@@ -1486,7 +1496,7 @@ class PyStage(BaseRetryStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         await trace.ainfo("[STAGE]: Prepare `globals` and `locals` variables.")
@@ -1631,7 +1641,7 @@ class CallStage(BaseRetryStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         call_func: TagFunc = self.get_caller(params=params)()
@@ -1750,7 +1760,7 @@ class CallStage(BaseRetryStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         call_func: TagFunc = self.get_caller(params=params)()
@@ -1884,7 +1894,7 @@ class CallStage(BaseRetryStage):
                 "Validate argument from the caller function raise invalid type."
             ) from e
         except TypeError as e:
-            trace: TraceManager = get_trace(
+            trace: Trace = get_trace(
                 run_id, parent_run_id=parent_run_id, extras=extras
             )
             trace.warning(
@@ -1963,6 +1973,9 @@ class TriggerStage(BaseNestedStage):
     execute method. This is the stage that allow you to create the reusable
     Workflow template with dynamic parameters.
 
+        This stage does not allow to pass the workflow model directly to the
+    trigger field. A trigger workflow name should exist on the config path only.
+
     Data Validate:
         >>> stage = {
         ...     "name": "Trigger workflow stage execution",
@@ -2009,11 +2022,22 @@ class TriggerStage(BaseNestedStage):
         """
         from .workflow import Workflow
 
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         _trigger: str = param2template(self.trigger, params, extras=self.extras)
-        trace.info(f"[STAGE]: Load workflow: {_trigger!r}")
+        # if _trigger in self.extras.get("stop_circle_workflow_name", []):
+        #     raise StageError(
+        #         "[NESTED]: Circle execution via trigger itself workflow name."
+        #     )
+        trace.info(f"[NESTED]: Load Workflow Config: {_trigger!r}")
+
+        # # NOTE: add noted key for cancel circle execution.
+        # if "stop_circle_workflow_name" in self.extras:
+        #     self.extras["stop_circle_workflow_name"].append(_trigger)
+        # else:
+        #     self.extras.update({"stop_circle_workflow_name": [_trigger]})
+
         result: Result = Workflow.from_conf(
             name=pass_env(_trigger),
             extras=self.extras,
@@ -2024,16 +2048,16 @@ class TriggerStage(BaseNestedStage):
             event=event,
         )
         if result.status == FAILED:
-            err_msg: StrOrNone = (
+            err_msg: str = (
                 f" with:\n{msg}"
                 if (msg := result.context.get("errors", {}).get("message"))
                 else "."
             )
-            raise StageError(f"Trigger workflow was failed{err_msg}")
+            raise StageNestedError(f"Trigger workflow was failed{err_msg}")
         elif result.status == CANCEL:
-            raise StageCancelError("Trigger workflow was cancel.")
+            raise StageNestedCancelError("Trigger workflow was cancel.")
         elif result.status == SKIP:
-            raise StageSkipError("Trigger workflow was skipped.")
+            raise StageNestedSkipError("Trigger workflow was skipped.")
         return result
 
 
@@ -2098,26 +2122,29 @@ class ParallelStage(BaseNestedStage):
         """Execute branch that will execute all nested-stage that was set in
         this stage with specific branch ID.
 
-        :param branch: (str) A branch ID.
-        :param params: (DictData) A parameter data.
-        :param run_id: (str)
-        :param context: (DictData)
-        :param parent_run_id: (str | None)
-        :param event: (Event) An Event manager instance that use to cancel this
-            execution if it forces stopped by parent execution.
-            (Default is None)
+        Args:
+            branch (str): A branch ID.
+            params (DictData): A parameter data.
+            run_id (str): A running ID.
+            context (DictData):
+            parent_run_id (str | None, default None): A parent running ID.
+            event: (Event) An Event manager instance that use to cancel this
+                execution if it forces stopped by parent execution.
+                (Default is None)
 
-        :raise StageCancelError: If event was set.
-        :raise StageCancelError: If result from a nested-stage return canceled
-            status.
-        :raise StageError: If result from a nested-stage return failed status.
+        Raises:
+            StageCancelError: If event was set.
+            StageCancelError: If result from a nested-stage return canceled
+                status.
+            StageError: If result from a nested-stage return failed status.
 
-        :rtype: tuple[Status, DictData]
+        Returns:
+            tuple[Status, DictData]: A pair of status and result context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
-        trace.debug(f"[STAGE]: Execute Branch: {branch!r}")
+        trace.debug(f"[NESTED]: Execute Branch: {branch!r}")
 
         # NOTE: Create nested-context
         current_context: DictData = copy.deepcopy(params)
@@ -2244,11 +2271,11 @@ class ParallelStage(BaseNestedStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         event: Event = event or Event()
-        trace.info(f"[STAGE]: Parallel with {self.max_workers} workers.")
+        trace.info(f"[NESTED]: Parallel with {self.max_workers} workers.")
         catch(
             context=context,
             status=WAIT,
@@ -2383,10 +2410,10 @@ class ForEachStage(BaseNestedStage):
 
         :rtype: tuple[Status, Result]
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
-        trace.debug(f"[STAGE]: Execute Item: {item!r}")
+        trace.debug(f"[NESTED]: Execute Item: {item!r}")
         key: StrOrInt = index if self.use_index_as_key else item
 
         # NOTE: Create nested-context data from the passing context.
@@ -2442,7 +2469,7 @@ class ForEachStage(BaseNestedStage):
                     f"Item execution was break because its nested-stage, "
                     f"{stage.iden!r}, failed."
                 )
-                trace.warning(f"[STAGE]: {error_msg}")
+                trace.warning(f"[NESTED]: {error_msg}")
                 catch(
                     context=context,
                     status=FAILED,
@@ -2520,7 +2547,7 @@ class ForEachStage(BaseNestedStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         event: Event = event or Event()
@@ -2552,7 +2579,7 @@ class ForEachStage(BaseNestedStage):
                 "duplicate item, it should set `use_index_as_key: true`."
             )
 
-        trace.info(f"[STAGE]: Foreach: {foreach!r}.")
+        trace.info(f"[NESTED]: Foreach: {foreach!r}.")
         catch(
             context=context,
             status=WAIT,
@@ -2586,7 +2613,7 @@ class ForEachStage(BaseNestedStage):
             done, not_done = wait(futures, return_when=FIRST_EXCEPTION)
             if len(list(done)) != len(futures):
                 trace.warning(
-                    "[STAGE]: Set the event for stop pending for-each stage."
+                    "[NESTED]: Set the event for stop pending for-each stage."
                 )
                 event.set()
                 for future in not_done:
@@ -2601,7 +2628,7 @@ class ForEachStage(BaseNestedStage):
                     if not_done
                     else ""
                 )
-                trace.debug(f"[STAGE]: ... Foreach-Stage set failed event{nd}")
+                trace.debug(f"[NESTED]: ... Foreach-Stage set failed event{nd}")
                 done: Iterator[Future] = as_completed(futures)
                 fail_fast = True
 
@@ -2705,10 +2732,10 @@ class UntilStage(BaseNestedStage):
         :rtype: tuple[Status, DictData, T]
         :return: Return a pair of Result and changed item.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
-        trace.debug(f"[STAGE]: Execute Loop: {loop} (Item {item!r})")
+        trace.debug(f"[NESTED]: Execute Loop: {loop} (Item {item!r})")
 
         # NOTE: Create nested-context
         current_context: DictData = copy.deepcopy(params)
@@ -2777,11 +2804,11 @@ class UntilStage(BaseNestedStage):
                             "stages": filter_func(
                                 nestet_context.pop("stages", {})
                             ),
-                            "errors": StageError(error_msg).to_dict(),
+                            "errors": StageNestedError(error_msg).to_dict(),
                         }
                     },
                 )
-                raise StageError(error_msg, refs=loop)
+                raise StageNestedError(error_msg, refs=loop)
 
             elif rs.status == CANCEL:
                 error_msg: str = (
@@ -2799,11 +2826,13 @@ class UntilStage(BaseNestedStage):
                             "stages": filter_func(
                                 nestet_context.pop("stages", {})
                             ),
-                            "errors": StageCancelError(error_msg).to_dict(),
+                            "errors": StageNestedCancelError(
+                                error_msg
+                            ).to_dict(),
                         }
                     },
                 )
-                raise StageCancelError(error_msg, refs=loop)
+                raise StageNestedCancelError(error_msg, refs=loop)
 
         status: Status = SKIP if sum(skips) == total_stage else SUCCESS
         return (
@@ -2847,11 +2876,11 @@ class UntilStage(BaseNestedStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         event: Event = event or Event()
-        trace.info(f"[STAGE]: Until: {self.until!r}")
+        trace.info(f"[NESTED]: Until: {self.until!r}")
         item: Union[str, int, bool] = pass_env(
             param2template(self.item, params, extras=self.extras)
         )
@@ -2881,7 +2910,7 @@ class UntilStage(BaseNestedStage):
             if item is None:
                 item: int = loop
                 trace.warning(
-                    f"[STAGE]: Return loop not set the item. It uses loop: "
+                    f"[NESTED]: Return loop not set the item. It uses loop: "
                     f"{loop} by default."
                 )
 
@@ -2999,10 +3028,10 @@ class CaseStage(BaseNestedStage):
 
         :rtype: DictData
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
-        trace.debug(f"[STAGE]: Execute Case: {case!r}")
+        trace.debug(f"[NESTED]: Execute Case: {case!r}")
         current_context: DictData = copy.deepcopy(params)
         current_context.update({"case": case})
         output: DictData = {"case": case, "stages": {}}
@@ -3080,23 +3109,27 @@ class CaseStage(BaseNestedStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
 
         _case: StrOrNone = param2template(self.case, params, extras=self.extras)
+        trace.info(f"[NESTED]: Get Case: {_case!r}.")
 
-        trace.info(f"[STAGE]: Case: {_case!r}.")
         _else: Optional[Match] = None
         stages: Optional[list[Stage]] = None
+
+        # NOTE: Start check the condition of each stage match with this case.
         for match in self.match:
+            # NOTE: Store the else case.
             if (c := match.case) == "_":
                 _else: Match = match
                 continue
 
             _condition: str = param2template(c, params, extras=self.extras)
-            if stages is None and pass_env(_case) == pass_env(_condition):
+            if pass_env(_case) == pass_env(_condition):
                 stages: list[Stage] = match.stages
+                break
 
         if stages is None:
             if _else is None:
@@ -3110,6 +3143,7 @@ class CaseStage(BaseNestedStage):
                     "case and the else condition does not set too."
                 )
 
+            # NOTE: Force to use the else when it does not match any case.
             _case: str = "_"
             stages: list[Stage] = _else.stages
 
@@ -3178,7 +3212,7 @@ class RaiseStage(BaseAsyncStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         message: str = param2template(self.message, params, extras=self.extras)
@@ -3209,7 +3243,7 @@ class RaiseStage(BaseAsyncStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         message: str = param2template(self.message, params, extras=self.extras)
@@ -3290,7 +3324,7 @@ class DockerStage(BaseStage):  # pragma: no cov
                 "by `pip install docker` first."
             ) from None
 
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         client = DockerClient(
@@ -3390,7 +3424,7 @@ class DockerStage(BaseStage):  # pragma: no cov
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         trace.info(f"[STAGE]: Docker: {self.image}:{self.tag}")
@@ -3403,8 +3437,11 @@ class VirtualPyStage(PyStage):  # pragma: no cov
     """
 
     version: str = Field(
-        default="3.9",
-        description="A Python version that want to run.",
+        default=__python_version__,
+        description=(
+            "A Python version that want to run. It will use supported version "
+            f"of this package by default, {__python_version__}."
+        ),
     )
     deps: list[str] = Field(
         description=(
@@ -3427,11 +3464,12 @@ class VirtualPyStage(PyStage):  # pragma: no cov
             The format of Python dependency was followed by the `uv`
         recommended.
 
-        :param py: A Python string statement.
-        :param values: A variable that want to set before running this
-        :param deps: An additional Python dependencies that want install before
-            run this python stage.
-        :param run_id: (StrOrNone) A running ID of this stage execution.
+        Args:
+            py: A Python string statement.
+            values: A variable that want to set before running this
+            deps: An additional Python dependencies that want install before
+                run this python stage.
+            run_id: (StrOrNone) A running ID of this stage execution.
         """
         run_id: str = run_id or uuid.uuid4()
         f_name: str = f"{run_id}.py"
@@ -3500,7 +3538,7 @@ class VirtualPyStage(PyStage):  # pragma: no cov
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         run: str = param2template(dedent(self.run), params, extras=self.extras)