ddeutil-workflow 0.0.72__py3-none-any.whl → 0.0.74__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,9 +99,11 @@ 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)
 
@@ -87,6 +125,17 @@ def get_dt_now(tz: Optional[ZoneInfo] = None, offset: float = 0.0) -> datetime:
     return datetime.now(tz=tz) - timedelta(seconds=offset)
 
 
+def get_dt_ntz_now() -> datetime:  # pragma: no cov
+    """Get current datetime with no timezone.
+
+    Returns the current datetime object using the None timezone.
+
+    Returns:
+        datetime: Current datetime with no timezone
+    """
+    return get_dt_now(tz=None)
+
+
 def get_d_now(
     tz: Optional[ZoneInfo] = None, offset: float = 0.0
 ) -> date:  # pragma: no cov
@@ -151,7 +200,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(