ddeutil-workflow 0.0.40__py3-none-any.whl → 0.0.42__py3-none-any.whl

ddeutil/workflow/stages.py

@@ -3,6 +3,7 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
+# [x] Use dynamic config
 """Stage Model that use for getting stage data template from the Job Model.
 The stage handle the minimize task that run in some thread (same thread at
 its job owner) that mean it is the lowest executor of a workflow that can
@@ -41,6 +42,7 @@ from inspect import Parameter
 from pathlib import Path
 from subprocess import CompletedProcess
 from textwrap import dedent
+from threading import Event
 from typing import Annotated, Optional, Union
 
 from pydantic import BaseModel, Field
@@ -48,11 +50,10 @@ from pydantic.functional_validators import model_validator
 from typing_extensions import Self
 
 from .__types import DictData, DictStr, TupleStr
-from .caller import TagFunc, extract_call
-from .conf import config
+from .conf import dynamic
 from .exceptions import StageException, to_dict
 from .result import Result, Status
-from .templates import not_in_template, param2template
+from .reusables import TagFunc, extract_call, not_in_template, param2template
 from .utils import (
     gen_id,
     make_exec,
@@ -66,6 +67,7 @@ __all__: TupleStr = (
     "TriggerStage",
     "ForEachStage",
     "ParallelStage",
+    "RaiseStage",
     "Stage",
 )
 
@@ -93,6 +95,10 @@ class BaseStage(BaseModel, ABC):
         description="A stage condition statement to allow stage executable.",
         alias="if",
     )
+    extras: DictData = Field(
+        default_factory=dict,
+        description="An extra override config values.",
+    )
 
     @property
     def iden(self) -> str:
@@ -126,7 +132,11 @@ class BaseStage(BaseModel, ABC):
 
     @abstractmethod
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        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 stage.
@@ -135,6 +145,8 @@ class BaseStage(BaseModel, ABC):
             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
         """
@@ -147,8 +159,9 @@ class BaseStage(BaseModel, ABC):
         run_id: str | None = None,
         parent_run_id: str | None = None,
         result: Result | None = None,
-        raise_error: bool = False,
+        raise_error: bool | None = None,
         to: DictData | None = None,
+        event: Event | None = None,
     ) -> Result:
         """Handler stage execution result from the stage `execute` method.
 
@@ -183,6 +196,7 @@ class BaseStage(BaseModel, ABC):
         :param raise_error: (bool) A flag that all this method raise error
         :param to: (DictData) A target object for auto set the return output
             after execution.
+        :param event: (Event) An event manager that pass to the stage execution.
 
         :rtype: Result
         """
@@ -194,14 +208,14 @@ class BaseStage(BaseModel, ABC):
         )
 
         try:
-            rs: Result = self.execute(params, result=result)
+            rs: Result = self.execute(params, result=result, event=event)
             if to is not None:
                 return self.set_outputs(rs.context, to=to)
             return rs
         except Exception as err:
             result.trace.error(f"[STAGE]: {err.__class__.__name__}: {err}")
 
-            if raise_error or config.stage_raise_error:
+            if dynamic("stage_raise_error", f=raise_error, extras=self.extras):
                 if isinstance(err, StageException):
                     raise
 
@@ -246,13 +260,17 @@ class BaseStage(BaseModel, ABC):
         if "stages" not in to:
             to["stages"] = {}
 
-        if self.id is None and not config.stage_default_id:
+        if self.id is None and not dynamic(
+            "stage_default_id", extras=self.extras
+        ):
             return to
 
         _id: str = (
-            param2template(self.id, params=to)
+            param2template(self.id, params=to, extras=self.extras)
             if self.id
-            else gen_id(param2template(self.name, params=to))
+            else gen_id(
+                param2template(self.name, params=to, extras=self.extras)
+            )
         )
 
         errors: DictData = (
@@ -290,7 +308,9 @@ class BaseStage(BaseModel, ABC):
             #   should use the `re` module to validate eval-string before
             #   running.
             rs: bool = eval(
-                param2template(self.condition, params), globals() | params, {}
+                param2template(self.condition, params, extras=self.extras),
+                globals() | params,
+                {},
             )
             if not isinstance(rs, bool):
                 raise TypeError("Return type of condition does not be boolean")
@@ -299,7 +319,102 @@ class BaseStage(BaseModel, ABC):
             raise StageException(f"{err.__class__.__name__}: {err}") from err
 
 
-class EmptyStage(BaseStage):
+class BaseAsyncStage(BaseStage):
+
+    @abstractmethod
+    def execute(
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
+    ) -> Result: ...
+
+    @abstractmethod
+    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
+        """
+        raise NotImplementedError(
+            "Async Stage should implement `axecute` method."
+        )
+
+    async def handler_axecute(
+        self,
+        params: DictData,
+        *,
+        run_id: str | None = None,
+        parent_run_id: str | None = None,
+        result: Result | None = None,
+        raise_error: bool | None = None,
+        to: DictData | None = None,
+        event: Event | None = None,
+    ) -> Result:
+        """Async Handler stage execution result from the stage `execute` method.
+
+        :param params: (DictData) A parameterize value data that use in this
+            stage execution.
+        :param run_id: (str) A running stage ID for this execution.
+        :param parent_run_id: (str) A parent workflow running ID for this
+            execution.
+        :param result: (Result) A result object for keeping context and status
+            data before execution.
+        :param raise_error: (bool) A flag that all this method raise error
+        :param to: (DictData) A target object for auto set the return output
+            after execution.
+        :param event: (Event) An event manager that pass to the stage execution.
+
+        :rtype: Result
+        """
+        result: Result = Result.construct_with_rs_or_id(
+            result,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            id_logic=self.iden,
+        )
+
+        try:
+            rs: Result = await self.axecute(params, result=result, event=event)
+            if to is not None:
+                return self.set_outputs(rs.context, to=to)
+            return rs
+        except Exception as err:
+            await result.trace.aerror(
+                f"[STAGE]: {err.__class__.__name__}: {err}"
+            )
+
+            if dynamic("stage_raise_error", f=raise_error, extras=self.extras):
+                if isinstance(err, StageException):
+                    raise
+
+                raise StageException(
+                    f"{self.__class__.__name__}: \n\t"
+                    f"{err.__class__.__name__}: {err}"
+                ) from None
+
+            errors: DictData = {"errors": to_dict(err)}
+            if to is not None:
+                return self.set_outputs(errors, to=to)
+
+            return result.catch(status=Status.FAILED, context=errors)
+
+
+class EmptyStage(BaseAsyncStage):
     """Empty stage that do nothing (context equal empty stage) and logging the
     name of stage only to stdout.
 
@@ -322,7 +437,11 @@ class EmptyStage(BaseStage):
     )
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result:
         """Execution method for the Empty stage that do only logging out to
         stdout. This method does not use the `handler_result` decorator because
@@ -335,6 +454,8 @@ class EmptyStage(BaseStage):
             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
         """
@@ -344,7 +465,7 @@ class EmptyStage(BaseStage):
 
         result.trace.info(
             f"[STAGE]: Empty-Execute: {self.name!r}: "
-            f"( {param2template(self.echo, params=params) or '...'} )"
+            f"( {param2template(self.echo, params, extras=self.extras) or '...'} )"
         )
         if self.sleep > 0:
             if self.sleep > 5:
@@ -353,21 +474,42 @@ class EmptyStage(BaseStage):
 
         return result.catch(status=Status.SUCCESS)
 
-    # TODO: Draft async execute method for the perf improvement.
-    async def aexecute(
-        self, params: DictData, *, result: Result | None = None
-    ) -> Result:  # pragma: no cov
+    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
+        """
         if result is None:  # pragma: no cov
             result: Result = Result(
                 run_id=gen_id(self.name + (self.id or ""), unique=True)
             )
 
-        result.trace.info(
+        await result.trace.ainfo(
             f"[STAGE]: Empty-Execute: {self.name!r}: "
-            f"( {param2template(self.echo, params=params) or '...'} )"
+            f"( {param2template(self.echo, params, extras=self.extras) or '...'} )"
         )
 
-        await asyncio.sleep(1)
+        if self.sleep > 0:
+            if self.sleep > 5:
+                await result.trace.ainfo(
+                    f"[STAGE]: ... sleep ({self.sleep} seconds)"
+                )
+            await asyncio.sleep(self.sleep)
+
         return result.catch(status=Status.SUCCESS)
 
 
@@ -438,7 +580,11 @@ class BashStage(BaseStage):
         Path(f"./{f_name}").unlink()
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result:
         """Execute the Bash statement with the Python build-in ``subprocess``
         package.
@@ -446,6 +592,8 @@ class BashStage(BaseStage):
         :param params: 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
         """
@@ -454,12 +602,14 @@ class BashStage(BaseStage):
                 run_id=gen_id(self.name + (self.id or ""), unique=True)
             )
 
-        bash: str = param2template(dedent(self.bash), params)
+        bash: str = param2template(
+            dedent(self.bash), params, extras=self.extras
+        )
 
         result.trace.info(f"[STAGE]: Shell-Execute: {self.name}")
         with self.create_sh_file(
             bash=bash,
-            env=param2template(self.env, params),
+            env=param2template(self.env, params, extras=self.extras),
             run_id=result.run_id,
         ) as sh:
             result.trace.debug(f"... Start create `{sh[1]}` file.")
@@ -555,7 +705,11 @@ class PyStage(BaseStage):
         return to
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result:
         """Execute the Python statement that pass all globals and input params
         to globals argument on ``exec`` build-in function.
@@ -563,6 +717,8 @@ class PyStage(BaseStage):
         :param params: A parameter that want to pass before run any statement.
         :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
         """
@@ -575,7 +731,7 @@ class PyStage(BaseStage):
         gb: DictData = (
             globals()
             | params
-            | param2template(self.vars, params)
+            | param2template(self.vars, params, extras=self.extras)
             | {"result": result}
         )
 
@@ -588,7 +744,9 @@ class PyStage(BaseStage):
 
         # 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), gb, lc)
+        exec(
+            param2template(dedent(self.run), params, extras=self.extras), gb, lc
+        )
 
         return result.catch(
             status=Status.SUCCESS, context={"locals": lc, "globals": gb}
@@ -629,7 +787,11 @@ class CallStage(BaseStage):
     )
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result:
         """Execute the Call function that already in the call registry.
 
@@ -638,11 +800,12 @@ class CallStage(BaseStage):
         :raise TypeError: When the return type of call function does not be
             dict type.
 
-        :param params: A parameter that want to pass before run any statement.
-        :type params: DictData
+        :param params: (DictData) A parameter that want to pass before run any
+            statement.
         :param result: (Result) A result object for keeping context and status
             data.
-        :type: str | None
+        :param event: (Event) An event manager that use to track parent execute
+            was not force stopped.
 
         :rtype: Result
         """
@@ -651,11 +814,16 @@ class CallStage(BaseStage):
                 run_id=gen_id(self.name + (self.id or ""), unique=True)
             )
 
-        t_func: TagFunc = extract_call(param2template(self.uses, params))()
+        t_func: TagFunc = extract_call(
+            param2template(self.uses, params, extras=self.extras),
+            registries=self.extras.get("regis_call"),
+        )()
 
         # VALIDATE: check input task caller parameters that exists before
         #   calling.
-        args: DictData = {"result": result} | param2template(self.args, params)
+        args: DictData = {"result": result} | param2template(
+            self.args, params, extras=self.extras
+        )
         ips = inspect.signature(t_func)
         necessary_params: list[str] = [
             k
@@ -689,10 +857,12 @@ class CallStage(BaseStage):
         if inspect.iscoroutinefunction(t_func):  # pragma: no cov
             loop = asyncio.get_event_loop()
             rs: DictData = loop.run_until_complete(
-                t_func(**param2template(args, params))
+                t_func(**param2template(args, params, extras=self.extras))
             )
         else:
-            rs: DictData = t_func(**param2template(args, params))
+            rs: DictData = t_func(
+                **param2template(args, params, extras=self.extras)
+            )
 
         # VALIDATE:
         #   Check the result type from call function, it should be dict.
@@ -728,7 +898,11 @@ class TriggerStage(BaseStage):
     )
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result:
         """Trigger another workflow execution. It will wait the trigger
         workflow running complete before catching its result.
@@ -736,6 +910,8 @@ class TriggerStage(BaseStage):
         :param params: 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
         """
@@ -748,15 +924,16 @@ class TriggerStage(BaseStage):
             )
 
         # NOTE: Loading workflow object from trigger name.
-        _trigger: str = param2template(self.trigger, params=params)
+        _trigger: str = param2template(self.trigger, params, extras=self.extras)
 
         # NOTE: Set running workflow ID from running stage ID to external
         #   params on Loader object.
-        workflow: Workflow = Workflow.from_loader(name=_trigger)
+        workflow: Workflow = Workflow.from_conf(_trigger, extras=self.extras)
         result.trace.info(f"[STAGE]: Trigger-Execute: {_trigger!r}")
         return workflow.execute(
-            params=param2template(self.params, params),
+            params=param2template(self.params, params, extras=self.extras),
             result=result,
+            event=event,
         )
 
 
@@ -838,7 +1015,11 @@ class ParallelStage(BaseStage):  # pragma: no cov
         return context
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result:
         """Execute the stages that parallel each branch via multi-threading mode
         or async mode by changing `async_mode` flag.
@@ -846,6 +1027,8 @@ class ParallelStage(BaseStage):  # pragma: no cov
         :param params: A parameter that want to pass before run any statement.
         :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
         """
@@ -854,6 +1037,9 @@ class ParallelStage(BaseStage):  # pragma: no cov
                 run_id=gen_id(self.name + (self.id or ""), unique=True)
             )
 
+        result.trace.info(
+            f"[STAGE]: Parallel-Execute with {self.max_parallel_core} cores."
+        )
         rs: DictData = {"parallel": {}}
         status = Status.SUCCESS
         with ThreadPoolExecutor(
@@ -904,25 +1090,40 @@ class ForEachStage(BaseStage):
         ... }
     """
 
-    foreach: Union[list[str], list[int]] = Field(
+    foreach: Union[list[str], list[int], str] = Field(
         description=(
             "A items for passing to each stages via ${{ item }} template."
         ),
     )
     stages: list[Stage] = Field(
+        default_factory=list,
         description=(
             "A list of stage that will run with each item in the foreach field."
         ),
     )
+    concurrent: int = Field(
+        default=1,
+        gt=0,
+        description=(
+            "A concurrent value allow to run each item at the same time. It "
+            "will be sequential mode if this value equal 1."
+        ),
+    )
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result:
         """Execute the stages that pass each item form the foreach field.
 
         :param params: A parameter that want to pass before run any statement.
         :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
         """
@@ -931,9 +1132,21 @@ class ForEachStage(BaseStage):
                 run_id=gen_id(self.name + (self.id or ""), unique=True)
             )
 
-        rs: DictData = {"items": self.foreach, "foreach": {}}
+        foreach: Union[list[str], list[int]] = (
+            param2template(self.foreach, params, extras=self.extras)
+            if isinstance(self.foreach, str)
+            else self.foreach
+        )
+        if not isinstance(foreach, list):
+            raise StageException(
+                f"Foreach does not support foreach value: {foreach!r}"
+            )
+
+        result.trace.info(f"[STAGE]: Foreach-Execute: {foreach!r}.")
+        rs: DictData = {"items": foreach, "foreach": {}}
         status = Status.SUCCESS
-        for item in self.foreach:
+        # TODO: Implement concurrent more than 1.
+        for item in foreach:
             result.trace.debug(f"[STAGE]: Execute foreach item: {item!r}")
             params["item"] = item
             context = {"stages": {}}
@@ -970,8 +1183,55 @@ class ForEachStage(BaseStage):
 
 
 # TODO: Not implement this stages yet
-class IfStage(BaseStage):  # pragma: no cov
-    """If execution stage.
+class UntilStage(BaseStage):  # pragma: no cov
+    """Until execution stage.
+
+    Data Validate:
+        >>> stage = {
+        ...     "name": "Until stage execution",
+        ...     "item": 1,
+        ...     "until": "${{ item }} > 3"
+        ...     "stages": [
+        ...         {
+        ...             "name": "Start increase item value.",
+        ...             "run": "item = ${{ item }}\\nitem += 1\\n"
+        ...         },
+        ...     ],
+        ... }
+    """
+
+    item: Union[str, int, bool] = Field(description="An initial value.")
+    until: str = Field(description="A until condition.")
+    stages: list[Stage] = Field(
+        default_factory=list,
+        description=(
+            "A list of stage that will run with each item until condition "
+            "correct."
+        ),
+    )
+    max_until_not_change: int = Field(
+        default=3,
+        description="The maximum value of loop if condition not change.",
+    )
+
+    def execute(
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
+    ) -> Result: ...
+
+
+# TODO: Not implement this stages yet
+class Match(BaseModel):
+    case: Union[str, int]
+    stage: Stage
+
+
+# TODO: Not implement this stages yet
+class CaseStage(BaseStage):  # pragma: no cov
+    """Case execution stage.
 
     Data Validate:
         >>> stage = {
@@ -1005,47 +1265,150 @@ class IfStage(BaseStage):  # pragma: no cov
     """
 
     case: str = Field(description="A case condition for routing.")
-    match: list[dict[str, Union[str, Stage]]]
+    match: list[Match]
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
-    ) -> Result: ...
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
+    ) -> Result:
+        """Execute case-match condition that pass to the case field.
+
+        :param params: A parameter that want to pass before run any statement.
+        :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
+        """
+        if result is None:  # pragma: no cov
+            result: Result = Result(
+                run_id=gen_id(self.name + (self.id or ""), unique=True)
+            )
+        status = Status.SUCCESS
+        _case = param2template(self.case, params, extras=self.extras)
+        _else = None
+        context = {}
+        for match in self.match:
+            if (c := match.case) != "_":
+                _condition = param2template(c, params, extras=self.extras)
+            else:
+                _else = match
+                continue
+
+            if match == _condition:
+                stage: Stage = match.stage
+                try:
+                    stage.set_outputs(
+                        stage.handler_execute(
+                            params=params,
+                            run_id=result.run_id,
+                            parent_run_id=result.parent_run_id,
+                        ).context,
+                        to=context,
+                    )
+                except StageException as err:  # pragma: no cov
+                    status = Status.FAILED
+                    result.trace.error(
+                        f"[STAGE]: Catch:\n\t{err.__class__.__name__}:"
+                        f"\n\t{err}"
+                    )
+                    context.update(
+                        {
+                            "errors": {
+                                "class": err,
+                                "name": err.__class__.__name__,
+                                "message": f"{err.__class__.__name__}: {err}",
+                            },
+                        },
+                    )
+
+        return result.catch(status=status, context=context)
 
 
 class RaiseStage(BaseStage):  # pragma: no cov
+    """Raise error stage that raise StageException that use a message field for
+    making error message before raise.
+
+    Data Validate:
+        >>> stage = {
+        ...     "name": "Raise stage",
+        ...     "raise": "raise this stage",
+        ... }
+
+    """
+
     message: str = Field(
         description="An error message that want to raise",
         alias="raise",
     )
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result:
+        """Raise the stage."""
+        if result is None:  # pragma: no cov
+            result: Result = Result(
+                run_id=gen_id(self.name + (self.id or ""), unique=True)
+            )
+        result.trace.info(f"[STAGE]: Raise-Execute: {self.message!r}.")
         raise StageException(self.message)
 
 
 # TODO: Not implement this stages yet
 class HookStage(BaseStage):  # pragma: no cov
+    """Hook stage execution."""
+
     hook: str
     args: DictData
     callback: str
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result: ...
 
 
 # TODO: Not implement this stages yet
 class DockerStage(BaseStage):  # pragma: no cov
-    """Docker container stage execution."""
+    """Docker container stage execution.
+
+    Data Validate:
+        >>> stage = {
+        ...     "name": "Docker stage execution",
+        ...     "image": "image-name.pkg.com",
+        ...     "env": {
+        ...         "ENV": "dev",
+        ...     },
+        ...     "volume": {
+        ...         "secrets": "/secrets",
+        ...     },
+        ... }
+    """
 
-    image: str
+    image: str = Field(
+        description="A Docker image url with tag that want to run.",
+    )
     env: DictData = Field(default_factory=dict)
     volume: DictData = Field(default_factory=dict)
     auth: DictData = Field(default_factory=dict)
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result: ...
 
 
@@ -1059,19 +1422,15 @@ class VirtualPyStage(PyStage):  # pragma: no cov
     def create_py_file(self, py: str, run_id: str | None): ...
 
     def execute(
-        self, params: DictData, *, result: Result | None = None
+        self,
+        params: DictData,
+        *,
+        result: Result | None = None,
+        event: Event | None = None,
     ) -> Result:
         return super().execute(params, result=result)
 
 
-# TODO: Not implement this stages yet
-class SensorStage(BaseStage):  # pragma: no cov
-
-    def execute(
-        self, params: DictData, *, result: Result | None = None
-    ) -> Result: ...
-
-
 # NOTE:
 #   An order of parsing stage model on the Job model with ``stages`` field.
 #   From the current build-in stages, they do not have stage that have the same
@@ -1079,7 +1438,6 @@ class SensorStage(BaseStage):  # pragma: no cov
 #
 Stage = Annotated[
     Union[
-        EmptyStage,
         BashStage,
         CallStage,
         TriggerStage,
@@ -1087,6 +1445,7 @@ Stage = Annotated[
         ParallelStage,
         PyStage,
         RaiseStage,
+        EmptyStage,
     ],
     Field(union_mode="smart"),
 ]