ddeutil-workflow 0.0.60__tar.gz → 0.0.62__tar.gz

{ddeutil_workflow-0.0.60 → ddeutil_workflow-0.0.62}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ddeutil-workflow
-Version: 0.0.60
+Version: 0.0.62
 Summary: Lightweight workflow orchestration
 Author-email: ddeutils <korawich.anu@gmail.com>
 License: MIT

ddeutil_workflow-0.0.62/src/ddeutil/workflow/__about__.py

@@ -0,0 +1 @@
+__version__: str = "0.0.62"

{ddeutil_workflow-0.0.60 → ddeutil_workflow-0.0.62}/src/ddeutil/workflow/__cron.py

@@ -18,7 +18,7 @@ from ddeutil.core import (
     isinstance_check,
     must_split,
 )
-from ddeutil.core.dtutils import next_date, replace_date
+from ddeutil.core.dtutils import DatetimeMode, next_date, replace_date
 
 WEEKDAYS: dict[str, int] = {
     "Sun": 0,
@@ -31,7 +31,8 @@ WEEKDAYS: dict[str, int] = {
 }
 
 
-class CronYearLimit(Exception): ...
+class YearReachLimit(Exception):
+    """"""
 
 
 def str2cron(value: str) -> str:  # pragma: no cov
@@ -178,7 +179,7 @@ class CronPart:
     def __init__(
         self,
         unit: Unit,
-        values: str | list[int],
+        values: Union[str, list[int]],
         options: Options,
     ) -> None:
         self.unit: Unit = unit
@@ -229,19 +230,21 @@ class CronPart:
             f"(unit={self.unit}, values={self.__str__()!r})"
         )
 
-    def __lt__(self, other) -> bool:
+    def __lt__(self, other: Union[CronPart, list]) -> bool:
         """Override __lt__ method."""
         if isinstance(other, CronPart):
             return self.values < other.values
         elif isinstance(other, list):
             return self.values < other
+        return NotImplemented
 
-    def __eq__(self, other) -> bool:
+    def __eq__(self, other: Union[CronPart, list]) -> bool:
         """Override __eq__ method."""
         if isinstance(other, CronPart):
             return self.values == other.values
         elif isinstance(other, list):
             return self.values == other
+        return NotImplemented
 
     @property
     def min(self) -> int:
@@ -271,6 +274,7 @@ class CronPart:
             and (step := self.values[1] - self.values[0]) > 1
         ):
             return step
+        return None
 
     @property
     def is_full(self) -> bool:
@@ -355,6 +359,8 @@ class CronPart:
                     f"Invalid interval step value {value_step!r} for "
                     f"{self.unit.name!r}"
                 )
+            elif value_step:
+                value_step: int = int(value_step)
 
             # NOTE: Generate interval that has step
             interval_list.append(self._interval(value_range_list, value_step))
@@ -375,7 +381,9 @@ class CronPart:
                 value: str = value.replace(alt, str(self.unit.min + i))
         return value
 
-    def replace_weekday(self, values: list[int] | Iterator[int]) -> list[int]:
+    def replace_weekday(
+        self, values: Union[list[int], Iterator[int]]
+    ) -> list[int]:
         """Replaces all 7 with 0 as Sunday can be represented by both.
 
         :param values: list or iter of int that want to mode by 7
@@ -433,12 +441,12 @@ class CronPart:
     def _interval(
         self,
         values: list[int],
-        step: int | None = None,
+        step: Optional[int] = None,
     ) -> list[int]:
         """Applies an interval step to a collection of values.
 
         :param values:
-        :param step:
+        :param step: (int) A step
 
         :rtype: list[int]
         """
@@ -515,7 +523,7 @@ class CronPart:
                 start_number: Optional[int] = value
         return multi_dim_values
 
-    def filler(self, value: int) -> int | str:
+    def filler(self, value: int) -> Union[int, str]:
         """Formats weekday and month names as string when the relevant options
         are set.
 
@@ -765,12 +773,12 @@ class CronRunner:
 
     def __init__(
         self,
-        cron: CronJob | CronJobYear,
+        cron: Union[CronJob, CronJobYear],
         date: Optional[datetime] = None,
         *,
-        tz: str | ZoneInfo | None = None,
+        tz: Optional[Union[str, ZoneInfo]] = None,
     ) -> None:
-        self.tz: ZoneInfo | None = None
+        self.tz: Optional[ZoneInfo] = None
         if tz:
             if isinstance(tz, ZoneInfo):
                 self.tz = tz
@@ -810,7 +818,7 @@ class CronRunner:
             )
 
         self.__start_date: datetime = self.date
-        self.cron: CronJob | CronJobYear = cron
+        self.cron: Union[CronJob, CronJobYear] = cron
         self.is_year: bool = isinstance(cron, CronJobYear)
         self.reset_flag: bool = True
 
@@ -863,7 +871,7 @@ class CronRunner:
 
         raise RecursionError("Unable to find execution time for schedule")
 
-    def __shift_date(self, mode: str, reverse: bool = False) -> bool:
+    def __shift_date(self, mode: DatetimeMode, reverse: bool = False) -> bool:
         """Increments the mode of date value ("month", "day", "hour", "minute")
         until matches with the schedule.
 
@@ -897,8 +905,8 @@ class CronRunner:
                 getattr(self.date, mode)
                 > (max_year := max(self.cron.year.values))
             ):
-                raise CronYearLimit(
-                    f"The year is out of limit with this crontab value: "
+                raise YearReachLimit(
+                    f"The year is reach the limit with this crontab setting: "
                     f"{max_year}."
                 )
 
@@ -917,12 +925,3 @@ class CronRunner:
 
         # NOTE: Return False if the date that match with condition.
         return False
-
-
-__all__ = (
-    "CronJob",
-    "CronJobYear",
-    "CronRunner",
-    "Options",
-    "WEEKDAYS",
-)

{ddeutil_workflow-0.0.60 → ddeutil_workflow-0.0.62}/src/ddeutil/workflow/event.py

@@ -314,3 +314,26 @@ class CrontabYear(Crontab):
             if isinstance(value, str)
             else value
         )
+
+
+class ReleaseEvent(BaseModel):  # pragma: no cov
+    """Release trigger event."""
+
+    release: list[str] = Field(
+        description=(
+            "A list of workflow name that want to receive event from release"
+            "trigger."
+        )
+    )
+
+
+Event = Annotated[
+    Union[
+        CronJobYear,
+        CronJob,
+    ],
+    Field(
+        union_mode="smart",
+        description="An event models.",
+    ),
+]  # pragma: no cov

{ddeutil_workflow-0.0.60 → ddeutil_workflow-0.0.62}/src/ddeutil/workflow/logs.py

@@ -23,7 +23,7 @@ from inspect import Traceback, currentframe, getframeinfo
 from pathlib import Path
 from threading import get_ident
 from types import FrameType
-from typing import ClassVar, Literal, Optional, TypeVar, Union
+from typing import ClassVar, Final, Literal, Optional, TypeVar, Union
 
 from pydantic import BaseModel, ConfigDict, Field
 from pydantic.functional_validators import model_validator
@@ -74,7 +74,7 @@ def get_dt_tznow() -> datetime:  # pragma: no cov
     return get_dt_now(tz=config.tz)
 
 
-PREFIX_LOGS: dict[str, dict] = {
+PREFIX_LOGS: Final[dict[str, dict]] = {
     "CALLER": {
         "emoji": "📍",
         "desc": "logs from any usage from custom caller function.",
@@ -85,7 +85,7 @@ PREFIX_LOGS: dict[str, dict] = {
     "RELEASE": {"emoji": "📅", "desc": "logs from release workflow method."},
     "POKING": {"emoji": "⏰", "desc": "logs from poke workflow method."},
 }  # pragma: no cov
-PREFIX_DEFAULT: str = "CALLER"
+PREFIX_DEFAULT: Final[str] = "CALLER"
 PREFIX_LOGS_REGEX: re.Pattern[str] = re.compile(
     rf"(^\[(?P<name>{'|'.join(PREFIX_LOGS)})]:\s?)?(?P<message>.*)",
     re.MULTILINE | re.DOTALL | re.ASCII | re.VERBOSE,
@@ -103,6 +103,9 @@ class PrefixMsg(BaseModel):
     def prepare(self, extras: Optional[DictData] = None) -> str:
         """Prepare message with force add prefix before writing trace log.
 
+        :param extras: (DictData) An extra parameter that want to get the
+            `log_add_emoji` flag.
+
         :rtype: str
         """
         name: str = self.name or PREFIX_DEFAULT
@@ -332,9 +335,7 @@ class BaseTrace(BaseModel, ABC):  # pragma: no cov
 
         :param message: (str) A message that want to log.
         """
-        msg: str = prepare_newline(
-            self.make_message(extract_msg_prefix(message).prepare(self.extras))
-        )
+        msg: str = self.make_message(message)
 
         if mode != "debug" or (
             mode == "debug" and dynamic("debug", extras=self.extras)
@@ -391,9 +392,7 @@ class BaseTrace(BaseModel, ABC):  # pragma: no cov
 
         :param message: (str) A message that want to log.
         """
-        msg: str = prepare_newline(
-            self.make_message(extract_msg_prefix(message).prepare(self.extras))
-        )
+        msg: str = self.make_message(message)
 
         if mode != "debug" or (
             mode == "debug" and dynamic("debug", extras=self.extras)
@@ -514,13 +513,15 @@ class FileTrace(BaseTrace):  # pragma: no cov
         return f"{cut_parent_run_id} -> {cut_run_id}"
 
     def make_message(self, message: str) -> str:
-        """Prepare and Make a message before write and log processes.
+        """Prepare and Make a message before write and log steps.
 
         :param message: (str) A message that want to prepare and make before.
 
         :rtype: str
         """
-        return f"({self.cut_id}) {message}"
+        return prepare_newline(
+            f"({self.cut_id}) {extract_msg_prefix(message).prepare(self.extras)}"
+        )
 
     def writer(self, message: str, level: str, is_err: bool = False) -> None:
         """Write a trace message after making to target file and write metadata

{ddeutil_workflow-0.0.60 → ddeutil_workflow-0.0.62}/src/ddeutil/workflow/params.py

@@ -20,6 +20,7 @@ from typing import Annotated, Any, Literal, Optional, TypeVar, Union
 from ddeutil.core import str2dict, str2list
 from pydantic import BaseModel, Field
 
+from .__types import StrOrInt
 from .exceptions import ParamValueException
 from .utils import get_d_now, get_dt_now
 
@@ -159,10 +160,11 @@ class StrParam(DefaultParam):
 
     type: Literal["str"] = "str"
 
-    def receive(self, value: Optional[str] = None) -> Optional[str]:
+    def receive(self, value: Optional[Any] = None) -> Optional[str]:
         """Receive value that match with str.
 
-        :param value: A value that want to validate with string parameter type.
+        :param value: (Any) A value that want to validate with string parameter
+            type.
         :rtype: Optional[str]
         """
         if value is None:
@@ -175,7 +177,7 @@ class IntParam(DefaultParam):
 
     type: Literal["int"] = "int"
 
-    def receive(self, value: Optional[int] = None) -> Optional[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.
@@ -200,13 +202,24 @@ class FloatParam(DefaultParam):  # pragma: no cov
     precision: int = 6
 
     def rounding(self, value: float) -> float:
-        """Rounding float value with the specific precision field."""
+        """Rounding float value with the specific precision field.
+
+        :param value: A float value that want to round with the precision value.
+
+        :rtype: float
+        """
         round_str: str = f"{{0:.{self.precision}f}}"
         return float(round_str.format(round(value, self.precision)))
 
-    def receive(self, value: Optional[Union[float, int, str]] = None) -> float:
+    def receive(
+        self, value: Optional[Union[float, int, str]] = None
+    ) -> Optional[float]:
+        """Receive value that match with float.
 
-        if value in None:
+        :param value: A value that want to validate with float parameter type.
+        :rtype: float | None
+        """
+        if value is None:
             return self.default
 
         if isinstance(value, float):
@@ -217,11 +230,7 @@ class FloatParam(DefaultParam):  # pragma: no cov
             raise TypeError(
                 "Received value type does not math with str, float, or int."
             )
-
-        try:
-            return self.rounding(float(value))
-        except Exception:
-            raise
+        return self.rounding(float(value))
 
 
 class DecimalParam(DefaultParam):  # pragma: no cov
@@ -231,12 +240,28 @@ class DecimalParam(DefaultParam):  # pragma: no cov
     precision: int = 6
 
     def rounding(self, value: Decimal) -> Decimal:
-        """Rounding float value with the specific precision field."""
+        """Rounding float value with the specific precision field.
+
+        :param value: (Decimal) A Decimal value that want to round with the
+            precision value.
+
+        :rtype: Decimal
+        """
         return value.quantize(Decimal(10) ** -self.precision)
 
-    def receive(self, value: float | Decimal | None = None) -> Decimal:
+    def receive(
+        self, value: Optional[Union[float, int, str, Decimal]] = None
+    ) -> Decimal:
+        """Receive value that match with decimal.
 
-        if isinstance(value, float):
+        :param value: (float | Decimal) A value that want to validate with
+            decimal parameter type.
+        :rtype: Decimal | None
+        """
+        if value is None:
+            return self.default
+
+        if isinstance(value, (float, int)):
             return self.rounding(Decimal(value))
         elif isinstance(value, Decimal):
             return self.rounding(value)
@@ -261,11 +286,12 @@ class ChoiceParam(BaseParam):
         description="A list of choice parameters that able be str or int.",
     )
 
-    def receive(self, value: Union[str, int] | None = None) -> Union[str, int]:
+    def receive(self, value: Optional[StrOrInt] = None) -> StrOrInt:
         """Receive value that match with options.
 
-        :param value: A value that want to select from the options field.
-        :rtype: str
+        :param value: (str | int) A value that want to select from the options
+            field.
+        :rtype: str | int
         """
         # NOTE:
         #   Return the first value in options if it does not pass any input
@@ -279,7 +305,7 @@ class ChoiceParam(BaseParam):
         return value
 
 
-class MapParam(DefaultParam):  # pragma: no cov
+class MapParam(DefaultParam):
     """Map parameter."""
 
     type: Literal["map"] = "map"
@@ -295,6 +321,7 @@ class MapParam(DefaultParam):  # pragma: no cov
         """Receive value that match with map type.
 
         :param value: A value that want to validate with map parameter type.
+
         :rtype: dict[Any, Any]
         """
         if value is None:
@@ -316,7 +343,7 @@ class MapParam(DefaultParam):  # pragma: no cov
         return value
 
 
-class ArrayParam(DefaultParam):  # pragma: no cov
+class ArrayParam(DefaultParam):
     """Array parameter."""
 
     type: Literal["array"] = "array"
@@ -326,7 +353,7 @@ class ArrayParam(DefaultParam):  # pragma: no cov
     )
 
     def receive(
-        self, value: Optional[Union[list[T], tuple[T, ...], str]] = None
+        self, value: Optional[Union[list[T], tuple[T, ...], set[T], str]] = None
     ) -> list[T]:
         """Receive value that match with array type.
 
@@ -365,5 +392,11 @@ Param = Annotated[
         IntParam,
         StrParam,
     ],
-    Field(discriminator="type"),
+    Field(
+        discriminator="type",
+        description=(
+            "A parameter models that use for validate and receive on the "
+            "workflow execution."
+        ),
+    ),
 ]

{ddeutil_workflow-0.0.60 → ddeutil_workflow-0.0.62}/src/ddeutil/workflow/reusables.py

@@ -4,7 +4,7 @@
 # license information.
 # ------------------------------------------------------------------------------
 # [x] Use dynamic config
-"""Reusables module that keep any templating functions."""
+"""Reusables module that keep any template and template filter functions."""
 from __future__ import annotations
 
 import copy
@@ -14,7 +14,7 @@ from ast import Call, Constant, Expr, Module, Name, parse
 from datetime import datetime
 from functools import wraps
 from importlib import import_module
-from typing import Any, Callable, Optional, Protocol, TypeVar, Union
+from typing import Any, Callable, Literal, Optional, Protocol, TypeVar, Union
 
 try:
     from typing import ParamSpec
@@ -32,7 +32,7 @@ from .exceptions import UtilException
 T = TypeVar("T")
 P = ParamSpec("P")
 
-logger = logging.getLogger("ddeutil.workflow")
+# NOTE: Adjust logging level of the `asyncio` to INFO level.
 logging.getLogger("asyncio").setLevel(logging.INFO)
 
 
@@ -40,10 +40,14 @@ FILTERS: dict[str, Callable] = {  # pragma: no cov
     "abs": abs,
     "str": str,
     "int": int,
+    "list": list,
+    "dict": dict,
     "title": lambda x: x.title(),
     "upper": lambda x: x.upper(),
     "lower": lambda x: x.lower(),
     "rstr": [str, repr],
+    "keys": lambda x: x.keys(),
+    "values": lambda x: x.values(),
 }
 
 
@@ -53,6 +57,7 @@ class FilterFunc(Protocol):
     """
 
     filter: str
+    mark: Literal["filter"] = "filter"
 
     def __call__(self, *args, **kwargs): ...  # pragma: no cov
 
@@ -71,6 +76,7 @@ def custom_filter(name: str) -> Callable[P, FilterFunc]:
 
     def func_internal(func: Callable[[...], Any]) -> FilterFunc:
         func.filter = name
+        func.mark = "filter"
 
         @wraps(func)
         def wrapped(*args, **kwargs):
@@ -102,7 +108,10 @@ def make_filter_registry(
         for fstr, func in inspect.getmembers(importer, inspect.isfunction):
             # NOTE: check function attribute that already set tag by
             #   ``utils.tag`` decorator.
-            if not hasattr(func, "filter"):
+            if not (
+                hasattr(func, "filter")
+                and str(getattr(func, "mark", "NOT SET")) == "filter"
+            ):
                 continue
 
             func: FilterFunc
@@ -207,11 +216,9 @@ def map_post_filter(
                     value: T = func(value)
             else:
                 value: T = f_func(value, *args, **kwargs)
-        except UtilException as err:
-            logger.warning(str(err))
+        except UtilException:
             raise
-        except Exception as err:
-            logger.warning(str(err))
+        except Exception:
             raise UtilException(
                 f"The post-filter: {func_name!r} does not fit with {value!r} "
                 f"(type: {type(value).__name__})."
@@ -301,7 +308,7 @@ def str2template(
             getter: Any = getdot(caller, params)
         except ValueError as err:
             raise UtilException(
-                f"Params does not set caller: {caller!r}."
+                f"Parameters does not get dot with caller: {caller!r}."
             ) from err
 
         # NOTE:
@@ -330,7 +337,7 @@ def param2template(
     filters: Optional[dict[str, FilterRegistry]] = None,
     *,
     extras: Optional[DictData] = None,
-) -> T:
+) -> Any:
     """Pass param to template string that can search by ``RE_CALLER`` regular
     expression.
 
@@ -340,7 +347,7 @@ def param2template(
     :param filters: A filter mapping for mapping with `map_post_filter` func.
     :param extras: (Optional[list[str]]) An Override extras.
 
-    :rtype: T
+    :rtype: Any
     :returns: An any getter value from the params input.
     """
     registers: Optional[list[str]] = (
@@ -367,6 +374,11 @@ def param2template(
 def datetime_format(value: datetime, fmt: str = "%Y-%m-%d %H:%M:%S") -> str:
     """Format datetime object to string with the format.
 
+    Examples:
+
+        > ${{ start-date | fmt('%Y%m%d') }}
+        > ${{ start-date | fmt }}
+
     :param value: (datetime) A datetime value that want to format to string
         value.
     :param fmt: (str) A format string pattern that passing to the `dt.strftime`
@@ -383,15 +395,54 @@ def datetime_format(value: datetime, fmt: str = "%Y-%m-%d %H:%M:%S") -> str:
 
 @custom_filter("coalesce")  # pragma: no cov
 def coalesce(value: Optional[T], default: Any) -> T:
-    """Coalesce with default value if the main value is None."""
+    """Coalesce with default value if the main value is None.
+
+    Examples:
+
+        > ${{ value | coalesce("foo") }}
+
+    :param value: A value that want to check nullable.
+    :param default: A default value that use to returned value if an input
+        value was null.
+    """
     return default if value is None else value
 
 
+@custom_filter("getitem")  # pragma: no cov
+def get_item(
+    value: DictData, key: Union[str, int], default: Optional[Any] = None
+) -> Any:
+    """Get a value with an input specific key."""
+    if not isinstance(value, dict):
+        raise UtilException(
+            f"The value that pass to `getitem` filter should be `dict` not "
+            f"`{type(value)}`."
+        )
+    return value.get(key, default)
+
+
+@custom_filter("getindex")  # pragma: no cov
+def get_index(value: list[Any], index: int):
+    if not isinstance(value, list):
+        raise UtilException(
+            f"The value that pass to `getindex` filter should be `list` not "
+            f"`{type(value)}`."
+        )
+    try:
+        return value[index]
+    except IndexError as e:
+        raise UtilException(
+            f"Index: {index} is out of range of value (The maximum range is "
+            f"{len(value)})."
+        ) from e
+
+
 class TagFunc(Protocol):
     """Tag Function Protocol"""
 
     name: str
     tag: str
+    mark: Literal["tag"] = "tag"
 
     def __call__(self, *args, **kwargs): ...  # pragma: no cov
 
@@ -419,6 +470,7 @@ def tag(
     def func_internal(func: Callable[[...], Any]) -> ReturnTagFunc:
         func.tag = name or "latest"
         func.name = alias or func.__name__.replace("_", "-")
+        func.mark = "tag"
 
         @wraps(func)
         def wrapped(*args: P.args, **kwargs: P.kwargs) -> TagFunc:
@@ -466,7 +518,9 @@ def make_registry(
             # NOTE: check function attribute that already set tag by
             #   ``utils.tag`` decorator.
             if not (
-                hasattr(func, "tag") and hasattr(func, "name")
+                hasattr(func, "tag")
+                and hasattr(func, "name")
+                and str(getattr(func, "mark", "NOT SET")) == "tag"
             ):  # pragma: no cov
                 continue