ddeutil-workflow 0.0.76__tar.gz → 0.0.78__tar.gz

{ddeutil_workflow-0.0.76 → ddeutil_workflow-0.0.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ddeutil-workflow
-Version: 0.0.76
+Version: 0.0.78
 Summary: Lightweight workflow orchestration with YAML template
 Author-email: ddeutils <korawich.anu@gmail.com>
 License: MIT
@@ -147,7 +147,6 @@ For comprehensive API documentation, examples, and best practices:
 - **[Full Documentation](https://ddeutils.github.io/ddeutil-workflow/)** - Complete user guide and API reference
 - **[Getting Started](https://ddeutils.github.io/ddeutil-workflow/getting-started/)** - Quick start guide
 - **[API Reference](https://ddeutils.github.io/ddeutil-workflow/api/workflow/)** - Detailed API documentation
-- **[Examples](https://ddeutils.github.io/ddeutil-workflow/examples/)** - Real-world usage examples
 
 ## 🎯 Usage
 

{ddeutil_workflow-0.0.76 → ddeutil_workflow-0.0.78}/README.md

@@ -105,7 +105,6 @@ For comprehensive API documentation, examples, and best practices:
 - **[Full Documentation](https://ddeutils.github.io/ddeutil-workflow/)** - Complete user guide and API reference
 - **[Getting Started](https://ddeutils.github.io/ddeutil-workflow/getting-started/)** - Quick start guide
 - **[API Reference](https://ddeutils.github.io/ddeutil-workflow/api/workflow/)** - Detailed API documentation
-- **[Examples](https://ddeutils.github.io/ddeutil-workflow/examples/)** - Real-world usage examples
 
 ## 🎯 Usage
 

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

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

{ddeutil_workflow-0.0.76 → ddeutil_workflow-0.0.78}/src/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,6 +65,10 @@ 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:
@@ -232,7 +236,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-0.0.76 → ddeutil_workflow-0.0.78}/src/ddeutil/workflow/conf.py

@@ -307,8 +307,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,25 +320,30 @@ class YamlParser:
         excluded: Optional[list[str]] = None,
         extras: Optional[DictData] = None,
         ignore_filename: Optional[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
         adds-on.
 
-        :param obj: (object | str) An object that want to validate matching
-            before return.
-        :param path: (Path) A config path object.
-        :param paths: (list[Path]) A list of config path object.
-        :param excluded: An included list of data key that want to filter from
-            data.
-        :param extras: (DictData) An extra parameter that use to override core
-            config values.
-        :param ignore_filename: (str) An ignore filename. Default is
+        Args:
+            obj: (object | str) An object that want to validate matching
+                before return.
+            path: (Path) A config path object.
+            paths: (list[Path]) A list of config path object.
+            excluded: An included list of data key that want to filter from
+                data.
+            extras: (DictData) An extra parameter that use to override core
+                config values.
+            ignore_filename: (str) An ignore filename. Default is
             ``.confignore`` filename.
+            tags: (list[str])
+                A list of tag that want to filter.
 
         :rtype: Iterator[tuple[str, DictData]]
         """
         excluded: list[str] = excluded or []
+        tags: list[str] = tags or []
         path: Path = dynamic("conf_path", f=path, extras=extras)
         paths: Optional[list[Path]] = paths or (extras or {}).get("conf_paths")
         if not paths:
@@ -366,7 +369,17 @@ class YamlParser:
                     if key in excluded:
                         continue
 
+                    if (
+                        tags
+                        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,
@@ -469,7 +482,10 @@ def pass_env(value: T) -> T:  # pragma: no cov
     if isinstance(value, dict):
         return {k: pass_env(value[k]) for k in value}
     elif isinstance(value, (list, tuple, set)):
-        return type(value)([pass_env(i) for i in value])
+        try:
+            return type(value)(pass_env(i) for i in value)
+        except TypeError:
+            return value
     if not isinstance(value, str):
         return value
 

{ddeutil_workflow-0.0.76 → ddeutil_workflow-0.0.78}/src/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-0.0.76 → ddeutil_workflow-0.0.78}/src/ddeutil/workflow/event.py

@@ -39,7 +39,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 +106,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 +124,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 +168,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 +211,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:
@@ -376,7 +360,10 @@ 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
 

{ddeutil_workflow-0.0.76 → ddeutil_workflow-0.0.78}/src/ddeutil/workflow/job.py

@@ -48,10 +48,11 @@ from enum import Enum
 from functools import lru_cache
 from textwrap import dedent
 from threading import Event
-from typing import Annotated, Any, Literal, Optional, Union
+from typing import Annotated, Any, Optional, Union
 
 from ddeutil.core import freeze_args
 from pydantic import BaseModel, Discriminator, Field, SecretStr, Tag
+from pydantic.functional_serializers import field_serializer
 from pydantic.functional_validators import field_validator, model_validator
 from typing_extensions import Self
 
@@ -263,24 +264,20 @@ class BaseRunsOn(BaseModel):  # pragma: no cov
     object and override execute method.
     """
 
-    type: RunsOn = Field(description="A runs-on type.")
+    type: RunsOn = LOCAL
     args: DictData = Field(
         default_factory=dict,
-        alias="with",
         description=(
             "An argument that pass to the runs-on execution function. This "
             "args will override by this child-model with specific args model."
         ),
+        alias="with",
     )
 
 
 class OnLocal(BaseRunsOn):  # pragma: no cov
     """Runs-on local."""
 
-    type: Literal[RunsOn.LOCAL] = Field(
-        default=RunsOn.LOCAL, validate_default=True
-    )
-
 
 class SelfHostedArgs(BaseModel):
     """Self-Hosted arguments."""
@@ -292,9 +289,7 @@ class SelfHostedArgs(BaseModel):
 class OnSelfHosted(BaseRunsOn):  # pragma: no cov
     """Runs-on self-hosted."""
 
-    type: Literal[RunsOn.SELF_HOSTED] = Field(
-        default=RunsOn.SELF_HOSTED, validate_default=True
-    )
+    type: RunsOn = SELF_HOSTED
     args: SelfHostedArgs = Field(alias="with")
 
 
@@ -310,9 +305,7 @@ class AzBatchArgs(BaseModel):
 
 class OnAzBatch(BaseRunsOn):  # pragma: no cov
 
-    type: Literal[RunsOn.AZ_BATCH] = Field(
-        default=RunsOn.AZ_BATCH, validate_default=True
-    )
+    type: RunsOn = AZ_BATCH
     args: AzBatchArgs = Field(alias="with")
 
 
@@ -331,23 +324,21 @@ class DockerArgs(BaseModel):
 class OnDocker(BaseRunsOn):  # pragma: no cov
     """Runs-on Docker container."""
 
-    type: Literal[RunsOn.DOCKER] = Field(
-        default=RunsOn.DOCKER, validate_default=True
-    )
-    args: DockerArgs = Field(alias="with", default_factory=DockerArgs)
+    type: RunsOn = DOCKER
+    args: DockerArgs = Field(default_factory=DockerArgs, alias="with")
 
 
 def get_discriminator_runs_on(model: dict[str, Any]) -> RunsOn:
     """Get discriminator of the RunsOn models."""
     t: str = model.get("type")
-    return RunsOn(t) if t else RunsOn.LOCAL
+    return RunsOn(t) if t else LOCAL
 
 
 RunsOnModel = Annotated[
     Union[
-        Annotated[OnSelfHosted, Tag(RunsOn.SELF_HOSTED)],
-        Annotated[OnDocker, Tag(RunsOn.DOCKER)],
-        Annotated[OnLocal, Tag(RunsOn.LOCAL)],
+        Annotated[OnSelfHosted, Tag(SELF_HOSTED)],
+        Annotated[OnDocker, Tag(DOCKER)],
+        Annotated[OnLocal, Tag(LOCAL)],
     ],
     Discriminator(get_discriminator_runs_on),
 ]
@@ -490,6 +481,10 @@ class Job(BaseModel):
 
         return self
 
+    @field_serializer("runs_on")
+    def __serialize_runs_on(self, value: RunsOnModel):
+        return value.model_dump(by_alias=True)
+
     def stage(self, stage_id: str) -> Stage:
         """Return stage instance that exists in this job via passing an input
         stage ID.

{ddeutil_workflow-0.0.76 → ddeutil_workflow-0.0.78}/src/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
 
@@ -42,7 +41,7 @@ from . import (
 from .__types import DictData
 from .audits import Trace, 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,13 @@ 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)
 
     @model_validator(mode="after")
     def __prepare_trace(self) -> Self:
@@ -207,20 +202,18 @@ class Result:
                 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: Trace):
+        """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 +230,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 +259,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 +266,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 +285,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-0.0.76 → ddeutil_workflow-0.0.78}/src/ddeutil/workflow/reusables.py

@@ -421,12 +421,13 @@ def param2template(
             for k in value
         }
     elif isinstance(value, (list, tuple, set)):
-        return type(value)(
-            [
+        try:
+            return type(value)(
                 param2template(i, params, context, filters, extras=extras)
                 for i in value
-            ]
-        )
+            )
+        except TypeError:
+            return value
     elif not isinstance(value, str):
         return value
     return str2template(
@@ -598,7 +599,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
 
@@ -616,6 +617,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