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

ddeutil/workflow/cli.py

@@ -57,7 +57,7 @@ def init() -> None:
         wf-example:
           type: Workflow
           desc: |
-            An example workflow template.
+            An example workflow template that provide the demo of workflow.
           params:
             name:
                 type: str
@@ -65,10 +65,18 @@ def init() -> None:
           jobs:
             first-job:
               stages:
+
+                - name: "Hello Stage"
+                  echo: "Start say hi to the console"
+
                 - name: "Call tasks"
                   uses: tasks/say-hello-func@example
                   with:
                     name: ${{ params.name }}
+            second-job:
+
+                - name: "Hello Env"
+                  echo: "Start say hi with ${ WORKFLOW_DEMO_HELLO }"
         """
         ).lstrip("\n")
     )
@@ -94,8 +102,22 @@ def init() -> None:
 
         init_path = task_path / "__init__.py"
         init_path.write_text("from .example import hello_world_task\n")
+
+    dotenv_file = Path(".env")
+    mode: str = "a" if dotenv_file.exists() else "w"
+    with dotenv_file.open(mode=mode) as f:
+        f.write("\n# Workflow env vars\n")
+        f.write(
+            "WORKFLOW_DEMO_HELLO=foo\n"
+            "WORKFLOW_CORE_DEBUG_MODE=true\n"
+            "WORKFLOW_LOG_TIMEZONE=Asia/Bangkok\n"
+            "WORKFLOW_LOG_TRACE_ENABLE_WRITE=false\n"
+            "WORKFLOW_LOG_AUDIT_ENABLE_WRITE=true\n"
+        )
+
+    typer.echo("Starter command:")
     typer.echo(
-        "Starter command: `workflow-cli workflows execute --name=wf-example`"
+        "> `source .env && workflow-cli workflows execute --name=wf-example`"
     )
 
 
@@ -232,7 +254,7 @@ def workflow_json_schema(
     json_schema = TypeAdapter(template).json_schema(by_alias=True)
     template_schema: dict[str, str] = {
         "$schema": "http://json-schema.org/draft-07/schema#",
-        "title": "Workflow Configuration Schema",
+        "title": "Workflow Configuration JSON Schema",
         "version": __version__,
     }
     with open(output, mode="w", encoding="utf-8") as f:

ddeutil/workflow/conf.py

@@ -40,12 +40,12 @@ Note:
     ${VAR_NAME} syntax and provide extensive validation capabilities.
 """
 import copy
+import json
 import os
 from collections.abc import Iterator
 from functools import cached_property
 from pathlib import Path
-from typing import Final, Optional, TypeVar, Union
-from urllib.parse import ParseResult, urlparse
+from typing import Any, Final, Optional, TypeVar, Union
 from zoneinfo import ZoneInfo
 
 from ddeutil.core import str2bool
@@ -122,8 +122,8 @@ class Config:  # pragma: no cov
         return [r.strip() for r in regis_filter_str.split(",")]
 
     @property
-    def trace_url(self) -> ParseResult:
-        return urlparse(env("LOG_TRACE_URL", "file:./logs"))
+    def trace_handlers(self) -> list[dict[str, Any]]:
+        return json.loads(env("LOG_TRACE_HANDLERS", '[{"type": "console"}]'))
 
     @property
     def debug(self) -> bool:
@@ -155,22 +155,8 @@ class Config:  # pragma: no cov
         )
 
     @property
-    def log_format_file(self) -> str:
-        return env(
-            "LOG_FORMAT_FILE",
-            (
-                "{datetime} ({process:5d}, {thread:5d}) ({cut_id}) "
-                "{message:120s} ({filename}:{lineno})"
-            ),
-        )
-
-    @property
-    def enable_write_log(self) -> bool:
-        return str2bool(env("LOG_TRACE_ENABLE_WRITE", "false"))
-
-    @property
-    def audit_url(self) -> ParseResult:
-        return urlparse(env("LOG_AUDIT_URL", "file:./audits"))
+    def audit_url(self) -> str:
+        return env("LOG_AUDIT_URL", "file:./audits")
 
     @property
     def enable_write_audit(self) -> bool:
@@ -307,8 +293,6 @@ class YamlParser:
                         all_data.append((file_stat.st_mtime, data))
                     elif (t := data.get("type")) and t == obj_type:
                         all_data.append((file_stat.st_mtime, data))
-                    else:
-                        continue
 
         return {} if not all_data else max(all_data, key=lambda x: x[0])[1]
 
@@ -322,7 +306,7 @@ class YamlParser:
         excluded: Optional[list[str]] = None,
         extras: Optional[DictData] = None,
         ignore_filename: Optional[str] = None,
-        tags: Optional[list[str]] = None,
+        tags: Optional[list[Union[str, int]]] = None,
     ) -> Iterator[tuple[str, DictData]]:
         """Find all data that match with object type in config path. This class
         method can use include and exclude list of identity name for filter and
@@ -373,13 +357,15 @@ class YamlParser:
 
                     if (
                         tags
-                        and (ts := data[key].get("tags"))
-                        and isinstance(ts, list)
-                        and all(t not in tags for t in ts)
-                    ):  # pragma: no cov
+                        and isinstance((ts := data.get("tags", [])), list)
+                        and any(t not in ts for t in tags)
+                    ):
                         continue
 
                     if (t := data.get("type")) and t == obj_type:
+                        file_stat: os.stat_result = file.lstat()
+                        data["created_at"] = file_stat.st_ctime
+                        data["updated_at"] = file_stat.st_mtime
                         marking: tuple[float, DictData] = (
                             file.lstat().st_mtime,
                             data,
@@ -464,7 +450,9 @@ def dynamic(
     conf: Optional[T] = getattr(config, key, None) if f is None else f
     if extra is None:
         return conf
-    if not isinstance(extra, type(conf)):
+    # NOTE: Fix type checking for boolean value and int type like
+    #   `isinstance(False, int)` which return True.
+    if type(extra) is not type(conf):
         raise TypeError(
             f"Type of config {key!r} from extras: {extra!r} does not valid "
             f"as config {type(conf)}."

ddeutil/workflow/errors.py

@@ -56,13 +56,13 @@ def to_dict(exception: Exception, **kwargs) -> ErrorData:  # pragma: no cov
         ErrorData: Dictionary containing exception name and message
 
     Example:
-        ```python
-        try:
-            raise ValueError("Something went wrong")
-        except Exception as e:
-            error_data = to_dict(e, context="workflow_execution")
-            # Returns: {"name": "ValueError", "message": "Something went wrong", "context": "workflow_execution"}
-        ```
+        >>> try:
+        >>>     raise ValueError("Something went wrong")
+        >>> except Exception as e:
+        >>>     error_data = to_dict(e, context="workflow_execution")
+        >>>     # Returns: {
+        >>>     #   "name": "ValueError", "message": "Something went wrong", "context": "workflow_execution"
+        >>>     # }
     """
     return {
         "name": exception.__class__.__name__,
@@ -85,14 +85,12 @@ class BaseError(Exception):
         params: Parameter data that was being processed when error occurred
 
     Example:
-        ```python
-        try:
-            # Some workflow operation
-            pass
-        except BaseError as e:
-            error_dict = e.to_dict(with_refs=True)
-            print(f"Error in {e.refs}: {error_dict}")
-        ```
+        >>> try:
+        >>>     # NOTE: Some workflow operation
+        >>>     pass
+        >>> except BaseError as e:
+        >>>     error_dict = e.to_dict(with_refs=True)
+        >>>     print(f\"Error in {e.refs}: {error_dict}\")
     """
 
     def __init__(

ddeutil/workflow/event.py

@@ -19,6 +19,9 @@ Classes:
     Crontab: Main cron-based event scheduler.
     CrontabYear: Enhanced cron scheduler with year constraints.
     ReleaseEvent: Release-based event triggers.
+    FileEvent: File system monitoring triggers.
+    WebhookEvent: API/webhook-based triggers.
+    DatabaseEvent: Database change monitoring triggers.
     SensorEvent: Sensor-based event monitoring.
 
 Example:
@@ -39,7 +42,6 @@ from __future__ import annotations
 from dataclasses import fields
 from datetime import datetime
 from typing import Annotated, Any, Literal, Optional, Union
-from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 from pydantic import BaseModel, ConfigDict, Field, ValidationInfo
 from pydantic.functional_serializers import field_serializer
@@ -107,7 +109,7 @@ class BaseCrontab(BaseModel):
     )
     tz: TimeZoneName = Field(
         default="UTC",
-        description="A timezone string value.",
+        description="A timezone string value that will pass to ZoneInfo.",
         alias="timezone",
     )
 
@@ -125,38 +127,25 @@ class BaseCrontab(BaseModel):
             data["timezone"] = tz
         return data
 
-    @field_validator("tz")
-    def __validate_tz(cls, value: str) -> str:
-        """Validate timezone value.
-
-        Args:
-            value: Timezone string to validate.
-
-        Returns:
-            Validated timezone string.
-
-        Raises:
-            ValueError: If timezone is invalid.
-        """
-        try:
-            _ = ZoneInfo(value)
-            return value
-        except ZoneInfoNotFoundError as e:
-            raise ValueError(f"Invalid timezone: {value}") from e
-
 
 class CrontabValue(BaseCrontab):
     """Crontab model using interval-based specification.
 
     Attributes:
-        interval: Scheduling interval ('daily', 'weekly', 'monthly').
-        day: Day specification for weekly/monthly schedules.
+        interval: (Interval)
+            A scheduling interval string ('daily', 'weekly', 'monthly').
+        day: (str, default None)
+            Day specification for weekly/monthly schedules.
         time: Time of day in 'HH:MM' format.
     """
 
-    interval: Interval
+    interval: Interval = Field(description="A scheduling interval string.")
     day: Optional[str] = Field(default=None)
-    time: str = Field(default="00:00")
+    time: str = Field(
+        default="00:00",
+        pattern=r"\d{2}:\d{2}",
+        description="A time of day that pass with format 'HH:MM'.",
+    )
 
     @property
     def cronjob(self) -> CronJob:
@@ -182,10 +171,13 @@ class CrontabValue(BaseCrontab):
             TypeError: If start parameter is neither string nor datetime.
         """
         if isinstance(start, str):
-            start: datetime = datetime.fromisoformat(start)
-        elif not isinstance(start, datetime):
-            raise TypeError("start value should be str or datetime type.")
-        return self.cronjob.schedule(date=start, tz=self.tz)
+            return self.cronjob.schedule(
+                date=datetime.fromisoformat(start), tz=self.tz
+            )
+
+        if isinstance(start, datetime):
+            return self.cronjob.schedule(date=start, tz=self.tz)
+        raise TypeError("start value should be str or datetime type.")
 
     def next(self, start: Union[str, datetime]) -> CronRunner:
         """Get next scheduled datetime after given start time.
@@ -222,11 +214,6 @@ class Crontab(BaseCrontab):
             "A Cronjob object that use for validate and generate datetime."
         ),
     )
-    tz: TimeZoneName = Field(
-        default="UTC",
-        description="A timezone string value.",
-        alias="timezone",
-    )
 
     @model_validator(mode="before")
     def __prepare_values(cls, data: Any) -> Any:
@@ -328,11 +315,9 @@ class CrontabYear(Crontab):
         cronjob: CronJobYear instance for year-aware schedule validation and generation.
     """
 
-    cronjob: CronJobYear = (
-        Field(
-            description=(
-                "A Cronjob object that use for validate and generate datetime."
-            ),
+    cronjob: CronJobYear = Field(
+        description=(
+            "A Cronjob object that use for validate and generate datetime."
         ),
     )
 
@@ -376,13 +361,24 @@ Cron = Annotated[
     ],
     Field(
         union_mode="smart",
-        description="Event model type supporting year-based, standard, and interval-based cron scheduling.",
+        description=(
+            "Event model type supporting year-based, standard, and "
+            "interval-based cron scheduling."
+        ),
     ),
 ]  # pragma: no cov
 
 
 class Event(BaseModel):
-    """Event model."""
+    """Event model with comprehensive trigger support.
+
+    Supports multiple types of event triggers including cron scheduling,
+    file monitoring, webhooks, database changes, sensor-based triggers,
+    polling-based triggers, message queue events, stream processing events,
+    batch processing events, data quality events, API rate limiting events,
+    data lineage events, ML pipeline events, data catalog events,
+    infrastructure events, compliance events, and business events.
+    """
 
     schedule: list[Cron] = Field(
         default_factory=list,