ddeutil-workflow 0.0.73__py3-none-any.whl → 0.0.75__py3-none-any.whl

ddeutil/workflow/params.py

@@ -3,13 +3,43 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-"""This module include all Param Pydantic Models that use for parsing an
-incoming parameters that was passed to the Workflow and Schedule objects before
-execution or release methods.
-
-    The Param model allow you to handle validation and preparation steps before
-passing an input value to target execution method.
+"""Parameter Models for Workflow Validation and Processing.
+
+This module provides comprehensive parameter models for handling validation and
+preparation of input values passed to workflows and scheduled executions. The
+parameter system ensures type safety and provides default value management.
+
+The parameter models support various data types including strings, numbers,
+dates, choices, and complex types like maps and arrays. Each parameter type
+provides validation and transformation capabilities.
+
+Classes:
+    BaseParam: Abstract base class for all parameter types
+    DefaultParam: Base class for parameters with default values
+    DateParam: Date parameter with validation
+    DatetimeParam: Datetime parameter with validation
+    StrParam: String parameter type
+    IntParam: Integer parameter type
+    FloatParam: Float parameter with precision control
+    DecimalParam: Decimal parameter for financial calculations
+    ChoiceParam: Parameter with predefined choices
+    MapParam: Dictionary/mapping parameter type
+    ArrayParam: List/array parameter type
+
+Example:
+    ```python
+    from ddeutil.workflow.params import StrParam, IntParam
+
+    # Define parameters
+    name_param = StrParam(desc="Username", required=True)
+    age_param = IntParam(desc="User age", default=18, required=False)
+
+    # Process values
+    name = name_param.receive("John")
+    age = age_param.receive(None)  # Uses default value
+    ```
 """
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
@@ -22,7 +52,7 @@ from pydantic import BaseModel, Field
 
 from .__types import StrOrInt
 from .errors import ParamError
-from .utils import get_d_now, get_dt_now
+from .utils import UTC, get_d_now, get_dt_now
 
 T = TypeVar("T")
 
@@ -52,7 +82,7 @@ class BaseParam(BaseModel, ABC):
         )
 
 
-class DefaultParam(BaseParam):
+class DefaultParam(BaseParam, ABC):
     """Default Parameter that will check default if it required. This model do
     not implement the `receive` method.
     """
@@ -139,16 +169,18 @@ class DatetimeParam(DefaultParam):
             return self.default
 
         if isinstance(value, datetime):
-            return value
+            if value.tzinfo is None:
+                return value.replace(tzinfo=UTC)
+            return value.astimezone(UTC)
         elif isinstance(value, date):
-            return datetime(value.year, value.month, value.day)
+            return datetime(value.year, value.month, value.day, tzinfo=UTC)
         elif not isinstance(value, str):
             raise ParamError(
                 f"Value that want to convert to datetime does not support for "
                 f"type: {type(value)}"
             )
         try:
-            return datetime.fromisoformat(value)
+            return datetime.fromisoformat(value).replace(tzinfo=UTC)
         except ValueError:
             raise ParamError(
                 f"Invalid the ISO format string for datetime: {value!r}"

ddeutil/workflow/result.py

@@ -3,9 +3,20 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-"""A Result module. It is the data context transfer objects that use by all
-object in this package. This module provide Status enum object and Result
-dataclass.
+"""Result and Status Management Module.
+
+This module provides the core result and status management functionality for
+workflow execution tracking. It includes the Status enumeration for execution
+states and the Result dataclass for context transfer between workflow components.
+
+Classes:
+    Status: Enumeration for execution status tracking
+    Result: Dataclass for execution context and result management
+
+Functions:
+    validate_statuses: Determine final status from multiple status values
+    get_status_from_error: Convert exception types to appropriate status
+    get_dt_tznow: Get current datetime with timezone configuration
 """
 from __future__ import annotations
 
@@ -13,7 +24,6 @@ from dataclasses import field
 from datetime import datetime
 from enum import Enum
 from typing import Optional, Union
-from zoneinfo import ZoneInfo
 
 from pydantic import ConfigDict
 from pydantic.dataclasses import dataclass
@@ -31,23 +41,24 @@ from . import (
     WorkflowError,
 )
 from .__types import DictData
-from .audits import TraceModel, get_trace
-from .conf import dynamic
+from .audits import Trace, get_trace
 from .errors import ResultError
-from .utils import default_gen_id, gen_id, get_dt_now
-
-
-def get_dt_tznow(tz: Optional[ZoneInfo] = None) -> datetime:  # pragma: no cov
-    """Return the current datetime object that passing the config timezone.
-
-    :rtype: datetime
-    """
-    return get_dt_now(tz=dynamic("tz", f=tz))
+from .utils import default_gen_id, get_dt_now
 
 
 class Status(str, Enum):
-    """Status Int Enum object that use for tracking execution status to the
-    Result dataclass object.
+    """Execution status enumeration for workflow components.
+
+    Status enum provides standardized status values for tracking the execution
+    state of workflows, jobs, and stages. Each status includes an emoji
+    representation for visual feedback.
+
+    Attributes:
+        SUCCESS: Successful execution completion
+        FAILED: Execution failed with errors
+        WAIT: Waiting for execution or dependencies
+        SKIP: Execution was skipped due to conditions
+        CANCEL: Execution was cancelled
     """
 
     SUCCESS = "SUCCESS"
@@ -58,9 +69,10 @@ class Status(str, Enum):
 
     @property
     def emoji(self) -> str:  # pragma: no cov
-        """Return the emoji value of this status.
+        """Get emoji representation of the status.
 
-        :rtype: str
+        Returns:
+            str: Unicode emoji character representing the status
         """
         return {
             "SUCCESS": "✅",
@@ -90,12 +102,28 @@ ResultStatuses: list[Status] = [SUCCESS, FAILED, CANCEL, SKIP]
 
 
 def validate_statuses(statuses: list[Status]) -> Status:
-    """Validate the final status from list of Status object.
+    """Determine final status from multiple status values.
 
-    :param statuses: (list[Status]) A list of status that want to validate the
-        final status.
+    Applies workflow logic to determine the overall status based on a collection
+    of individual status values. Follows priority order: CANCEL > FAILED > WAIT >
+    individual status consistency.
 
-    :rtype: Status
+    Args:
+        statuses: List of status values to evaluate
+
+    Returns:
+        Status: Final consolidated status based on workflow logic
+
+    Example:
+        ```python
+        # Mixed statuses - FAILED takes priority
+        result = validate_statuses([SUCCESS, FAILED, SUCCESS])
+        # Returns: FAILED
+
+        # All same status
+        result = validate_statuses([SUCCESS, SUCCESS, SUCCESS])
+        # Returns: SUCCESS
+        ```
     """
     if any(s == CANCEL for s in statuses):
         return CANCEL
@@ -123,7 +151,11 @@ def get_status_from_error(
         BaseException,
     ]
 ) -> Status:
-    """Get the Status from the error object."""
+    """Get the Status from the error object.
+
+    Returns:
+        Status: The status from the specific exception class.
+    """
     if isinstance(error, (StageSkipError, JobSkipError)):
         return SKIP
     elif isinstance(
@@ -155,49 +187,13 @@ class Result:
 
     status: Status = field(default=WAIT)
     context: DictData = field(default_factory=default_context)
+    info: DictData = field(default_factory=dict)
     run_id: Optional[str] = field(default_factory=default_gen_id)
     parent_run_id: Optional[str] = field(default=None, compare=False)
-    ts: datetime = field(default_factory=get_dt_tznow, compare=False)
-
-    trace: Optional[TraceModel] = field(default=None, compare=False, repr=False)
+    ts: datetime = field(default_factory=get_dt_now, compare=False)
+    trace: Optional[Trace] = field(default=None, compare=False, repr=False)
     extras: DictData = field(default_factory=dict, compare=False, repr=False)
 
-    @classmethod
-    def construct_with_rs_or_id(
-        cls,
-        result: Optional[Result] = None,
-        run_id: Optional[str] = None,
-        parent_run_id: Optional[str] = None,
-        id_logic: Optional[str] = None,
-        *,
-        extras: DictData | None = None,
-    ) -> Self:
-        """Create the Result object or set parent running id if passing Result
-        object.
-
-        :param result: A Result instance.
-        :param run_id: A running ID.
-        :param parent_run_id: A parent running ID.
-        :param id_logic: A logic function that use to generate a running ID.
-        :param extras: An extra parameter that want to override the core config.
-
-        :rtype: Self
-        """
-        if result is None:
-            return cls(
-                run_id=(run_id or gen_id(id_logic or "", unique=True)),
-                parent_run_id=parent_run_id,
-                ts=get_dt_now(dynamic("tz", extras=extras)),
-                extras=(extras or {}),
-            )
-        elif parent_run_id:
-            result.set_parent_run_id(parent_run_id)
-
-        if extras is not None:
-            result.extras.update(extras)
-
-        return result
-
     @model_validator(mode="after")
     def __prepare_trace(self) -> Self:
         """Prepare trace field that want to pass after its initialize step.
@@ -205,7 +201,7 @@ class Result:
         :rtype: Self
         """
         if self.trace is None:  # pragma: no cov
-            self.trace: TraceModel = get_trace(
+            self.trace: Trace = get_trace(
                 self.run_id,
                 parent_run_id=self.parent_run_id,
                 extras=self.extras,
@@ -220,7 +216,7 @@ class Result:
         :rtype: Self
         """
         self.parent_run_id: str = running_id
-        self.trace: TraceModel = get_trace(
+        self.trace: Trace = get_trace(
             self.run_id, parent_run_id=running_id, extras=self.extras
         )
         return self
@@ -240,29 +236,59 @@ class Result:
 
         :rtype: Self
         """
+        self.__dict__["context"].update(context or {})
         self.__dict__["status"] = (
             Status(status) if isinstance(status, int) else status
         )
-        self.__dict__["context"].update(context or {})
         self.__dict__["context"]["status"] = self.status
+
+        # NOTE: Update other context data.
         if kwargs:
             for k in kwargs:
                 if k in self.__dict__["context"]:
                     self.__dict__["context"][k].update(kwargs[k])
                 # NOTE: Exclude the `info` key for update information data.
                 elif k == "info":
-                    self.__dict__["context"][k].update(kwargs[k])
+                    self.__dict__["info"].update(kwargs["info"])
                 else:
                     raise ResultError(
                         f"The key {k!r} does not exists on context data."
                     )
         return self
 
+    def make_info(self, data: DictData) -> Self:
+        """Making information."""
+        self.__dict__["info"].update(data)
+        return self
+
     def alive_time(self) -> float:  # pragma: no cov
         """Return total seconds that this object use since it was created.
 
         :rtype: float
         """
-        return (
-            get_dt_now(tz=dynamic("tz", extras=self.extras)) - self.ts
-        ).total_seconds()
+        return (get_dt_now() - self.ts).total_seconds()
+
+
+def catch(
+    context: DictData,
+    status: Union[int, Status],
+    updated: DictData | None = None,
+    **kwargs,
+) -> DictData:
+    """Catch updated context to the current context."""
+    context.update(updated or {})
+    context["status"] = Status(status) if isinstance(status, int) else status
+
+    if not kwargs:
+        return context
+
+    # NOTE: Update other context data.
+    for k in kwargs:
+        if k in context:
+            context[k].update(kwargs[k])
+        # NOTE: Exclude the `info` key for update information data.
+        elif k == "info":
+            context["info"].update(kwargs["info"])
+        else:
+            raise ResultError(f"The key {k!r} does not exists on context data.")
+    return context

ddeutil/workflow/reusables.py

@@ -3,8 +3,49 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-# [x] Use dynamic config
-"""Reusables module that keep any template and template filter functions."""
+"""Reusable Components and Registry System.
+
+This module provides a registry system for reusable workflow components including
+tagged functions, template operations, and utility functions for parameter
+processing and template rendering.
+
+The registry system allows developers to create custom callable functions that
+can be invoked from workflows using the CallStage, enabling extensible and
+modular workflow design.
+
+Classes:
+    TagFunc: Tagged function wrapper for registry storage
+
+Functions:
+    tag: Decorator for registering callable functions
+    param2template: Convert parameters to template format
+    has_template: Check if string contains template variables
+    not_in_template: Validate template restrictions
+    extract_call: Extract callable information from registry
+    create_model_from_caller: Generate Pydantic models from function signatures
+
+Example:
+    ```python
+    from ddeutil.workflow.reusables import tag
+
+    @tag("data-processing", alias="process-csv")
+    def process_csv_file(input_path: str, output_path: str) -> dict:
+        # Custom processing logic
+        return {"status": "completed", "rows_processed": 1000}
+
+    # Use in workflow YAML:
+    # stages:
+    #   - name: "Process data"
+    #     uses: "data-processing/process-csv@latest"
+    #     args:
+    #       input_path: "/data/input.csv"
+    #       output_path: "/data/output.csv"
+    ```
+
+Note:
+    The registry system supports versioning and aliasing for better function
+    management and backward compatibility.
+"""
 from __future__ import annotations
 
 import copy
@@ -277,6 +318,7 @@ def str2template(
     value: str,
     params: DictData,
     *,
+    context: Optional[DictData] = None,
     filters: Optional[dict[str, FilterRegistry]] = None,
     registers: Optional[list[str]] = None,
 ) -> Optional[str]:
@@ -290,6 +332,7 @@ def str2template(
     :param value: (str) A string value that want to map with params.
     :param params: (DictData) A parameter value that getting with matched
         regular expression.
+    :param context: (DictData)
     :param filters: (dict[str, FilterRegistry]) A mapping of filter registry.
     :param registers: (Optional[list[str]]) Override list of register.
 
@@ -318,7 +361,7 @@ def str2template(
         #   I recommend to avoid logging params context on this case because it
         #   can include secret value.
         try:
-            getter: Any = getdot(caller, params)
+            getter: Any = getdot(caller, params | (context or {}))
         except ValueError:
             raise UtilError(
                 f"Parameters does not get dot with caller: {caller!r}."
@@ -347,6 +390,7 @@ def str2template(
 def param2template(
     value: T,
     params: DictData,
+    context: Optional[DictData] = None,
     filters: Optional[dict[str, FilterRegistry]] = None,
     *,
     extras: Optional[DictData] = None,
@@ -357,6 +401,7 @@ def param2template(
     :param value: (Any) A value that want to map with params.
     :param params: (DictData) A parameter value that getting with matched
         regular expression.
+    :param context: (DictData)
     :param filters: (dict[str, FilterRegistry]) A filter mapping for mapping
         with `map_post_filter` func.
     :param extras: (Optional[list[str]]) An Override extras.
@@ -372,16 +417,21 @@ def param2template(
     )
     if isinstance(value, dict):
         return {
-            k: param2template(value[k], params, filters, extras=extras)
+            k: param2template(value[k], params, context, filters, extras=extras)
             for k in value
         }
     elif isinstance(value, (list, tuple, set)):
         return type(value)(
-            [param2template(i, params, filters, extras=extras) for i in value]
+            [
+                param2template(i, params, context, filters, extras=extras)
+                for i in value
+            ]
         )
     elif not isinstance(value, str):
         return value
-    return str2template(value, params, filters=filters, registers=registers)
+    return str2template(
+        value, params, context=context, filters=filters, registers=registers
+    )
 
 
 @custom_filter("fmt")  # pragma: no cov