ddeutil-workflow 0.0.14__py3-none-any.whl → 0.0.16__py3-none-any.whl

ddeutil/workflow/stage.py

@@ -3,8 +3,8 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-"""Stage Model that use for getting stage data template from Job Model.
-The stage that handle the minimize task that run in some thread (same thread at
+"""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 workflow that
 can tracking logs.
 
@@ -12,11 +12,13 @@ can tracking logs.
 handle stage error on this stage model. I think stage model should have a lot of
 usecase and it does not worry when I want to create a new one.
 
-    Execution   --> Ok    --> Result with 0
-                --> Error --> Raise StageException
+    Execution   --> Ok      --> Result with 0
+                --> Error   --> Raise StageException
+                            --> Result with 1 (if env var was set)
 
-    On the context I/O that pass to stage object at execute process. The execute
-method receive `{"params": {...}}` for mapping to template.
+    On the context I/O that pass to a stage object at execute process. The
+execute method receives a `params={"params": {...}}` value for mapping to
+template searching.
 """
 from __future__ import annotations
 
@@ -24,6 +26,7 @@ import contextlib
 import inspect
 import subprocess
 import sys
+import time
 import uuid
 from abc import ABC, abstractmethod
 from collections.abc import Iterator
@@ -60,6 +63,8 @@ from .utils import (
 )
 
 P = ParamSpec("P")
+ReturnResult = Callable[P, Result]
+DecoratorResult = Callable[[ReturnResult], ReturnResult]
 logger = get_logger("ddeutil.workflow")
 
 
@@ -77,7 +82,7 @@ __all__: TupleStr = (
 )
 
 
-def handler_result(message: str | None = None) -> Callable[P, Result]:
+def handler_result(message: str | None = None) -> DecoratorResult:
     """Decorator function for handler result from the stage execution. This
     function should to use with execution method only.
 
@@ -85,25 +90,33 @@ def handler_result(message: str | None = None) -> Callable[P, Result]:
     you force catching an output result with error message by specific
     environment variable,`WORKFLOW_CORE_STAGE_RAISE_ERROR`.
 
-        Execution   --> Ok      --> Result with 0
+        Execution   --> Ok      --> Result
+                                        status: 0
+                                        context:
+                                            outputs: ...
                     --> Error   --> Raise StageException
-                                --> Result with 1 (if env var was set)
+                                --> Result (if env var was set)
+                                        status: 1
+                                        context:
+                                            error: ...
+                                            error_message: ...
 
         On the last step, it will set the running ID on a return result object
     from current stage ID before release the final result.
 
     :param message: A message that want to add at prefix of exception statement.
+    :type message: str | None (Default=None)
     :rtype: Callable[P, Result]
     """
     # NOTE: The prefix message string that want to add on the first exception
     #   message dialog.
     #
-    #       ... ValueError: {message}
+    #       >>> ValueError: {message}
     #       ...     raise value error from the stage execution process.
     #
     message: str = message or ""
 
-    def decorator(func: Callable[P, Result]) -> Callable[P, Result]:
+    def decorator(func: ReturnResult) -> ReturnResult:
 
         @wraps(func)
         def wrapped(self: Stage, *args, **kwargs):
@@ -172,7 +185,7 @@ class BaseStage(BaseModel, ABC):
     )
 
     @model_validator(mode="after")
-    def __prepare_running_id(self) -> Self:
+    def __prepare_running_id__(self) -> Self:
         """Prepare stage running ID that use default value of field and this
         method will validate name and id fields should not contain any template
         parameter (exclude matrix template).
@@ -232,7 +245,7 @@ class BaseStage(BaseModel, ABC):
         :param to: A context data that want to add output result.
         :rtype: DictData
         """
-        if not (self.id or config.stage_default_id):
+        if self.id is None and not config.stage_default_id:
             logger.debug(
                 f"({self.run_id}) [STAGE]: Output does not set because this "
                 f"stage does not set ID or default stage ID config flag not be "
@@ -252,7 +265,7 @@ class BaseStage(BaseModel, ABC):
         )
 
         # NOTE: Set the output to that stage generated ID with ``outputs`` key.
-        logger.debug(f"({self.run_id}) [STAGE]: Set outputs on: {_id}")
+        logger.debug(f"({self.run_id}) [STAGE]: Set outputs to {_id!r}")
         to["stages"][_id] = {"outputs": output}
         return to
 
@@ -293,6 +306,11 @@ class EmptyStage(BaseStage):
         default=None,
         description="A string statement that want to logging",
     )
+    sleep: float = Field(
+        default=0,
+        description="A second value to sleep before finish execution",
+        ge=0,
+    )
 
     def execute(self, params: DictData) -> Result:
         """Execution method for the Empty stage that do only logging out to
@@ -310,6 +328,8 @@ class EmptyStage(BaseStage):
             f"({self.run_id}) [STAGE]: Empty-Execute: {self.name!r}: "
             f"( {param2template(self.echo, params=params) or '...'} )"
         )
+        if self.sleep > 0:
+            time.sleep(self.sleep)
         return Result(status=0, context={})
 
 
@@ -342,7 +362,7 @@ class BashStage(BaseStage):
     )
 
     @contextlib.contextmanager
-    def __prepare_bash(self, bash: str, env: DictStr) -> Iterator[TupleStr]:
+    def prepare_bash(self, bash: str, env: DictStr) -> 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.
@@ -385,15 +405,12 @@ class BashStage(BaseStage):
         :rtype: Result
         """
         bash: str = param2template(dedent(self.bash), params)
-        with self.__prepare_bash(
+        with self.prepare_bash(
             bash=bash, env=param2template(self.env, params)
         ) as sh:
             logger.info(f"({self.run_id}) [STAGE]: Shell-Execute: {sh}")
             rs: CompletedProcess = subprocess.run(
-                sh,
-                shell=False,
-                capture_output=True,
-                text=True,
+                sh, shell=False, capture_output=True, text=True
             )
         if rs.returncode > 0:
             # NOTE: Prepare stderr message that returning from subprocess.
@@ -410,8 +427,8 @@ class BashStage(BaseStage):
             status=0,
             context={
                 "return_code": rs.returncode,
-                "stdout": rs.stdout.rstrip("\n"),
-                "stderr": rs.stderr.rstrip("\n"),
+                "stdout": rs.stdout.rstrip("\n") or None,
+                "stderr": rs.stderr.rstrip("\n") or None,
             },
         )
 
@@ -545,14 +562,14 @@ class HookStage(BaseStage):
         >>> stage = {
         ...     "name": "Task stage execution",
         ...     "uses": "tasks/function-name@tag-name",
-        ...     "args": {
-        ...         "FOO": "BAR",
-        ...     },
+        ...     "args": {"FOO": "BAR"},
         ... }
     """
 
     uses: str = Field(
-        description="A pointer that want to load function from registry.",
+        description=(
+            "A pointer that want to load function from the hook registry."
+        ),
     )
     args: DictData = Field(
         default_factory=dict,
@@ -613,10 +630,7 @@ class TriggerStage(BaseStage):
         >>> stage = {
         ...     "name": "Trigger workflow stage execution",
         ...     "trigger": 'workflow-name-for-loader',
-        ...     "params": {
-        ...         "run-date": "2024-08-01",
-        ...         "source": "src",
-        ...     },
+        ...     "params": {"run-date": "2024-08-01", "source": "src"},
         ... }
     """