ddeutil-workflow 0.0.77__py3-none-any.whl → 0.0.79__py3-none-any.whl

ddeutil/workflow/params.py

@@ -14,17 +14,17 @@ 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
+    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
@@ -58,8 +58,11 @@ T = TypeVar("T")
 
 
 class BaseParam(BaseModel, ABC):
-    """Base Parameter that use to make any Params Models. The parameter type
-    will dynamic with the setup type field that made from literal string.
+    """Base Parameter that use to make any Params Models.
+
+    The parameter type will dynamic with the setup type field that made from
+    literal string. This abstract base class provides the foundation for all
+    parameter types with common validation and processing capabilities.
     """
 
     desc: Optional[str] = Field(
@@ -76,15 +79,28 @@ class BaseParam(BaseModel, ABC):
 
     @abstractmethod
     def receive(self, value: Optional[T] = None) -> T:
-        """Abstract method receive value to this parameter model."""
+        """Abstract method receive value to this parameter model.
+
+        Args:
+            value: The value to validate and process.
+
+        Returns:
+            T: The validated and processed value.
+
+        Raises:
+            NotImplementedError: If not implemented by subclass.
+        """
         raise NotImplementedError(
             "Receive value and validate typing before return valid value."
         )
 
 
 class DefaultParam(BaseParam, ABC):
-    """Default Parameter that will check default if it required. This model do
-    not implement the `receive` method.
+    """Default Parameter that will check default if it required.
+
+    This model extends BaseParam and provides default value handling capabilities.
+    It does not implement the `receive` method, which must be implemented by
+    concrete subclasses.
     """
 
     required: bool = Field(
@@ -98,14 +114,29 @@ class DefaultParam(BaseParam, ABC):
 
     @abstractmethod
     def receive(self, value: Optional[Any] = None) -> Any:
-        """Abstract method receive value to this parameter model."""
+        """Abstract method receive value to this parameter model.
+
+        Args:
+            value: The value to validate and process.
+
+        Returns:
+            Any: The validated and processed value.
+
+        Raises:
+            NotImplementedError: If not implemented by subclass.
+        """
         raise NotImplementedError(
             "Receive value and validate typing before return valid value."
         )
 
 
 class DateParam(DefaultParam):  # pragma: no cov
-    """Date parameter model."""
+    """Date parameter model.
+
+    This class provides date parameter validation and processing with support
+    for various input formats including ISO date strings, datetime objects,
+    and date objects.
+    """
 
     type: Literal["date"] = "date"
     default: date = Field(
@@ -116,12 +147,18 @@ class DateParam(DefaultParam):  # pragma: no cov
     def receive(
         self, value: Optional[Union[str, datetime, date]] = None
     ) -> date:
-        """Receive value that match with date. If an input value pass with
-        None, it will use default value instead.
+        """Receive value that match with date.
 
-        :param value: A value that want to validate with date parameter type.
+        If an input value pass with None, it will use default value instead.
 
-        :rtype: date
+        Args:
+            value: A value that want to validate with date parameter type.
+
+        Returns:
+            date: The validated date value.
+
+        Raises:
+            ParamError: If the value cannot be converted to a valid date.
         """
         if value is None:
             return self.default
@@ -144,7 +181,12 @@ class DateParam(DefaultParam):  # pragma: no cov
 
 
 class DatetimeParam(DefaultParam):
-    """Datetime parameter model."""
+    """Datetime parameter model.
+
+    This class provides datetime parameter validation and processing with support
+    for various input formats including ISO datetime strings, datetime objects,
+    and date objects. All datetime values are normalized to UTC timezone.
+    """
 
     type: Literal["datetime"] = "datetime"
     default: datetime = Field(
@@ -157,13 +199,18 @@ class DatetimeParam(DefaultParam):
     def receive(
         self, value: Optional[Union[str, datetime, date]] = None
     ) -> datetime:
-        """Receive value that match with datetime. If an input value pass with
-        None, it will use default value instead.
+        """Receive value that match with datetime.
+
+        If an input value pass with None, it will use default value instead.
+
+        Args:
+            value: A value that want to validate with datetime parameter type.
 
-        :param value: A value that want to validate with datetime parameter
-            type.
+        Returns:
+            datetime: The validated datetime value in UTC timezone.
 
-        :rtype: datetime
+        Raises:
+            ParamError: If the value cannot be converted to a valid datetime.
         """
         if value is None:
             return self.default
@@ -188,16 +235,22 @@ class DatetimeParam(DefaultParam):
 
 
 class StrParam(DefaultParam):
-    """String parameter."""
+    """String parameter.
+
+    This class provides string parameter validation and processing with support
+    for converting various input types to strings.
+    """
 
     type: Literal["str"] = "str"
 
     def receive(self, value: Optional[Any] = None) -> Optional[str]:
         """Receive value that match with str.
 
-        :param value: (Any) A value that want to validate with string parameter
-            type.
-        :rtype: Optional[str]
+        Args:
+            value: A value that want to validate with string parameter type.
+
+        Returns:
+            Optional[str]: The validated string value or None.
         """
         if value is None:
             return self.default
@@ -205,15 +258,25 @@ class StrParam(DefaultParam):
 
 
 class IntParam(DefaultParam):
-    """Integer parameter."""
+    """Integer parameter.
+
+    This class provides integer parameter validation and processing with support
+    for converting various numeric types to integers.
+    """
 
     type: Literal["int"] = "int"
 
     def receive(self, value: Optional[StrOrInt] = None) -> Optional[int]:
         """Receive value that match with int.
 
-        :param value: A value that want to validate with integer parameter type.
-        :rtype: int | None
+        Args:
+            value: A value that want to validate with integer parameter type.
+
+        Returns:
+            Optional[int]: The validated integer value or None.
+
+        Raises:
+            ParamError: If the value cannot be converted to an integer.
         """
         if value is None:
             return self.default
@@ -228,7 +291,11 @@ class IntParam(DefaultParam):
 
 
 class FloatParam(DefaultParam):  # pragma: no cov
-    """Float parameter."""
+    """Float parameter.
+
+    This class provides float parameter validation and processing with precision
+    control for rounding float values to a specified number of decimal places.
+    """
 
     type: Literal["float"] = "float"
     precision: int = 6
@@ -236,9 +303,11 @@ class FloatParam(DefaultParam):  # pragma: no cov
     def rounding(self, value: float) -> float:
         """Rounding float value with the specific precision field.
 
-        :param value: A float value that want to round with the precision value.
+        Args:
+            value: A float value that want to round with the precision value.
 
-        :rtype: float
+        Returns:
+            float: The rounded float value.
         """
         round_str: str = f"{{0:.{self.precision}f}}"
         return float(round_str.format(round(value, self.precision)))
@@ -248,8 +317,14 @@ class FloatParam(DefaultParam):  # pragma: no cov
     ) -> Optional[float]:
         """Receive value that match with float.
 
-        :param value: A value that want to validate with float parameter type.
-        :rtype: float | None
+        Args:
+            value: A value that want to validate with float parameter type.
+
+        Returns:
+            Optional[float]: The validated float value or None.
+
+        Raises:
+            TypeError: If the value type is not supported.
         """
         if value is None:
             return self.default
@@ -266,18 +341,23 @@ class FloatParam(DefaultParam):  # pragma: no cov
 
 
 class DecimalParam(DefaultParam):  # pragma: no cov
-    """Decimal parameter."""
+    """Decimal parameter.
+
+    This class provides decimal parameter validation and processing with precision
+    control for financial calculations and exact decimal arithmetic.
+    """
 
     type: Literal["decimal"] = "decimal"
     precision: int = 6
 
     def rounding(self, value: Decimal) -> Decimal:
-        """Rounding float value with the specific precision field.
+        """Rounding decimal value with the specific precision field.
 
-        :param value: (Decimal) A Decimal value that want to round with the
-            precision value.
+        Args:
+            value: A Decimal value that want to round with the precision value.
 
-        :rtype: Decimal
+        Returns:
+            Decimal: The rounded decimal value.
         """
         return value.quantize(Decimal(10) ** -self.precision)
 
@@ -286,9 +366,15 @@ class DecimalParam(DefaultParam):  # pragma: no cov
     ) -> Decimal:
         """Receive value that match with decimal.
 
-        :param value: (float | Decimal) A value that want to validate with
-            decimal parameter type.
-        :rtype: Decimal | None
+        Args:
+            value: A value that want to validate with decimal parameter type.
+
+        Returns:
+            Decimal: The validated decimal value.
+
+        Raises:
+            TypeError: If the value type is not supported.
+            ValueError: If the string cannot be converted to a valid decimal.
         """
         if value is None:
             return self.default
@@ -311,7 +397,11 @@ class DecimalParam(DefaultParam):  # pragma: no cov
 
 
 class ChoiceParam(BaseParam):
-    """Choice parameter."""
+    """Choice parameter.
+
+    This class provides choice parameter validation and processing with support
+    for predefined options. If no value is provided, it returns the first option.
+    """
 
     type: Literal["choice"] = "choice"
     options: Union[list[str], list[int]] = Field(
@@ -321,9 +411,14 @@ class ChoiceParam(BaseParam):
     def receive(self, value: Optional[StrOrInt] = None) -> StrOrInt:
         """Receive value that match with options.
 
-        :param value: (str | int) A value that want to select from the options
-            field.
-        :rtype: str | int
+        Args:
+            value: A value that want to select from the options field.
+
+        Returns:
+            StrOrInt: The validated choice value.
+
+        Raises:
+            ParamError: If the value is not in the available options.
         """
         # NOTE:
         #   Return the first value in options if it does not pass any input
@@ -338,7 +433,11 @@ class ChoiceParam(BaseParam):
 
 
 class MapParam(DefaultParam):
-    """Map parameter."""
+    """Map parameter.
+
+    This class provides dictionary/mapping parameter validation and processing
+    with support for converting string representations to dictionaries.
+    """
 
     type: Literal["map"] = "map"
     default: dict[Any, Any] = Field(
@@ -352,9 +451,14 @@ class MapParam(DefaultParam):
     ) -> dict[Any, Any]:
         """Receive value that match with map type.
 
-        :param value: A value that want to validate with map parameter type.
+        Args:
+            value: A value that want to validate with map parameter type.
 
-        :rtype: dict[Any, Any]
+        Returns:
+            dict[Any, Any]: The validated dictionary value.
+
+        Raises:
+            ParamError: If the value cannot be converted to a valid dictionary.
         """
         if value is None:
             return self.default
@@ -376,7 +480,11 @@ class MapParam(DefaultParam):
 
 
 class ArrayParam(DefaultParam):
-    """Array parameter."""
+    """Array parameter.
+
+    This class provides list/array parameter validation and processing with support
+    for converting various sequence types to lists.
+    """
 
     type: Literal["array"] = "array"
     default: list[Any] = Field(
@@ -389,8 +497,14 @@ class ArrayParam(DefaultParam):
     ) -> list[T]:
         """Receive value that match with array type.
 
-        :param value: A value that want to validate with array parameter type.
-        :rtype: list[Any]
+        Args:
+            value: A value that want to validate with array parameter type.
+
+        Returns:
+            list[T]: The validated list value.
+
+        Raises:
+            ParamError: If the value cannot be converted to a valid list.
         """
         if value is None:
             return self.default