ddeutil-workflow 0.0.64__py3-none-any.whl → 0.0.65__py3-none-any.whl

ddeutil/workflow/job.py

@@ -12,7 +12,7 @@ for execute on target machine instead of the current local machine.
 making matrix values before execution parallelism stage execution.
 
     The Job model does not implement `handler_execute` same as Stage model
-because the job should raise only `JobException` class from the execution
+because the job should raise only `JobError` class from the execution
 method.
 """
 from __future__ import annotations
@@ -39,13 +39,20 @@ from pydantic import BaseModel, Discriminator, Field, SecretStr, Tag
 from pydantic.functional_validators import field_validator, model_validator
 from typing_extensions import Self
 
+from . import JobSkipError
 from .__types import DictData, DictStr, Matrix, StrOrNone
-from .exceptions import (
-    JobException,
-    StageException,
-    to_dict,
+from .errors import JobCancelError, JobError, to_dict
+from .result import (
+    CANCEL,
+    FAILED,
+    SKIP,
+    SUCCESS,
+    WAIT,
+    Result,
+    Status,
+    get_status_from_error,
+    validate_statuses,
 )
-from .result import CANCEL, FAILED, SKIP, SUCCESS, WAIT, Result, Status
 from .reusables import has_template, param2template
 from .stages import Stage
 from .utils import cross_product, filter_func, gen_id
@@ -238,6 +245,7 @@ class SelfHostedArgs(BaseModel):
     """Self-Hosted arguments."""
 
     host: str = Field(description="A host URL of the target self-hosted.")
+    token: SecretStr = Field(description="An API or Access token.")
 
 
 class OnSelfHosted(BaseRunsOn):  # pragma: no cov
@@ -250,6 +258,8 @@ class OnSelfHosted(BaseRunsOn):  # pragma: no cov
 
 
 class AzBatchArgs(BaseModel):
+    """Azure Batch arguments."""
+
     batch_account_name: str
     batch_account_key: SecretStr
     batch_account_url: str
@@ -431,11 +441,10 @@ class Job(BaseModel):
                 return stage
         raise ValueError(f"Stage {stage_id!r} does not exists in this job.")
 
-    def check_needs(
-        self, jobs: dict[str, DictData]
-    ) -> Status:  # pragma: no cov
+    def check_needs(self, jobs: dict[str, DictData]) -> Status:
         """Return trigger status from checking job's need trigger rule logic was
-        valid. The return status should be SUCCESS, FAILED, WAIT, or SKIP.
+        valid. The return status should be `SUCCESS`, `FAILED`, `WAIT`, or
+        `SKIP` status.
 
         :param jobs: (dict[str, DictData]) A mapping of job ID and its context
             data that return from execution process.
@@ -450,43 +459,98 @@ class Job(BaseModel):
         def make_return(result: bool) -> Status:
             return SUCCESS if result else FAILED
 
+        # NOTE: Filter all job result context only needed in this job.
         need_exist: dict[str, Any] = {
-            need: jobs[need] for need in self.needs if need in jobs
+            need: jobs[need] or {"status": SUCCESS}
+            for need in self.needs
+            if need in jobs
         }
-        if len(need_exist) != len(self.needs):
+
+        # NOTE: Return WAIT status if result context not complete, or it has any
+        #   waiting status.
+        if len(need_exist) < len(self.needs) or any(
+            need_exist[job].get("status", SUCCESS) == WAIT for job in need_exist
+        ):
             return WAIT
-        elif all(need_exist[job].get("skipped", False) for job in need_exist):
+
+        # NOTE: Return SKIP status if all status are SKIP.
+        elif all(
+            need_exist[job].get("status", SUCCESS) == SKIP for job in need_exist
+        ):
             return SKIP
+
+        # NOTE: Return CANCEL status if any status is CANCEL.
+        elif any(
+            need_exist[job].get("status", SUCCESS) == CANCEL
+            for job in need_exist
+        ):
+            return CANCEL
+
+        # NOTE: Return SUCCESS if all status not be WAIT or all SKIP.
         elif self.trigger_rule == Rule.ALL_DONE:
             return SUCCESS
+
         elif self.trigger_rule == Rule.ALL_SUCCESS:
             rs = all(
                 (
                     "errors" not in need_exist[job]
-                    and not need_exist[job].get("skipped", False)
+                    and need_exist[job].get("status", SUCCESS) == SUCCESS
                 )
                 for job in need_exist
             )
         elif self.trigger_rule == Rule.ALL_FAILED:
-            rs = all("errors" in need_exist[job] for job in need_exist)
-        elif self.trigger_rule == Rule.ONE_SUCCESS:
-            rs = sum(
+            rs = all(
                 (
-                    "errors" not in need_exist[job]
-                    and not need_exist[job].get("skipped", False)
+                    "errors" in need_exist[job]
+                    or need_exist[job].get("status", SUCCESS) == FAILED
                 )
                 for job in need_exist
-            ) + 1 == len(self.needs)
+            )
+
+        elif self.trigger_rule == Rule.ONE_SUCCESS:
+            rs = (
+                sum(
+                    (
+                        "errors" not in need_exist[job]
+                        and need_exist[job].get("status", SUCCESS) == SUCCESS
+                    )
+                    for job in need_exist
+                )
+                == 1
+            )
+
         elif self.trigger_rule == Rule.ONE_FAILED:
-            rs = sum("errors" in need_exist[job] for job in need_exist) == 1
+            rs = (
+                sum(
+                    (
+                        "errors" in need_exist[job]
+                        or need_exist[job].get("status", SUCCESS) == FAILED
+                    )
+                    for job in need_exist
+                )
+                == 1
+            )
+
         elif self.trigger_rule == Rule.NONE_SKIPPED:
             rs = all(
-                not need_exist[job].get("skipped", False) for job in need_exist
+                need_exist[job].get("status", SUCCESS) != SKIP
+                for job in need_exist
             )
+
         elif self.trigger_rule == Rule.NONE_FAILED:
-            rs = all("errors" not in need_exist[job] for job in need_exist)
+            rs = all(
+                (
+                    "errors" not in need_exist[job]
+                    and need_exist[job].get("status", SUCCESS) != FAILED
+                )
+                for job in need_exist
+            )
+
         else:  # pragma: no cov
-            return FAILED
+            raise NotImplementedError(
+                f"Trigger rule {self.trigger_rule} does not implement on this "
+                f"`check_needs` method yet."
+            )
         return make_return(rs)
 
     def is_skipped(self, params: DictData) -> bool:
@@ -496,9 +560,9 @@ class Job(BaseModel):
         :param params: (DictData) A parameter value that want to pass to condition
             template.
 
-        :raise JobException: When it has any error raise from the eval
+        :raise JobError: When it has any error raise from the eval
             condition statement.
-        :raise JobException: When return type of the eval condition statement
+        :raise JobError: When return type of the eval condition statement
             does not return with boolean type.
 
         :rtype: bool
@@ -519,7 +583,7 @@ class Job(BaseModel):
                 raise TypeError("Return type of condition does not be boolean")
             return not rs
         except Exception as e:
-            raise JobException(f"{e.__class__.__name__}: {e}") from e
+            raise JobError(f"{e.__class__.__name__}: {e}") from e
 
     def set_outputs(
         self,
@@ -561,7 +625,7 @@ class Job(BaseModel):
         extract from the result context if it exists. If it does not found, it
         will not set on the received context.
 
-        :raise JobException: If the job's ID does not set and the setting
+        :raise JobError: If the job's ID does not set and the setting
             default job ID flag does not set.
 
         :param output: (DictData) A result data context that want to extract
@@ -575,34 +639,51 @@ class Job(BaseModel):
             to["jobs"] = {}
 
         if self.id is None and job_id is None:
-            raise JobException(
+            raise JobError(
                 "This job do not set the ID before setting execution output."
             )
 
         _id: str = self.id or job_id
-        output: DictData = output.copy()
+        output: DictData = copy.deepcopy(output)
         errors: DictData = (
-            {"errors": output.pop("errors", {})} if "errors" in output else {}
+            {"errors": output.pop("errors")} if "errors" in output else {}
         )
-        skipping: dict[str, bool] = (
-            {"skipped": output.pop("skipped", False)}
-            if "skipped" in output
-            else {}
+        status: dict[str, Status] = (
+            {"status": output.pop("status")} if "status" in output else {}
         )
-
         if self.strategy.is_set():
-            to["jobs"][_id] = {"strategies": output, **skipping, **errors}
+            to["jobs"][_id] = {"strategies": output} | errors | status
         elif len(k := output.keys()) > 1:  # pragma: no cov
-            raise JobException(
+            raise JobError(
                 "Strategy output from execution return more than one ID while "
                 "this job does not set strategy."
             )
         else:
             _output: DictData = {} if len(k) == 0 else output[list(k)[0]]
             _output.pop("matrix", {})
-            to["jobs"][_id] = {**_output, **skipping, **errors}
+            to["jobs"][_id] = _output | errors | status
         return to
 
+    def get_outputs(
+        self,
+        output: DictData,
+        *,
+        job_id: StrOrNone = None,
+    ) -> DictData:
+        """Get the outputs from jobs data. It will get this job ID or passing
+        custom ID from the job outputs mapping.
+
+        :param output: (DictData) A job outputs data that want to extract
+        :param job_id: (StrOrNone) A job ID if the `id` field does not set.
+
+        :rtype: DictData
+        """
+        _id: str = self.id or job_id
+        if self.strategy.is_set():
+            return output.get("jobs", {}).get(_id, {}).get("strategies", {})
+        else:
+            return output.get("jobs", {}).get(_id, {})
+
     def execute(
         self,
         params: DictData,
@@ -634,10 +715,11 @@ class Job(BaseModel):
         )
 
         result.trace.info(
-            f"[JOB]: Execute "
+            f"[JOB]: Routing for "
             f"{''.join(self.runs_on.type.value.split('_')).title()}: "
             f"{self.id!r}"
         )
+
         if self.runs_on.type == RunsOn.LOCAL:
             return local_execute(
                 self,
@@ -658,13 +740,13 @@ class Job(BaseModel):
             )
 
         result.trace.error(
-            f"[JOB]: Execute not support runs-on: {self.runs_on.type.value!r} "
+            f"[JOB]: Execution not support runs-on: {self.runs_on.type.value!r} "
             f"yet."
         )
         return result.catch(
             status=FAILED,
             context={
-                "errors": JobException(
+                "errors": JobError(
                     f"Execute runs-on type: {self.runs_on.type.value!r} does "
                     f"not support yet."
                 ).to_dict(),
@@ -672,6 +754,19 @@ class Job(BaseModel):
         )
 
 
+def mark_errors(context: DictData, error: JobError) -> None:
+    """Make the errors context result with the refs value depends on the nested
+    execute func.
+
+    :param context: (DictData) A context data.
+    :param error: (JobError) A stage exception object.
+    """
+    if "errors" in context:
+        context["errors"][error.refs] = error.to_dict()
+    else:
+        context["errors"] = error.to_dict(with_refs=True)
+
+
 def local_execute_strategy(
     job: Job,
     strategy: DictData,
@@ -700,9 +795,9 @@ def local_execute_strategy(
     :param event: (Event) An Event manager instance that use to cancel this
         execution if it forces stopped by parent execution.
 
-    :raise JobException: If event was set.
-    :raise JobException: If stage execution raise any error as `StageException`.
-    :raise JobException: If the result from execution has `FAILED` status.
+    :raise JobError: If event was set.
+    :raise JobError: If stage execution raise any error as `StageError`.
+    :raise JobError: If the result from execution has `FAILED` status.
 
     :rtype: Result
     """
@@ -719,81 +814,94 @@ def local_execute_strategy(
 
     context: DictData = copy.deepcopy(params)
     context.update({"matrix": strategy, "stages": {}})
-    for stage in job.stages:
+    total_stage: int = len(job.stages)
+    skips: list[bool] = [False] * total_stage
+    for i, stage in enumerate(job.stages, start=0):
 
         if job.extras:
             stage.extras = job.extras
 
-        if stage.is_skipped(params=context):
-            result.trace.info(f"[JOB]: Skip Stage: {stage.iden!r}")
-            stage.set_outputs(output={"skipped": True}, to=context)
-            continue
-
         if event and event.is_set():
-            error_msg: str = "Job strategy was canceled because event was set."
+            error_msg: str = (
+                "Strategy execution was canceled from the event before "
+                "start stage execution."
+            )
             result.catch(
                 status=CANCEL,
                 context={
                     strategy_id: {
+                        "status": CANCEL,
                         "matrix": strategy,
                         "stages": filter_func(context.pop("stages", {})),
-                        "errors": JobException(error_msg).to_dict(),
+                        "errors": JobCancelError(error_msg).to_dict(),
                     },
                 },
             )
-            raise JobException(error_msg, refs=strategy_id)
+            raise JobCancelError(error_msg, refs=strategy_id)
+
+        result.trace.info(f"[JOB]: Execute Stage: {stage.iden!r}")
+        rs: Result = stage.handler_execute(
+            params=context,
+            run_id=result.run_id,
+            parent_run_id=result.parent_run_id,
+            event=event,
+        )
+        stage.set_outputs(rs.context, to=context)
 
-        try:
-            result.trace.info(f"[JOB]: Execute Stage: {stage.iden!r}")
-            rs: Result = stage.handler_execute(
-                params=context,
-                run_id=result.run_id,
-                parent_run_id=result.parent_run_id,
-                event=event,
+        if rs.status == SKIP:
+            skips[i] = True
+            continue
+
+        if rs.status == FAILED:
+            error_msg: str = (
+                f"Strategy execution was break because its nested-stage, "
+                f"{stage.iden!r}, failed."
             )
-            stage.set_outputs(rs.context, to=context)
-        except StageException as e:
             result.catch(
                 status=FAILED,
                 context={
                     strategy_id: {
+                        "status": FAILED,
                         "matrix": strategy,
                         "stages": filter_func(context.pop("stages", {})),
-                        "errors": e.to_dict(),
+                        "errors": JobError(error_msg).to_dict(),
                     },
                 },
             )
-            raise JobException(
-                message=f"Handler Error: {e.__class__.__name__}: {e}",
-                refs=strategy_id,
-            ) from e
+            raise JobError(error_msg, refs=strategy_id)
 
-        if rs.status == FAILED:
+        elif rs.status == CANCEL:
             error_msg: str = (
-                f"Strategy break because stage, {stage.iden!r}, return "
-                f"`FAILED` status."
+                "Strategy execution was canceled from the event after "
+                "end stage execution."
             )
             result.catch(
-                status=FAILED,
+                status=CANCEL,
                 context={
                     strategy_id: {
+                        "status": CANCEL,
                         "matrix": strategy,
                         "stages": filter_func(context.pop("stages", {})),
-                        "errors": JobException(error_msg).to_dict(),
+                        "errors": JobCancelError(error_msg).to_dict(),
                     },
                 },
             )
-            raise JobException(error_msg, refs=strategy_id)
+            raise JobCancelError(error_msg, refs=strategy_id)
 
-    return result.catch(
-        status=SUCCESS,
+    status: Status = SKIP if sum(skips) == total_stage else SUCCESS
+    result.catch(
+        status=status,
         context={
             strategy_id: {
+                "status": status,
                 "matrix": strategy,
                 "stages": filter_func(context.pop("stages", {})),
             },
         },
     )
+    if status == SKIP:
+        raise JobSkipError("All stage was skipped.")
+    return result
 
 
 def local_execute(
@@ -809,7 +917,7 @@ def local_execute(
     step and run multithread on this metrics to the `stages` field of this job.
 
     Important:
-        This method does not raise any `JobException` because it allows run
+        This method does not raise any `JobError` because it allows run
     parallel mode. If it raises error from strategy execution, it will catch
     that error and store it in the `errors` key with list of error.
 
@@ -835,12 +943,22 @@ def local_execute(
         extras=job.extras,
     )
 
+    result.trace.info("[JOB]: Start Local executor.")
+
+    if job.desc:
+        result.trace.debug(f"[JOB]: Description:||{job.desc}||")
+
+    if job.is_skipped(params=params):
+        result.trace.info("[JOB]: Skip because job condition was valid.")
+        return result.catch(status=SKIP)
+
     event: Event = event or Event()
-    fail_fast_flag: bool = job.strategy.fail_fast
-    ls: str = "Fail-Fast" if fail_fast_flag else "All-Completed"
+    ls: str = "Fail-Fast" if job.strategy.fail_fast else "All-Completed"
     workers: int = job.strategy.max_parallel
+    strategies: list[DictStr] = job.strategy.make()
+    len_strategy: int = len(strategies)
     result.trace.info(
-        f"[JOB]: Execute {ls}: {job.id!r} with {workers} "
+        f"[JOB]: ... Mode {ls}: {job.id!r} with {workers} "
         f"worker{'s' if workers > 1 else ''}."
     )
 
@@ -848,17 +966,14 @@ def local_execute(
         return result.catch(
             status=CANCEL,
             context={
-                "errors": JobException(
-                    "Job was canceled from event that had set before "
+                "errors": JobCancelError(
+                    "Execution was canceled from the event before start "
                     "local job execution."
                 ).to_dict()
             },
         )
 
-    with ThreadPoolExecutor(
-        max_workers=workers, thread_name_prefix="job_strategy_exec_"
-    ) as executor:
-
+    with ThreadPoolExecutor(workers, "jb_stg") as executor:
         futures: list[Future] = [
             executor.submit(
                 local_execute_strategy,
@@ -868,50 +983,58 @@ def local_execute(
                 result=result,
                 event=event,
             )
-            for strategy in job.strategy.make()
+            for strategy in strategies
         ]
 
         context: DictData = {}
-        status: Status = SUCCESS
+        statuses: list[Status] = [WAIT] * len_strategy
+        fail_fast: bool = False
 
-        if not fail_fast_flag:
+        if not job.strategy.fail_fast:
             done: Iterator[Future] = as_completed(futures)
         else:
             done, not_done = wait(futures, return_when=FIRST_EXCEPTION)
             if len(list(done)) != len(futures):
                 result.trace.warning(
-                    "[JOB]: Handler Fail-Fast: Got exception and set event."
+                    "[JOB]: Set the event for stop pending job-execution."
                 )
                 event.set()
                 for future in not_done:
                     future.cancel()
-                time.sleep(0.075)
 
-            nd: str = (
-                (
-                    f", {len(not_done)} strateg"
-                    f"{'ies' if len(not_done) > 1 else 'y'} not run!!!"
+                time.sleep(0.025)
+                nd: str = (
+                    (
+                        f", {len(not_done)} strateg"
+                        f"{'ies' if len(not_done) > 1 else 'y'} not run!!!"
+                    )
+                    if not_done
+                    else ""
                 )
-                if not_done
-                else ""
-            )
-            result.trace.debug(f"[JOB]: ... Job was set Fail-Fast{nd}")
-            done: Iterator[Future] = as_completed(futures)
+                result.trace.debug(f"[JOB]: ... Job was set Fail-Fast{nd}")
+                done: Iterator[Future] = as_completed(futures)
+                fail_fast: bool = True
 
-        for future in done:
+        for i, future in enumerate(done, start=0):
             try:
-                future.result()
-            except JobException as e:
-                status = FAILED
+                statuses[i] = future.result().status
+            except JobError as e:
+                statuses[i] = get_status_from_error(e)
                 result.trace.error(
-                    f"[JOB]: {ls} Error Handler:||{e.__class__.__name__}:||{e}"
+                    f"[JOB]: {ls} Error Handler:||{e.__class__.__name__}: {e}"
                 )
-                if "errors" in context:
-                    context["errors"][e.refs] = e.to_dict()
-                else:
-                    context["errors"] = e.to_dict(with_refs=True)
+                if not isinstance(e, JobSkipError):
+                    mark_errors(context, e)
             except CancelledError:
                 pass
+
+    status: Status = validate_statuses(statuses)
+
+    # NOTE: Prepare status because it does not cancel from parent event but
+    #   cancel from failed item execution.
+    if fail_fast and status == CANCEL:
+        status = FAILED
+
     return result.catch(status=status, context=context)
 
 
@@ -943,12 +1066,14 @@ def self_hosted_execute(
         extras=job.extras,
     )
 
+    result.trace.info("[JOB]: Start self-hosted executor.")
+
     if event and event.is_set():
         return result.catch(
             status=CANCEL,
             context={
-                "errors": JobException(
-                    "Job was canceled from event that had set before start "
+                "errors": JobCancelError(
+                    "Execution was canceled from the event before start "
                     "self-hosted execution."
                 ).to_dict()
             },
@@ -970,8 +1095,8 @@ def self_hosted_execute(
         return result.catch(status=FAILED, context={"errors": to_dict(e)})
 
     if resp.status_code != 200:
-        raise JobException(
-            f"Job execution error from request to self-hosted: "
+        raise JobError(
+            f"Job execution got error response from self-hosted: "
             f"{job.runs_on.args.host!r}"
         )
 
@@ -1018,12 +1143,15 @@ def azure_batch_execute(
         id_logic=(job.id or "EMPTY"),
         extras=job.extras,
     )
+
+    result.trace.info("[JOB]: Start Azure Batch executor.")
+
     if event and event.is_set():
         return result.catch(
             status=CANCEL,
             context={
-                "errors": JobException(
-                    "Job was canceled from event that had set before start "
+                "errors": JobCancelError(
+                    "Execution was canceled from the event before start "
                     "azure-batch execution."
                 ).to_dict()
             },
@@ -1053,13 +1181,16 @@ def docker_execution(
         id_logic=(job.id or "EMPTY"),
         extras=job.extras,
     )
+
+    result.trace.info("[JOB]: Start Docker executor.")
+
     if event and event.is_set():
         return result.catch(
             status=CANCEL,
             context={
-                "errors": JobException(
-                    "Job Docker execution was canceled from event that "
-                    "had set before start execution."
+                "errors": JobCancelError(
+                    "Execution was canceled from the event before start "
+                    "start docker execution."
                 ).to_dict()
             },
         )