ddeutil-workflow 0.0.56__py3-none-any.whl → 0.0.58__py3-none-any.whl

ddeutil/workflow/stages.py

@@ -3,7 +3,6 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-# [x] Use dynamic config
 """Stages module include all stage model that use be the minimum execution layer
 of this workflow engine. The stage handle the minimize task that run in some
 thread (same thread at its job owner) that mean it is the lowest executor that
@@ -16,11 +15,11 @@ have a lot of use-case, and it should does not worry about it error output.
     So, I will create `handler_execute` for any exception class that raise from
 the stage execution method.
 
-    Execution   --> Ok      ---( handler )--> Result with `SUCCESS` or `CANCEL`
-
-                --> Error   ┬--( handler )-> Result with `FAILED` (Set `raise_error` flag)
+    Execution   --> Ok      ┬--( handler )--> Result with `SUCCESS` or `CANCEL`
                             |
-                            ╰--( handler )-> Raise StageException(...)
+                            ╰--( handler )--> Result with `FAILED` (Set `raise_error` flag)
+
+                --> Error   ---( handler )--> Raise StageException(...)
 
     On the context I/O that pass to a stage object at execute process. The
 execute method receives a `params={"params": {...}}` value for passing template
@@ -41,6 +40,7 @@ from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Iterator
 from concurrent.futures import (
     FIRST_EXCEPTION,
+    CancelledError,
     Future,
     ThreadPoolExecutor,
     as_completed,
@@ -58,13 +58,12 @@ from pydantic import BaseModel, Field
 from pydantic.functional_validators import model_validator
 from typing_extensions import Self
 
-from .__types import DictData, DictStr, TupleStr
+from .__types import DictData, DictStr, StrOrInt, TupleStr
 from .conf import dynamic
-from .exceptions import StageException, UtilException, to_dict
+from .exceptions import StageException, to_dict
 from .result import CANCEL, FAILED, SUCCESS, WAIT, Result, Status
 from .reusables import TagFunc, extract_call, not_in_template, param2template
 from .utils import (
-    NEWLINE,
     delay,
     filter_func,
     gen_id,
@@ -72,7 +71,6 @@ from .utils import (
 )
 
 T = TypeVar("T")
-StrOrInt = Union[str, int]
 
 
 class BaseStage(BaseModel, ABC):
@@ -174,17 +172,23 @@ class BaseStage(BaseModel, ABC):
 
             This stage exception handler still use ok-error concept, but it
         allows you force catching an output result with error message by
-        specific environment variable,`WORKFLOW_CORE_STAGE_RAISE_ERROR`.
+        specific environment variable,`WORKFLOW_CORE_STAGE_RAISE_ERROR` or set
+        `raise_error` parameter to True.
 
             Execution   --> Ok      --> Result
                                         |-status: SUCCESS
                                         ╰-context:
                                             ╰-outputs: ...
 
-                        --> Error   --> Result (if `raise_error` was set)
+                        --> Ok      --> Result
+                                        |-status: CANCEL
+                                        ╰-errors:
+                                            |-name: ...
+                                            ╰-message: ...
+
+                        --> Ok      --> Result (if `raise_error` was set)
                                         |-status: FAILED
                                         ╰-errors:
-                                            |-class: ...
                                             |-name: ...
                                             ╰-message: ...
 
@@ -201,6 +205,9 @@ class BaseStage(BaseModel, ABC):
         :param event: (Event) An event manager that pass to the stage execution.
         :param raise_error: (bool) A flag that all this method raise error
 
+        :raise StageException: If the raise_error was set and the execution
+            raise any error.
+
         :rtype: Result
         """
         result: Result = Result.construct_with_rs_or_id(
@@ -210,20 +217,17 @@ class BaseStage(BaseModel, ABC):
             id_logic=self.iden,
             extras=self.extras,
         )
-
         try:
             return self.execute(params, result=result, event=event)
         except Exception as e:
             e_name: str = e.__class__.__name__
-            result.trace.error(f"[STAGE]: Handler:{NEWLINE}{e_name}: {e}")
+            result.trace.error(f"[STAGE]: Error Handler:||{e_name}:||{e}")
             if dynamic("stage_raise_error", f=raise_error, extras=self.extras):
                 if isinstance(e, StageException):
                     raise
-
                 raise StageException(
-                    f"{self.__class__.__name__}: {NEWLINE}{e_name}: {e}"
+                    f"{self.__class__.__name__}: {e_name}: {e}"
                 ) from e
-
             return result.catch(status=FAILED, context={"errors": to_dict(e)})
 
     def set_outputs(self, output: DictData, to: DictData) -> DictData:
@@ -273,13 +277,6 @@ class BaseStage(BaseModel, ABC):
         ):
             return to
 
-        _id: str = (
-            param2template(self.id, params=to, extras=self.extras)
-            if self.id
-            else gen_id(
-                param2template(self.name, params=to, extras=self.extras)
-            )
-        )
         output: DictData = output.copy()
         errors: DictData = (
             {"errors": output.pop("errors", {})} if "errors" in output else {}
@@ -289,7 +286,7 @@ class BaseStage(BaseModel, ABC):
             if "skipped" in output
             else {}
         )
-        to["stages"][_id] = {
+        to["stages"][self.gen_id(params=to)] = {
             "outputs": copy.deepcopy(output),
             **skipping,
             **errors,
@@ -309,15 +306,11 @@ class BaseStage(BaseModel, ABC):
             "stage_default_id", extras=self.extras
         ):
             return {}
-
-        _id: str = (
-            param2template(self.id, params=output, extras=self.extras)
-            if self.id
-            else gen_id(
-                param2template(self.name, params=output, extras=self.extras)
-            )
+        return (
+            output.get("stages", {})
+            .get(self.gen_id(params=output), {})
+            .get("outputs", {})
         )
-        return output.get("stages", {}).get(_id, {}).get("outputs", {})
 
     def is_skipped(self, params: DictData) -> bool:
         """Return true if condition of this stage do not correct. This process
@@ -351,6 +344,22 @@ class BaseStage(BaseModel, ABC):
         except Exception as e:
             raise StageException(f"{e.__class__.__name__}: {e}") from e
 
+    def gen_id(self, params: DictData) -> str:
+        """Generate stage ID that dynamic use stage's name if it ID does not
+        set.
+
+        :param params: A parameter data.
+
+        :rtype: str
+        """
+        return (
+            param2template(self.id, params=params, extras=self.extras)
+            if self.id
+            else gen_id(
+                param2template(self.name, params=params, extras=self.extras)
+            )
+        )
+
 
 class BaseAsyncStage(BaseStage):
     """Base Async Stage model to make any stage model allow async execution for
@@ -431,15 +440,14 @@ class BaseAsyncStage(BaseStage):
         try:
             rs: Result = await self.axecute(params, result=result, event=event)
             return rs
-        except Exception as e:  # pragma: no cov
+        except Exception as e:
             e_name: str = e.__class__.__name__
             await result.trace.aerror(f"[STAGE]: Handler {e_name}: {e}")
             if dynamic("stage_raise_error", f=raise_error, extras=self.extras):
                 if isinstance(e, StageException):
                     raise
-
                 raise StageException(
-                    f"{self.__class__.__name__}: {NEWLINE}{e_name}: {e}"
+                    f"{self.__class__.__name__}: {e_name}: {e}"
                 ) from None
 
             return result.catch(status=FAILED, context={"errors": to_dict(e)})
@@ -499,18 +507,16 @@ class EmptyStage(BaseAsyncStage):
             run_id=gen_id(self.name + (self.id or ""), unique=True),
             extras=self.extras,
         )
-
-        if not self.echo:
-            message: str = "..."
-        else:
-            message: str = param2template(
+        message: str = (
+            param2template(
                 dedent(self.echo.strip("\n")), params, extras=self.extras
             )
-            if "\n" in message:
-                message: str = NEWLINE + message.replace("\n", NEWLINE)
+            if self.echo
+            else "..."
+        )
 
         result.trace.info(
-            f"[STAGE]: Empty-Execute: {self.name!r}: ( {message} )"
+            f"[STAGE]: Execute Empty-Stage: {self.name!r}: ( {message} )"
         )
         if self.sleep > 0:
             if self.sleep > 5:
@@ -540,18 +546,15 @@ class EmptyStage(BaseAsyncStage):
             extras=self.extras,
         )
 
-        if not self.echo:
-            message: str = "..."
-        else:
-            message: str = param2template(
+        message: str = (
+            param2template(
                 dedent(self.echo.strip("\n")), params, extras=self.extras
             )
-            if "\n" in message:
-                message: str = NEWLINE + message.replace("\n", NEWLINE)
-
-        result.trace.info(
-            f"[STAGE]: Empty-Execute: {self.name!r}: ( {message} )"
+            if self.echo
+            else "..."
         )
+
+        result.trace.info(f"[STAGE]: Empty-Stage: {self.name!r}: ( {message} )")
         if self.sleep > 0:
             if self.sleep > 5:
                 await result.trace.ainfo(
@@ -561,7 +564,7 @@ class EmptyStage(BaseAsyncStage):
         return result.catch(status=SUCCESS)
 
 
-class BashStage(BaseStage):
+class BashStage(BaseAsyncStage):
     """Bash stage executor that execute bash script on the current OS.
     If your current OS is Windows, it will run on the bash from the current WSL.
     It will use `bash` for Windows OS and use `sh` for Linux OS.
@@ -597,7 +600,16 @@ class BashStage(BaseStage):
     @contextlib.asynccontextmanager
     async def acreate_sh_file(
         self, bash: str, env: DictStr, run_id: str | None = None
-    ) -> AsyncIterator:  # pragma no cov
+    ) -> AsyncIterator[TupleStr]:
+        """Async create and write `.sh` file with the `aiofiles` package.
+
+        :param bash: (str) A bash statement.
+        :param env: (DictStr) An environment variable that set before run bash.
+        :param run_id: (str | None) A running stage ID that use for writing sh
+            file instead generate by UUID4.
+
+        :rtype: AsyncIterator[TupleStr]
+        """
         import aiofiles
 
         f_name: str = f"{run_id or uuid.uuid4()}.sh"
@@ -616,7 +628,7 @@ class BashStage(BaseStage):
         # NOTE: Make this .sh file able to executable.
         make_exec(f"./{f_name}")
 
-        yield [f_shebang, f_name]
+        yield f_shebang, f_name
 
         # Note: Remove .sh file that use to run bash.
         Path(f"./{f_name}").unlink()
@@ -625,9 +637,8 @@ class BashStage(BaseStage):
     def create_sh_file(
         self, bash: str, env: DictStr, run_id: str | None = None
     ) -> Iterator[TupleStr]:
-        """Return context of prepared bash statement that want to execute. This
-        step will write the `.sh` file before giving this file name to context.
-        After that, it will auto delete this file automatic.
+        """Create and write the `.sh` file before giving this file name to
+        context. After that, it will auto delete this file automatic.
 
         :param bash: (str) A bash statement.
         :param env: (DictStr) An environment variable that set before run bash.
@@ -635,6 +646,7 @@ class BashStage(BaseStage):
             file instead generate by UUID4.
 
         :rtype: Iterator[TupleStr]
+        :return: Return context of prepared bash statement that want to execute.
         """
         f_name: str = f"{run_id or uuid.uuid4()}.sh"
         f_shebang: str = "bash" if sys.platform.startswith("win") else "sh"
@@ -652,7 +664,7 @@ class BashStage(BaseStage):
         # NOTE: Make this .sh file able to executable.
         make_exec(f"./{f_name}")
 
-        yield [f_shebang, f_name]
+        yield f_shebang, f_name
 
         # Note: Remove .sh file that use to run bash.
         Path(f"./{f_name}").unlink()
@@ -680,7 +692,7 @@ class BashStage(BaseStage):
             extras=self.extras,
         )
 
-        result.trace.info(f"[STAGE]: Shell-Execute: {self.name}")
+        result.trace.info(f"[STAGE]: Execute Shell-Stage: {self.name}")
 
         bash: str = param2template(
             dedent(self.bash.strip("\n")), params, extras=self.extras
@@ -691,21 +703,74 @@ class BashStage(BaseStage):
             env=param2template(self.env, params, extras=self.extras),
             run_id=result.run_id,
         ) as sh:
-            result.trace.debug(f"... Create `{sh[1]}` file.")
+            result.trace.debug(f"[STAGE]: ... Create `{sh[1]}` file.")
             rs: CompletedProcess = subprocess.run(
-                sh, shell=False, capture_output=True, text=True
+                sh,
+                shell=False,
+                check=False,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+            )
+        if rs.returncode > 0:
+            e: str = rs.stderr.removesuffix("\n")
+            raise StageException(
+                f"Subprocess: {e}\n---( statement )---\n```bash\n{bash}\n```"
+            )
+        return result.catch(
+            status=SUCCESS,
+            context={
+                "return_code": rs.returncode,
+                "stdout": None if (out := rs.stdout.strip("\n")) == "" else out,
+                "stderr": None if (out := rs.stderr.strip("\n")) == "" else out,
+            },
+        )
+
+    async def axecute(
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
+    ) -> Result:
+        """Async execution method for this Bash stage that only logging out to
+        stdout.
+
+        :param params: (DictData) A parameter data.
+        :param result: (Result) A Result instance for return context and status.
+        :param event: (Event) An Event manager instance that use to cancel this
+            execution if it forces stopped by parent execution.
+
+        :rtype: Result
+        """
+        result: Result = result or Result(
+            run_id=gen_id(self.name + (self.id or ""), unique=True),
+            extras=self.extras,
+        )
+        await result.trace.ainfo(f"[STAGE]: Execute Shell-Stage: {self.name}")
+        bash: str = param2template(
+            dedent(self.bash.strip("\n")), params, extras=self.extras
+        )
+
+        async with self.acreate_sh_file(
+            bash=bash,
+            env=param2template(self.env, params, extras=self.extras),
+            run_id=result.run_id,
+        ) as sh:
+            await result.trace.adebug(f"[STAGE]: ... Create `{sh[1]}` file.")
+            rs: CompletedProcess = subprocess.run(
+                sh,
+                shell=False,
+                check=False,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
             )
 
         if rs.returncode > 0:
-            # NOTE: Prepare stderr message that returning from subprocess.
-            e: str = (
-                rs.stderr.encode("utf-8").decode("utf-16")
-                if "\\x00" in rs.stderr
-                else rs.stderr
-            ).removesuffix("\n")
+            e: str = rs.stderr.removesuffix("\n")
             raise StageException(
-                f"Subprocess: {e}\n---( statement )---\n"
-                f"```bash\n{bash}\n```"
+                f"Subprocess: {e}\n---( statement )---\n```bash\n{bash}\n```"
             )
         return result.catch(
             status=SUCCESS,
@@ -717,7 +782,7 @@ class BashStage(BaseStage):
         )
 
 
-class PyStage(BaseStage):
+class PyStage(BaseAsyncStage):
     """Python stage that running the Python statement with the current globals
     and passing an input additional variables via `exec` built-in function.
 
@@ -819,7 +884,7 @@ class PyStage(BaseStage):
             | {"result": result}
         )
 
-        result.trace.info(f"[STAGE]: Py-Execute: {self.name}")
+        result.trace.info(f"[STAGE]: Execute Py-Stage: {self.name}")
 
         # WARNING: The exec build-in function is very dangerous. So, it
         #   should use the re module to validate exec-string before running.
@@ -849,15 +914,63 @@ class PyStage(BaseStage):
 
     async def axecute(
         self,
-    ):
-        """Async execution method.
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
+    ) -> Result:
+        """Async execution method for this Bash stage that only logging out to
+        stdout.
+
+        :param params: (DictData) A parameter data.
+        :param result: (Result) A Result instance for return context and status.
+        :param event: (Event) An Event manager instance that use to cancel this
+            execution if it forces stopped by parent execution.
 
         References:
             - https://stackoverflow.com/questions/44859165/async-exec-in-python
+
+        :rtype: Result
         """
+        result: Result = result or Result(
+            run_id=gen_id(self.name + (self.id or ""), unique=True),
+            extras=self.extras,
+        )
+        lc: DictData = {}
+        gb: DictData = (
+            globals()
+            | param2template(self.vars, params, extras=self.extras)
+            | {"result": result}
+        )
+        await result.trace.ainfo(f"[STAGE]: Execute Py-Stage: {self.name}")
+
+        # WARNING: The exec build-in function is very dangerous. So, it
+        #   should use the re module to validate exec-string before running.
+        exec(
+            param2template(dedent(self.run), params, extras=self.extras),
+            gb,
+            lc,
+        )
+        return result.catch(
+            status=SUCCESS,
+            context={
+                "locals": {k: lc[k] for k in self.filter_locals(lc)},
+                "globals": {
+                    k: gb[k]
+                    for k in gb
+                    if (
+                        not k.startswith("__")
+                        and k != "annotations"
+                        and not ismodule(gb[k])
+                        and not isclass(gb[k])
+                        and not isfunction(gb[k])
+                    )
+                },
+            },
+        )
 
 
-class CallStage(BaseStage):
+class CallStage(BaseAsyncStage):
     """Call stage executor that call the Python function from registry with tag
     decorator function in `reusables` module and run it with input arguments.
 
@@ -933,7 +1046,7 @@ class CallStage(BaseStage):
         )()
 
         result.trace.info(
-            f"[STAGE]: Call-Execute: {call_func.name}@{call_func.tag}"
+            f"[STAGE]: Execute Call-Stage: {call_func.name}@{call_func.tag}"
         )
 
         # VALIDATE: check input task caller parameters that exists before
@@ -985,8 +1098,97 @@ class CallStage(BaseStage):
             rs: DictData = rs.model_dump(by_alias=True)
         elif not isinstance(rs, dict):
             raise TypeError(
-                f"Return type: '{call_func.name}@{call_func.tag}' does not "
-                f"serialize to result model, you change return type to `dict`."
+                f"Return type: '{call_func.name}@{call_func.tag}' can not "
+                f"serialize, you must set return be `dict` or Pydantic "
+                f"model."
+            )
+        return result.catch(status=SUCCESS, context=rs)
+
+    async def axecute(
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
+    ) -> Result:
+        """Async execution method for this Bash stage that only logging out to
+        stdout.
+
+        :param params: (DictData) A parameter data.
+        :param result: (Result) A Result instance for return context and status.
+        :param event: (Event) An Event manager instance that use to cancel this
+            execution if it forces stopped by parent execution.
+
+        References:
+            - https://stackoverflow.com/questions/44859165/async-exec-in-python
+
+        :rtype: Result
+        """
+        result: Result = result or Result(
+            run_id=gen_id(self.name + (self.id or ""), unique=True),
+            extras=self.extras,
+        )
+
+        call_func: TagFunc = extract_call(
+            param2template(self.uses, params, extras=self.extras),
+            registries=self.extras.get("registry_caller"),
+        )()
+
+        await result.trace.ainfo(
+            f"[STAGE]: Execute Call-Stage: {call_func.name}@{call_func.tag}"
+        )
+
+        # VALIDATE: check input task caller parameters that exists before
+        #   calling.
+        args: DictData = {"result": result} | param2template(
+            self.args, params, extras=self.extras
+        )
+        ips = inspect.signature(call_func)
+        necessary_params: list[str] = []
+        has_keyword: bool = False
+        for k in ips.parameters:
+            if (
+                v := ips.parameters[k]
+            ).default == Parameter.empty and v.kind not in (
+                Parameter.VAR_KEYWORD,
+                Parameter.VAR_POSITIONAL,
+            ):
+                necessary_params.append(k)
+            elif v.kind == Parameter.VAR_KEYWORD:
+                has_keyword = True
+
+        if any(
+            (k.removeprefix("_") not in args and k not in args)
+            for k in necessary_params
+        ):
+            raise ValueError(
+                f"Necessary params, ({', '.join(necessary_params)}, ), "
+                f"does not set to args, {list(args.keys())}."
+            )
+
+        if "result" not in ips.parameters and not has_keyword:
+            args.pop("result")
+
+        args = self.parse_model_args(call_func, args, result)
+
+        if inspect.iscoroutinefunction(call_func):
+            rs: DictData = await call_func(
+                **param2template(args, params, extras=self.extras)
+            )
+        else:
+            rs: DictData = call_func(
+                **param2template(args, params, extras=self.extras)
+            )
+
+        # VALIDATE:
+        #   Check the result type from call function, it should be dict.
+        if isinstance(rs, BaseModel):
+            rs: DictData = rs.model_dump(by_alias=True)
+        elif not isinstance(rs, dict):
+            raise TypeError(
+                f"Return type: '{call_func.name}@{call_func.tag}' can not "
+                f"serialize, you must set return be `dict` or Pydantic "
+                f"model."
             )
         return result.catch(status=SUCCESS, context=rs)
 
@@ -1078,7 +1280,6 @@ class TriggerStage(BaseStage):
 
         :rtype: Result
         """
-        from .exceptions import WorkflowException
         from .workflow import Workflow
 
         result: Result = result or Result(
@@ -1087,19 +1288,15 @@ class TriggerStage(BaseStage):
         )
 
         _trigger: str = param2template(self.trigger, params, extras=self.extras)
-        result.trace.info(f"[STAGE]: Trigger-Execute: {_trigger!r}")
-        try:
-            rs: Result = Workflow.from_conf(
-                name=_trigger,
-                extras=self.extras | {"stage_raise_error": True},
-            ).execute(
-                params=param2template(self.params, params, extras=self.extras),
-                parent_run_id=result.run_id,
-                event=event,
-            )
-        except WorkflowException as e:
-            raise StageException("Trigger workflow stage was failed") from e
-
+        result.trace.info(f"[STAGE]: Execute Trigger-Stage: {_trigger!r}")
+        rs: Result = Workflow.from_conf(
+            name=_trigger,
+            extras=self.extras | {"stage_raise_error": True},
+        ).execute(
+            params=param2template(self.params, params, extras=self.extras),
+            parent_run_id=result.run_id,
+            event=event,
+        )
         if rs.status == FAILED:
             err_msg: str | None = (
                 f" with:\n{msg}"
@@ -1107,12 +1304,43 @@ class TriggerStage(BaseStage):
                 else "."
             )
             raise StageException(
-                f"Trigger workflow return failed status{err_msg}"
+                f"Trigger workflow return `FAILED` status{err_msg}"
             )
         return rs
 
 
-class ParallelStage(BaseStage):  # pragma: no cov
+class BaseNestedStage(BaseStage):
+    """Base Nested Stage model. This model is use for checking the child stage
+    is the nested stage or not.
+    """
+
+    @abstractmethod
+    def execute(
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
+    ) -> Result:
+        """Execute abstraction method that action something by sub-model class.
+        This is important method that make this class is able to be the nested
+        stage.
+
+        :param params: (DictData) A parameter data that want to use in this
+            execution.
+        :param result: (Result) A result object for keeping context and status
+            data.
+        :param event: (Event) An event manager that use to track parent execute
+            was not force stopped.
+
+        :rtype: Result
+        """
+        raise NotImplementedError(
+            "Nested-Stage should implement `execute` method."
+        )
+
+
+class ParallelStage(BaseNestedStage):
     """Parallel stage executor that execute branch stages with multithreading.
     This stage let you set the fix branches for running child stage inside it on
     multithread pool.
@@ -1193,7 +1421,7 @@ class ParallelStage(BaseStage):  # pragma: no cov
                     "Branch-Stage was canceled from event that had set before "
                     "stage branch execution."
                 )
-                return result.catch(
+                result.catch(
                     status=CANCEL,
                     parallel={
                         branch: {
@@ -1203,6 +1431,7 @@ class ParallelStage(BaseStage):  # pragma: no cov
                         }
                     },
                 )
+                raise StageException(error_msg, refs=branch)
 
             try:
                 rs: Result = stage.handler_execute(
@@ -1214,10 +1443,7 @@ class ParallelStage(BaseStage):  # pragma: no cov
                 )
                 stage.set_outputs(rs.context, to=output)
                 stage.set_outputs(stage.get_outputs(output), to=context)
-            except (StageException, UtilException) as e:  # pragma: no cov
-                result.trace.error(
-                    f"[STAGE]: {e.__class__.__name__}:{NEWLINE}{e}"
-                )
+            except StageException as e:
                 result.catch(
                     status=FAILED,
                     parallel={
@@ -1228,9 +1454,7 @@ class ParallelStage(BaseStage):  # pragma: no cov
                         },
                     },
                 )
-                raise StageException(
-                    f"Sub-Stage raise: {e.__class__.__name__}: {e}"
-                ) from None
+                raise StageException(str(e), refs=branch) from e
 
             if rs.status == FAILED:
                 error_msg: str = (
@@ -1247,7 +1471,7 @@ class ParallelStage(BaseStage):  # pragma: no cov
                         },
                     },
                 )
-                raise StageException(error_msg)
+                raise StageException(error_msg, refs=branch)
 
         return result.catch(
             status=SUCCESS,
@@ -1279,12 +1503,12 @@ class ParallelStage(BaseStage):  # pragma: no cov
             run_id=gen_id(self.name + (self.id or ""), unique=True),
             extras=self.extras,
         )
-        event: Event = Event() if event is None else event
+        event: Event = event or Event()
         result.trace.info(
-            f"[STAGE]: Parallel-Execute: {self.max_workers} workers."
+            f"[STAGE]: Execute Parallel-Stage: {self.max_workers} workers."
         )
         result.catch(status=WAIT, context={"parallel": {}})
-        if event and event.is_set():  # pragma: no cov
+        if event and event.is_set():
             return result.catch(
                 status=CANCEL,
                 context={
@@ -1318,17 +1542,14 @@ class ParallelStage(BaseStage):  # pragma: no cov
                     future.result()
                 except StageException as e:
                     status = FAILED
-                    result.trace.error(
-                        f"[STAGE]: {e.__class__.__name__}:{NEWLINE}{e}"
-                    )
                     if "errors" in context:
-                        context["errors"].append(e.to_dict())
+                        context["errors"][e.refs] = e.to_dict()
                     else:
-                        context["errors"] = [e.to_dict()]
+                        context["errors"] = e.to_dict(with_refs=True)
         return result.catch(status=status, context=context)
 
 
-class ForEachStage(BaseStage):
+class ForEachStage(BaseNestedStage):
     """For-Each stage executor that execute all stages with each item in the
     foreach list.
 
@@ -1369,30 +1590,43 @@ class ForEachStage(BaseStage):
             "will be sequential mode if this value equal 1."
         ),
     )
+    use_index_as_key: bool = Field(
+        default=False,
+        description=(
+            "A flag for using the loop index as a key instead item value. "
+            "This flag allow to skip checking duplicate item step."
+        ),
+    )
 
     def execute_item(
         self,
+        index: int,
         item: StrOrInt,
         params: DictData,
         result: Result,
         *,
         event: Event | None = None,
     ) -> Result:
-        """Execute all stage with specific foreach item.
+        """Execute all nested stage that set on this stage with specific foreach
+        item parameter.
 
+        :param index: (int) An index value of foreach loop.
         :param item: (str | int) An item that want to execution.
         :param params: (DictData) A parameter data.
         :param result: (Result) A Result instance for return context and status.
         :param event: (Event) An Event manager instance that use to cancel this
             execution if it forces stopped by parent execution.
 
-        :raise StageException: If the stage execution raise errors.
+        :raise StageException: If event was set.
+        :raise StageException: If the stage execution raise any Exception error.
+        :raise StageException: If the result from execution has `FAILED` status.
 
         :rtype: Result
         """
         result.trace.debug(f"[STAGE]: Execute Item: {item!r}")
+        key: StrOrInt = index if self.use_index_as_key else item
         context: DictData = copy.deepcopy(params)
-        context.update({"item": item})
+        context.update({"item": item, "loop": index})
         output: DictData = {"item": item, "stages": {}}
         for stage in self.stages:
 
@@ -1404,21 +1638,21 @@ class ForEachStage(BaseStage):
                 stage.set_outputs(output={"skipped": True}, to=output)
                 continue
 
-            if event and event.is_set():  # pragma: no cov
+            if event and event.is_set():
                 error_msg: str = (
-                    "Item-Stage was canceled from event that had set before "
-                    "stage item execution."
+                    "Item-Stage was canceled because event was set."
                 )
-                return result.catch(
+                result.catch(
                     status=CANCEL,
                     foreach={
-                        item: {
+                        key: {
                             "item": item,
                             "stages": filter_func(output.pop("stages", {})),
                             "errors": StageException(error_msg).to_dict(),
                         }
                     },
                 )
+                raise StageException(error_msg, refs=key)
 
             try:
                 rs: Result = stage.handler_execute(
@@ -1430,23 +1664,18 @@ class ForEachStage(BaseStage):
                 )
                 stage.set_outputs(rs.context, to=output)
                 stage.set_outputs(stage.get_outputs(output), to=context)
-            except (StageException, UtilException) as e:
-                result.trace.error(
-                    f"[STAGE]: {e.__class__.__name__}:{NEWLINE}{e}"
-                )
+            except StageException as e:
                 result.catch(
                     status=FAILED,
                     foreach={
-                        item: {
+                        key: {
                             "item": item,
                             "stages": filter_func(output.pop("stages", {})),
                             "errors": e.to_dict(),
                         },
                     },
                 )
-                raise StageException(
-                    f"Sub-Stage raise: {e.__class__.__name__}: {e}"
-                ) from None
+                raise StageException(str(e), refs=key) from e
 
             if rs.status == FAILED:
                 error_msg: str = (
@@ -1457,19 +1686,19 @@ class ForEachStage(BaseStage):
                 result.catch(
                     status=FAILED,
                     foreach={
-                        item: {
+                        key: {
                             "item": item,
                             "stages": filter_func(output.pop("stages", {})),
                             "errors": StageException(error_msg).to_dict(),
                         },
                     },
                 )
-                raise StageException(error_msg)
+                raise StageException(error_msg, refs=key)
 
         return result.catch(
             status=SUCCESS,
             foreach={
-                item: {
+                key: {
                     "item": item,
                     "stages": filter_func(output.pop("stages", {})),
                 },
@@ -1498,7 +1727,7 @@ class ForEachStage(BaseStage):
             run_id=gen_id(self.name + (self.id or ""), unique=True),
             extras=self.extras,
         )
-        event: Event = Event() if event is None else event
+        event: Event = event or Event()
         foreach: Union[list[str], list[int]] = (
             param2template(self.foreach, params, extras=self.extras)
             if isinstance(self.foreach, str)
@@ -1508,10 +1737,15 @@ class ForEachStage(BaseStage):
         # [VALIDATE]: Type of the foreach should be `list` type.
         if not isinstance(foreach, list):
             raise TypeError(f"Does not support foreach: {foreach!r}")
+        elif len(set(foreach)) != len(foreach) and not self.use_index_as_key:
+            raise ValueError(
+                "Foreach item should not duplicate. If this stage must to pass "
+                "duplicate item, it should set `use_index_as_key: true`."
+            )
 
-        result.trace.info(f"[STAGE]: Foreach-Execute: {foreach!r}.")
+        result.trace.info(f"[STAGE]: Execute Foreach-Stage: {foreach!r}.")
         result.catch(status=WAIT, context={"items": foreach, "foreach": {}})
-        if event and event.is_set():  # pragma: no cov
+        if event and event.is_set():
             return result.catch(
                 status=CANCEL,
                 context={
@@ -1529,12 +1763,13 @@ class ForEachStage(BaseStage):
             futures: list[Future] = [
                 executor.submit(
                     self.execute_item,
+                    index=i,
                     item=item,
                     params=params,
                     result=result,
                     event=event,
                 )
-                for item in foreach
+                for i, item in enumerate(foreach, start=0)
             ]
             context: DictData = {}
             status: Status = SUCCESS
@@ -1542,28 +1777,41 @@ class ForEachStage(BaseStage):
             done, not_done = wait(futures, return_when=FIRST_EXCEPTION)
             if len(done) != len(futures):
                 result.trace.warning(
-                    "[STAGE]: Set event for stop pending stage future."
+                    "[STAGE]: Set event for stop pending for-each stage."
                 )
                 event.set()
                 for future in not_done:
                     future.cancel()
+                time.sleep(0.075)
 
-                nd: str = f", item not run: {not_done}" if not_done else ""
-                result.trace.debug(f"... Foreach set Fail-Fast{nd}")
+                nd: str = (
+                    (
+                        f", {len(not_done)} item"
+                        f"{'s' if len(not_done) > 1 else ''} not run!!!"
+                    )
+                    if not_done
+                    else ""
+                )
+                result.trace.debug(
+                    f"[STAGE]: ... Foreach-Stage set failed event{nd}"
+                )
+                done: list[Future] = as_completed(futures)
 
             for future in done:
                 try:
                     future.result()
                 except StageException as e:
                     status = FAILED
-                    result.trace.error(
-                        f"[STAGE]: {e.__class__.__name__}:{NEWLINE}{e}"
-                    )
-                    context.update({"errors": e.to_dict()})
+                    if "errors" in context:
+                        context["errors"][e.refs] = e.to_dict()
+                    else:
+                        context["errors"] = e.to_dict(with_refs=True)
+                except CancelledError:
+                    pass
         return result.catch(status=status, context=context)
 
 
-class UntilStage(BaseStage):
+class UntilStage(BaseNestedStage):
     """Until stage executor that will run stages in each loop until it valid
     with stop loop condition.
 
@@ -1628,7 +1876,7 @@ class UntilStage(BaseStage):
         :rtype: tuple[Result, T]
         :return: Return a pair of Result and changed item.
         """
-        result.trace.debug(f"... Execute until item: {item!r}")
+        result.trace.debug(f"[STAGE]: ... Execute until item: {item!r}")
         context: DictData = copy.deepcopy(params)
         context.update({"item": item})
         output: DictData = {"loop": loop, "item": item, "stages": {}}
@@ -1677,10 +1925,7 @@ class UntilStage(BaseStage):
                     next_item = _output["item"]
 
                 stage.set_outputs(_output, to=context)
-            except (StageException, UtilException) as e:
-                result.trace.error(
-                    f"[STAGE]: {e.__class__.__name__}:{NEWLINE}{e}"
-                )
+            except StageException as e:
                 result.catch(
                     status=FAILED,
                     until={
@@ -1692,9 +1937,7 @@ class UntilStage(BaseStage):
                         }
                     },
                 )
-                raise StageException(
-                    f"Sub-Stage execution error: {e.__class__.__name__}: {e}"
-                ) from None
+                raise
 
             if rs.status == FAILED:
                 error_msg: str = (
@@ -1749,7 +1992,7 @@ class UntilStage(BaseStage):
             extras=self.extras,
         )
 
-        result.trace.info(f"[STAGE]: Until-Execution: {self.until}")
+        result.trace.info(f"[STAGE]: Execute Until-Stage: {self.until}")
         item: Union[str, int, bool] = param2template(
             self.item, params, extras=self.extras
         )
@@ -1781,7 +2024,7 @@ class UntilStage(BaseStage):
             loop += 1
             if item is None:
                 result.trace.warning(
-                    f"... Loop-Execute not set item. It use loop: {loop} by "
+                    f"[STAGE]: ... Loop-Execute not set item. It use loop: {loop} by "
                     f"default."
                 )
                 item: int = loop
@@ -1819,7 +2062,7 @@ class Match(BaseModel):
     )
 
 
-class CaseStage(BaseStage):
+class CaseStage(BaseNestedStage):
     """Case stage executor that execute all stages if the condition was matched.
 
     Data Validate:
@@ -1892,11 +2135,11 @@ class CaseStage(BaseStage):
                 stage.extras = self.extras
 
             if stage.is_skipped(params=context):
-                result.trace.info(f"... Skip stage: {stage.iden!r}")
+                result.trace.info(f"[STAGE]: ... Skip stage: {stage.iden!r}")
                 stage.set_outputs(output={"skipped": True}, to=output)
                 continue
 
-            if event and event.is_set():  # pragma: no cov
+            if event and event.is_set():
                 error_msg: str = (
                     "Case-Stage was canceled from event that had set before "
                     "stage case execution."
@@ -1920,8 +2163,7 @@ class CaseStage(BaseStage):
                 )
                 stage.set_outputs(rs.context, to=output)
                 stage.set_outputs(stage.get_outputs(output), to=context)
-            except (StageException, UtilException) as e:  # pragma: no cov
-                result.trace.error(f"[STAGE]: {e.__class__.__name__}: {e}")
+            except StageException as e:
                 return result.catch(
                     status=FAILED,
                     context={
@@ -1977,7 +2219,7 @@ class CaseStage(BaseStage):
             self.case, params, extras=self.extras
         )
 
-        result.trace.info(f"[STAGE]: Case-Execute: {_case!r}.")
+        result.trace.info(f"[STAGE]: Execute Case-Stage: {_case!r}.")
         _else: Optional[Match] = None
         stages: Optional[list[Stage]] = None
         for match in self.match:
@@ -1997,7 +2239,7 @@ class CaseStage(BaseStage):
                         "any case."
                     )
                 result.trace.info(
-                    "... Skip this stage because it does not match."
+                    "[STAGE]: ... Skip this stage because it does not match."
                 )
                 error_msg: str = (
                     "Case-Stage was canceled because it does not match any "
@@ -2010,7 +2252,7 @@ class CaseStage(BaseStage):
             _case: str = "_"
             stages: list[Stage] = _else.stages
 
-        if event and event.is_set():  # pragma: no cov
+        if event and event.is_set():
             return result.catch(
                 status=CANCEL,
                 context={
@@ -2026,7 +2268,7 @@ class CaseStage(BaseStage):
         )
 
 
-class RaiseStage(BaseStage):  # pragma: no cov
+class RaiseStage(BaseAsyncStage):
     """Raise error stage executor that raise `StageException` that use a message
     field for making error message before raise.
 
@@ -2064,7 +2306,34 @@ class RaiseStage(BaseStage):  # pragma: no cov
             extras=self.extras,
         )
         message: str = param2template(self.message, params, extras=self.extras)
-        result.trace.info(f"[STAGE]: Raise-Execute: {message!r}.")
+        result.trace.info(f"[STAGE]: Execute Raise-Stage: ( {message} )")
+        raise StageException(message)
+
+    async def axecute(
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
+    ) -> Result:
+        """Async execution method for this Empty stage that only logging out to
+        stdout.
+
+        :param params: (DictData) A context data that want to add output result.
+            But this stage does not pass any output.
+        :param result: (Result) A result object for keeping context and status
+            data.
+        :param event: (Event) An event manager that use to track parent execute
+            was not force stopped.
+
+        :rtype: Result
+        """
+        result: Result = result or Result(
+            run_id=gen_id(self.name + (self.id or ""), unique=True),
+            extras=self.extras,
+        )
+        message: str = param2template(self.message, params, extras=self.extras)
+        await result.trace.ainfo(f"[STAGE]: Execute Raise-Stage: ( {message} )")
         raise StageException(message)
 
 
@@ -2142,7 +2411,7 @@ class DockerStage(BaseStage):  # pragma: no cov
             decode=True,
         )
         for line in resp:
-            result.trace.info(f"... {line}")
+            result.trace.info(f"[STAGE]: ... {line}")
 
         if event and event.is_set():
             error_msg: str = (
@@ -2178,7 +2447,7 @@ class DockerStage(BaseStage):  # pragma: no cov
         )
 
         for line in container.logs(stream=True, timestamps=True):
-            result.trace.info(f"... {line.strip().decode()}")
+            result.trace.info(f"[STAGE]: ... {line.strip().decode()}")
 
         # NOTE: This code copy from the docker package.
         exit_status: int = container.wait()["StatusCode"]
@@ -2221,8 +2490,9 @@ class DockerStage(BaseStage):  # pragma: no cov
             extras=self.extras,
         )
 
-        result.trace.info(f"[STAGE]: Docker-Execute: {self.image}:{self.tag}")
-
+        result.trace.info(
+            f"[STAGE]: Execute Docker-Stage: {self.image}:{self.tag}"
+        )
         raise NotImplementedError("Docker Stage does not implement yet.")
 
 
@@ -2316,7 +2586,7 @@ class VirtualPyStage(PyStage):  # pragma: no cov
             extras=self.extras,
         )
 
-        result.trace.info(f"[STAGE]: Py-Virtual-Execute: {self.name}")
+        result.trace.info(f"[STAGE]: Execute VirtualPy-Stage: {self.name}")
         run: str = param2template(dedent(self.run), params, extras=self.extras)
         with self.create_py_file(
             py=run,
@@ -2324,7 +2594,7 @@ class VirtualPyStage(PyStage):  # pragma: no cov
             deps=param2template(self.deps, params, extras=self.extras),
             run_id=result.run_id,
         ) as py:
-            result.trace.debug(f"... Create `{py}` file.")
+            result.trace.debug(f"[STAGE]: ... Create `{py}` file.")
             rs: CompletedProcess = subprocess.run(
                 ["uv", "run", py, "--no-cache"],
                 # ["uv", "run", "--python", "3.9", py],
@@ -2375,4 +2645,4 @@ Stage = Annotated[
         EmptyStage,
     ],
     Field(union_mode="smart"),
-]
+]  # pragma: no cov