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

ddeutil/workflow/utils.py

@@ -3,7 +3,35 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-"""Utility function model."""
+"""Utility Functions for Workflow Operations.
+
+This module provides essential utility functions used throughout the workflow
+system for ID generation, datetime handling, string processing, template
+operations, and other common tasks.
+
+Functions:
+    gen_id: Generate unique identifiers for workflow components
+    make_exec: Create executable strings for shell commands
+    filter_func: Filter functions based on criteria
+    dump_all: Serialize data to various formats
+    delay: Create delays in execution
+    to_train: Convert strings to train-case format
+    get_dt_now: Get current datetime with timezone
+    get_d_now: Get current date
+    cross_product: Generate cross product of matrix values
+    replace_sec: Replace template variables in strings
+
+Example:
+    ```python
+    from ddeutil.workflow.utils import gen_id, get_dt_now
+
+    # Generate unique ID
+    run_id = gen_id("workflow")
+
+    # Get current datetime
+    now = get_dt_now()
+    ```
+"""
 from __future__ import annotations
 
 import stat
@@ -27,13 +55,19 @@ T = TypeVar("T")
 UTC: Final[ZoneInfo] = ZoneInfo("UTC")
 MARK_NEWLINE: Final[str] = "||"
 
+# Cache for random delay values to avoid repeated randrange calls
+_CACHED_DELAYS = [randrange(0, 99, step=10) / 100 for _ in range(100)]
+_DELAY_INDEX = 0
+
 
 def to_train(camel: str) -> str:
     """Convert camel case string to train case.
 
-    :param camel: (str) A camel case string that want to convert.
+    Args:
+        camel: A camel case string that want to convert.
 
-    :rtype: str
+    Returns:
+        str: The converted train-case string.
     """
     return "".join("-" + i if i.isupper() else i for i in camel).lstrip("-")
 
@@ -41,9 +75,11 @@ def to_train(camel: str) -> str:
 def prepare_newline(msg: str) -> str:
     """Prepare message that has multiple newline char.
 
-    :param msg: (str) A message that want to prepare.
+    Args:
+        msg: A message that want to prepare.
 
-    :rtype: str
+    Returns:
+        str: The prepared message with formatted newlines.
     """
     # NOTE: Remove ending with "\n" and replace "\n" with the "||" value.
     msg: str = msg.strip("\n").replace("\n", MARK_NEWLINE)
@@ -63,42 +99,42 @@ def prepare_newline(msg: str) -> str:
 def replace_sec(dt: datetime) -> datetime:
     """Replace second and microsecond values to 0.
 
-    :param dt: A datetime object that want to replace.
+    Args:
+        dt: A datetime object that want to replace.
 
-    :rtype: datetime
+    Returns:
+        datetime: The datetime with seconds and microseconds set to 0.
     """
     return dt.replace(second=0, microsecond=0)
 
 
 def clear_tz(dt: datetime) -> datetime:
-    """Replace timezone info on an input datetime object to None."""
-    return dt.replace(tzinfo=None)
+    """Replace timezone info on an input datetime object to UTC."""
+    return dt.replace(tzinfo=UTC)
 
 
-def get_dt_now(tz: Optional[ZoneInfo] = None, offset: float = 0.0) -> datetime:
+def get_dt_now(offset: float = 0.0) -> datetime:
     """Return the current datetime object.
 
-    :param tz: A ZoneInfo object for replace timezone of return datetime object.
     :param offset: An offset second value.
 
     :rtype: datetime
     :return: The current datetime object that use an input timezone or UTC.
     """
-    return datetime.now(tz=tz) - timedelta(seconds=offset)
+    return datetime.now().replace(tzinfo=UTC) - timedelta(seconds=offset)
 
 
-def get_d_now(
-    tz: Optional[ZoneInfo] = None, offset: float = 0.0
-) -> date:  # pragma: no cov
+def get_d_now(offset: float = 0.0) -> date:  # pragma: no cov
     """Return the current date object.
 
-    :param tz: A ZoneInfo object for replace timezone of return date object.
     :param offset: An offset second value.
 
     :rtype: date
     :return: The current date object that use an input timezone or UTC.
     """
-    return (datetime.now(tz=tz) - timedelta(seconds=offset)).date()
+    return (
+        datetime.now().replace(tzinfo=UTC) - timedelta(seconds=offset)
+    ).date()
 
 
 def get_diff_sec(dt: datetime, offset: float = 0.0) -> int:
@@ -151,7 +187,10 @@ def delay(second: float = 0) -> None:  # pragma: no cov
 
     :param second: (float) A second number that want to adds-on random value.
     """
-    time.sleep(second + randrange(0, 99, step=10) / 100)
+    global _DELAY_INDEX
+    cached_random = _CACHED_DELAYS[_DELAY_INDEX % len(_CACHED_DELAYS)]
+    _DELAY_INDEX = (_DELAY_INDEX + 1) % len(_CACHED_DELAYS)
+    time.sleep(second + cached_random)
 
 
 def gen_id(
@@ -188,7 +227,7 @@ def gen_id(
     if not isinstance(value, str):
         value: str = str(value)
 
-    dt: datetime = datetime.now(tz=dynamic("tz", extras=extras))
+    dt: datetime = datetime.now(tz=UTC)
     if dynamic("generate_id_simple_mode", f=simple_mode, extras=extras):
         return (f"{dt:%Y%m%d%H%M%S%f}T" if unique else "") + hash_str(
             f"{(value if sensitive else value.lower())}", n=10