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

ddeutil/workflow/result.py

@@ -20,7 +20,6 @@ Functions:
 from __future__ import annotations
 
 from dataclasses import field
-from datetime import datetime
 from enum import Enum
 from typing import Optional, Union
 
@@ -40,9 +39,9 @@ from . import (
     WorkflowError,
 )
 from .__types import DictData
-from .audits import Trace, get_trace
+from .audits import TraceManager, get_trace
 from .errors import ResultError
-from .utils import default_gen_id, get_dt_now
+from .utils import default_gen_id
 
 
 class Status(str, Enum):
@@ -105,8 +104,9 @@ def validate_statuses(statuses: list[Status]) -> Status:
     """Determine final status from multiple status values.
 
     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.
+    of individual status values. Follows priority order:
+
+        CANCEL > FAILED > WAIT > individual status consistency.
 
     Args:
         statuses: List of status values to evaluate
@@ -132,7 +132,7 @@ def validate_statuses(statuses: list[Status]) -> Status:
     for status in (SUCCESS, SKIP):
         if all(s == status for s in statuses):
             return status
-    return FAILED if FAILED in statuses else SUCCESS
+    return SUCCESS
 
 
 def get_status_from_error(
@@ -166,10 +166,6 @@ def get_status_from_error(
     return FAILED
 
 
-def default_context() -> DictData:
-    return {"status": WAIT}
-
-
 @dataclass(
     config=ConfigDict(arbitrary_types_allowed=True, use_enum_values=True),
 )
@@ -186,14 +182,15 @@ class Result:
     field that keep dict value change its ID when update new value to it.
     """
 
+    extras: DictData = field(default_factory=dict, compare=False, repr=False)
     status: Status = field(default=WAIT)
-    context: DictData = field(default_factory=default_context)
+    context: Optional[DictData] = field(default=None)
     info: DictData = field(default_factory=dict)
-    run_id: Optional[str] = field(default_factory=default_gen_id)
+    run_id: str = field(default_factory=default_gen_id)
     parent_run_id: Optional[str] = field(default=None)
-    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)
+    trace: Optional[TraceManager] = field(
+        default=None, compare=False, repr=False
+    )
 
     @model_validator(mode="after")
     def __prepare_trace(self) -> Self:
@@ -202,25 +199,23 @@ class Result:
         :rtype: Self
         """
         if self.trace is None:  # pragma: no cov
-            self.trace: Trace = get_trace(
+            self.trace: TraceManager = get_trace(
                 self.run_id,
                 parent_run_id=self.parent_run_id,
                 extras=self.extras,
             )
-        return self
-
-    def set_parent_run_id(self, running_id: str) -> Self:
-        """Set a parent running ID.
 
-        :param running_id: (str) A running ID that want to update on this model.
+        return self
 
-        :rtype: Self
-        """
-        self.parent_run_id: str = running_id
-        self.trace: Trace = get_trace(
-            self.run_id, parent_run_id=running_id, extras=self.extras
+    @classmethod
+    def from_trace(cls, trace: TraceManager):
+        """Construct the result model from trace for clean code objective."""
+        return cls(
+            run_id=trace.run_id,
+            parent_run_id=trace.parent_run_id,
+            extras=trace.extras,
+            trace=trace,
         )
-        return self
 
     def catch(
         self,
@@ -237,7 +232,11 @@ class Result:
 
         :rtype: Self
         """
-        self.__dict__["context"].update(context or {})
+        if self.__dict__["context"] is None:
+            self.__dict__["context"] = context
+        else:
+            self.__dict__["context"].update(context or {})
+
         self.__dict__["status"] = (
             Status(status) if isinstance(status, int) else status
         )
@@ -262,13 +261,6 @@ class Result:
         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() - self.ts).total_seconds()
-
 
 def catch(
     context: DictData,
@@ -276,7 +268,13 @@ def catch(
     updated: DictData | None = None,
     **kwargs,
 ) -> DictData:
-    """Catch updated context to the current context."""
+    """Catch updated context to the current context.
+
+    Args:
+        context: A context data that want to be the current context.
+        status: A status enum object.
+        updated: A updated data that will update to the current context.
+    """
     context.update(updated or {})
     context["status"] = Status(status) if isinstance(status, int) else status
 
@@ -289,7 +287,7 @@ def catch(
             context[k].update(kwargs[k])
         # NOTE: Exclude the `info` key for update information data.
         elif k == "info":
-            context["info"].update(kwargs["info"])
+            context.update({"info": kwargs["info"]})
         else:
             raise ResultError(f"The key {k!r} does not exists on context data.")
     return context

ddeutil/workflow/reusables.py

@@ -119,12 +119,15 @@ FilterRegistry = Union[FilterFunc, Callable[[...], Any]]
 
 
 def custom_filter(name: str) -> Callable[P, FilterFunc]:
-    """Custom filter decorator function that set function attributes, ``filter``
-    for making filter registries variable.
+    """Custom filter decorator function that sets function attributes.
 
-    :param: name: (str) A filter name for make different use-case of a function.
+    This decorator sets the `filter` attribute for making filter registries variable.
 
-    :rtype: Callable[P, FilterFunc]
+    Args:
+        name: A filter name for different use-cases of a function.
+
+    Returns:
+        Callable[P, FilterFunc]: Decorated function with filter attributes.
     """
 
     def func_internal(func: Callable[[...], Any]) -> FilterFunc:
@@ -144,11 +147,13 @@ def custom_filter(name: str) -> Callable[P, FilterFunc]:
 def make_filter_registry(
     registers: Optional[list[str]] = None,
 ) -> dict[str, FilterRegistry]:
-    """Return registries of all functions that able to called with task.
+    """Return registries of all functions that can be called with tasks.
 
-    :param registers: (Optional[list[str]]) Override list of register.
+    Args:
+        registers: Optional override list of registers.
 
-    :rtype: dict[str, FilterRegistry]
+    Returns:
+        dict[str, FilterRegistry]: Dictionary mapping filter names to functions.
     """
     rs: dict[str, FilterRegistry] = {}
     for module in dynamic("registry_filter", f=registers):
@@ -180,9 +185,14 @@ def get_args_const(
 ) -> tuple[str, list[Constant], dict[str, Constant]]:
     """Get arguments and keyword-arguments from function calling string.
 
-    :param expr: (str) An expr string value.
+    Args:
+        expr: A string expression representing a function call.
+
+    Returns:
+        tuple[str, list[Constant], dict[str, Constant]]: Function name, args, and kwargs.
 
-    :rtype: tuple[str, list[Constant], dict[str, Constant]]
+    Raises:
+        UtilError: If the expression has syntax errors or invalid format.
     """
     try:
         mod: Module = parse(expr)
@@ -223,12 +233,18 @@ def get_args_from_filter(
     filters: dict[str, FilterRegistry],
 ) -> tuple[str, FilterRegistry, list[Any], dict[Any, Any]]:  # pragma: no cov
     """Get arguments and keyword-arguments from filter function calling string.
-    and validate it with the filter functions mapping dict.
 
-    :param ft:
-    :param filters: A mapping of filter registry.
+    This function validates the filter function call with the filter functions mapping dict.
+
+    Args:
+        ft: Filter function calling string.
+        filters: A mapping of filter registry.
 
-    :rtype: tuple[str, FilterRegistry, list[Any], dict[Any, Any]]
+    Returns:
+        tuple[str, FilterRegistry, list[Any], dict[Any, Any]]: Function name, function, args, and kwargs.
+
+    Raises:
+        UtilError: If the filter function is not supported or has invalid arguments.
     """
     func_name, _args, _kwargs = get_args_const(ft)
     args: list[Any] = [arg.value for arg in _args]
@@ -250,14 +266,18 @@ def map_post_filter(
     post_filter: list[str],
     filters: dict[str, FilterRegistry],
 ) -> T:
-    """Mapping post-filter to value with sequence list of filter function name
-    that will get from the filter registry.
+    """Map post-filter functions to value with sequence of filter function names.
+
+    Args:
+        value: A value to map with filter functions.
+        post_filter: A list of post-filter function names.
+        filters: A mapping of filter registry.
 
-    :param value: A string value that want to map with filter function.
-    :param post_filter: A list of post-filter function name.
-    :param filters: A mapping of filter registry.
+    Returns:
+        T: The value after applying all post-filter functions.
 
-    :rtype: T
+    Raises:
+        UtilError: If a post-filter function fails or is incompatible with the value.
     """
     for ft in post_filter:
         func_name, f_func, args, kwargs = get_args_from_filter(ft, filters)
@@ -278,13 +298,15 @@ def map_post_filter(
 
 
 def not_in_template(value: Any, *, not_in: str = "matrix.") -> bool:
-    """Check value should not pass template with not_in value prefix.
+    """Check if value should not pass template with not_in value prefix.
 
-    :param value: A value that want to find parameter template prefix.
-    :param not_in: The not-in string that use in the `.startswith` function.
-        (Default is `matrix.`)
+    Args:
+        value: A value to check for parameter template prefix.
+        not_in: The not-in string to use in the `.startswith` function.
+            Default is `matrix.`.
 
-    :rtype: bool
+    Returns:
+        bool: True if value should not pass template, False otherwise.
     """
     if isinstance(value, dict):
         return any(not_in_template(value[k], not_in=not_in) for k in value)
@@ -299,11 +321,13 @@ def not_in_template(value: Any, *, not_in: str = "matrix.") -> bool:
 
 
 def has_template(value: Any) -> bool:
-    """Check value include templating string.
+    """Check if value includes templating string.
 
-    :param value: A value that want to find parameter template.
+    Args:
+        value: A value to check for parameter template.
 
-    :rtype: bool
+    Returns:
+        bool: True if value contains template variables, False otherwise.
     """
     if isinstance(value, dict):
         return any(has_template(value[k]) for k in value)
@@ -322,21 +346,24 @@ def str2template(
     filters: Optional[dict[str, FilterRegistry]] = None,
     registers: Optional[list[str]] = None,
 ) -> Optional[str]:
-    """(Sub-function) Pass param to template string that can search by
-    ``RE_CALLER`` regular expression.
+    """Pass parameters to template string using RE_CALLER regular expression.
+
+    This is a sub-function that processes template strings. The getter value
+    that maps a template should have typing support aligned with workflow
+    parameter types: `str`, `int`, `datetime`, and `list`.
 
-        The getter value that map a template should have typing support align
-    with the workflow parameter types that is `str`, `int`, `datetime`, and
-    `list`.
+    Args:
+        value: A string value to map with parameters.
+        params: Parameter values to get with matched regular expression.
+        context: Optional context data.
+        filters: Optional mapping of filter registry.
+        registers: Optional override list of registers.
 
-    :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.
+    Returns:
+        Optional[str]: The processed template string or None if value is "None".
 
-    :rtype: str
+    Raises:
+        UtilError: If parameters cannot be retrieved or template processing fails.
     """
     filters: dict[str, FilterRegistry] = filters or make_filter_registry(
         registers=registers
@@ -395,19 +422,17 @@ def param2template(
     *,
     extras: Optional[DictData] = None,
 ) -> Any:
-    """Pass param to template string that can search by ``RE_CALLER`` regular
-    expression.
-
-    :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.
-
-    :rtype: Any
-    :returns: An any getter value from the params input.
+    """Pass parameters to template string using RE_CALLER regular expression.
+
+    Args:
+        value: A value to map with parameters.
+        params: Parameter values to get with matched regular expression.
+        context: Optional context data.
+        filters: Optional filter mapping for use with `map_post_filter` function.
+        extras: Optional override extras.
+
+    Returns:
+        Any: The processed value with template variables replaced.
     """
     registers: Optional[list[str]] = (
         extras.get("registry_filter") if extras else None
@@ -437,19 +462,21 @@ def param2template(
 
 @custom_filter("fmt")  # pragma: no cov
 def datetime_format(value: datetime, fmt: str = "%Y-%m-%d %H:%M:%S") -> str:
-    """Format datetime object to string with the format.
+    """Format datetime object to string with the specified 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`
-        method.
+    Args:
+        value: A datetime value to format to string.
+        fmt: A format string pattern to pass to the `dt.strftime` method.
 
-    :rtype: str
+    Returns:
+        str: The formatted datetime string.
+
+    Raises:
+        UtilError: If the input value is not a datetime object.
     """
     if isinstance(value, datetime):
         return value.strftime(fmt)
@@ -463,12 +490,14 @@ def coalesce(value: Optional[T], default: Any) -> T:
     """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.
+    Args:
+        value: A value to check for null.
+        default: A default value to return if the input value is null.
+
+    Returns:
+        T: The original value if not None, otherwise the default value.
     """
     return default if value is None else value
 
@@ -477,13 +506,22 @@ def coalesce(value: Optional[T], default: Any) -> T:
 def get_item(
     value: DictData, key: Union[str, int], default: Optional[Any] = None
 ) -> Any:
-    """Get a value with an input specific key.
+    """Get a value with a specific key.
 
     Examples:
-
         >>> "${{ value | getitem('key') }}"
         >>> "${{ value | getitem('key', 'default') }}"
 
+    Args:
+        value: A dictionary to get the value from.
+        key: The key to look up in the dictionary.
+        default: Optional default value if key is not found.
+
+    Returns:
+        Any: The value associated with the key, or the default value.
+
+    Raises:
+        UtilError: If the value is not a dictionary.
     """
     if not isinstance(value, dict):
         raise UtilError(
@@ -495,12 +533,20 @@ def get_item(
 
 @custom_filter("getindex")  # pragma: no cov
 def get_index(value: list[Any], index: int) -> Any:
-    """Get a value with an input specific index.
+    """Get a value with a specific index.
 
     Examples:
-
         >>> "${{ value | getindex(1) }}"
 
+    Args:
+        value: A list to get the value from.
+        index: The index to access in the list.
+
+    Returns:
+        Any: The value at the specified index.
+
+    Raises:
+        UtilError: If the value is not a list or if the index is out of range.
     """
     if not isinstance(value, list):
         raise UtilError(
@@ -534,16 +580,18 @@ def tag(
     name: Optional[str] = None,
     alias: Optional[str] = None,
 ) -> DecoratorTagFunc:  # pragma: no cov
-    """Tag decorator function that set function attributes, ``tag`` and ``name``
-    for making registries variable.
+    """Tag decorator function that sets function attributes for registry.
 
-    :param: name: (str) A tag name for make different use-case of a function.
-        It will use 'latest' if this tag name does not set.
-    :param: alias: (str) A alias function name that keeping in registries.
-        If this value does not supply, it will use original function name
-        from `__name__` argument.
+    This decorator sets the `tag` and `name` attributes for making registries variable.
 
-    :rtype: Callable[P, TagFunc]
+    Args:
+        name: A tag name for different use-cases of a function.
+            Uses 'latest' if not set.
+        alias: An alias function name to keep in registries.
+            Uses original function name from `__name__` if not supplied.
+
+    Returns:
+        DecoratorTagFunc: Decorated function with tag attributes.
     """
 
     def func_internal(func: Callable[[...], Any]) -> ReturnTagFunc:
@@ -574,12 +622,17 @@ def make_registry(
     *,
     registries: Optional[list[str]] = None,
 ) -> dict[str, Registry]:
-    """Return registries of all functions that able to called with task.
+    """Return registries of all functions that can be called with tasks.
+
+    Args:
+        submodule: A module prefix to import registry from.
+        registries: Optional list of registries.
 
-    :param submodule: (str) A module prefix that want to import registry.
-    :param registries: (Optional[list[str]]) A list of registry.
+    Returns:
+        dict[str, Registry]: Dictionary mapping function names to their registries.
 
-    :rtype: dict[str, Registry]
+    Raises:
+        ValueError: If a tag already exists for a function name.
     """
     rs: dict[str, Registry] = {}
     regis_calls: list[str] = copy.deepcopy(
@@ -599,7 +652,7 @@ def make_registry(
             if not (
                 hasattr(func, "tag")
                 and hasattr(func, "name")
-                and str(getattr(func, "mark", "NOT SET")) == "tag"
+                and str(getattr(func, "mark", "NOTSET")) == "tag"
             ):  # pragma: no cov
                 continue
 
@@ -617,6 +670,7 @@ def make_registry(
                     f"{module}.{submodule}, you should change this tag name or "
                     f"change it func name."
                 )
+
             rs[func.name][func.tag] = lazy(f"{module}.{submodule}.{fstr}")
 
     return rs
@@ -638,13 +692,9 @@ def extract_call(
     *,
     registries: Optional[list[str]] = None,
 ) -> Callable[[], TagFunc]:
-    """Extract Call function from string value to call partial function that
-    does run it at runtime.
+    """Extract call function from string value to call partial function at runtime.
 
-    :param call: (str) A call value that able to match with Task regex.
-    :param registries: (Optional[list[str]]) A list of registry.
-
-        The format of call value should contain 3 regular expression groups
+    The format of call value should contain 3 regular expression groups
     which match with the below config format:
 
         >>> "^(?P<path>[^/@]+)/(?P<func>[^@]+)@(?P<tag>.+)$"
@@ -655,12 +705,16 @@ def extract_call(
         >>> extract_call("tasks/return-type-not-valid@raise")
         ...
 
-    :raise NotImplementedError: When the searching call's function result does
-        not exist in the registry.
-    :raise NotImplementedError: When the searching call's tag result does not
-        exist in the registry with its function key.
+    Args:
+        call: A call value that matches the Task regex.
+        registries: Optional list of registries.
+
+    Returns:
+        Callable[[], TagFunc]: A callable function that can be executed.
 
-    :rtype: Callable[[], TagFunc]
+    Raises:
+        ValueError: If the call does not match the regex format.
+        NotImplementedError: If the function or tag does not exist in the registry.
     """
     if not (found := Re.RE_TASK_FMT.search(call)):
         raise ValueError(
@@ -696,17 +750,20 @@ class BaseCallerArgs(BaseModel):  # pragma: no cov
 
 
 def create_model_from_caller(func: Callable) -> BaseModel:  # pragma: no cov
-    """Create model from the caller function. This function will use for
-    validate the caller function argument typed-hint that valid with the args
-    field.
+    """Create model from the caller function.
+
+    This function is used to validate the caller function argument type hints
+    that are valid with the args field.
 
     Reference:
         - https://github.com/lmmx/pydantic-function-models
         - https://docs.pydantic.dev/1.10/usage/models/#dynamic-model-creation
 
-    :param func: (Callable) A caller function.
+    Args:
+        func: A caller function to create a model from.
 
-    :rtype: BaseModel
+    Returns:
+        BaseModel: A Pydantic model created from the function signature.
     """
     sig: inspect.Signature = inspect.signature(func)
     type_hints: dict[str, Any] = get_type_hints(func)