ddeutil-workflow 0.0.82__tar.gz → 0.0.83__tar.gz

{ddeutil_workflow-0.0.82 → ddeutil_workflow-0.0.83}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ddeutil-workflow
-Version: 0.0.82
+Version: 0.0.83
 Summary: Lightweight workflow orchestration with YAML template
 Author-email: ddeutils <korawich.anu@gmail.com>
 License: MIT

{ddeutil_workflow-0.0.82 → ddeutil_workflow-0.0.83}/src/ddeutil/workflow/__about__.py

@@ -1,2 +1,2 @@
-__version__: str = "0.0.82"
+__version__: str = "0.0.83"
 __python_version__: str = "3.9"

{ddeutil_workflow-0.0.82 → ddeutil_workflow-0.0.83}/src/ddeutil/workflow/__cron.py

@@ -715,7 +715,7 @@ class CronJob:
         self,
         date: Optional[datetime] = None,
         *,
-        tz: Optional[str] = None,
+        tz: Optional[Union[str, ZoneInfo]] = None,
     ) -> CronRunner:
         """Returns CronRunner instance that be datetime runner with this
         cronjob. It can use `next`, `prev`, or `reset` methods to generate

{ddeutil_workflow-0.0.82 → ddeutil_workflow-0.0.83}/src/ddeutil/workflow/__init__.py

@@ -50,12 +50,12 @@ Note:
 from .__cron import CronRunner
 from .__types import DictData, DictStr, Matrix, Re, TupleStr
 from .audits import (
-    EVENT,
+    DRYRUN,
     FORCE,
     NORMAL,
     RERUN,
     Audit,
-    FileAudit,
+    LocalFileAudit,
     get_audit,
 )
 from .conf import (
@@ -71,6 +71,7 @@ from .conf import (
 )
 from .errors import (
     BaseError,
+    EventError,
     JobCancelError,
     JobError,
     JobSkipError,

{ddeutil_workflow-0.0.82 → ddeutil_workflow-0.0.83}/src/ddeutil/workflow/__types.py

@@ -16,17 +16,26 @@ from re import (
     Match,
     Pattern,
 )
-from typing import Any, Optional, TypedDict, Union
+from typing import Any, Optional, TypedDict, Union, cast
 
 from typing_extensions import Self
 
 StrOrNone = Optional[str]
 StrOrInt = Union[str, int]
 TupleStr = tuple[str, ...]
+ListStr = list[str]
+ListInt = list[int]
 DictData = dict[str, Any]
+DictRange = dict[int, Any]
 DictStr = dict[str, str]
 Matrix = dict[str, Union[list[str], list[int]]]
 
+
+def cast_dict(value: TypedDict[...]) -> DictData:
+    """Cast any TypedDict object to DictData type."""
+    return cast(DictData, value)
+
+
 # Pre-compile regex patterns for better performance
 _RE_CALLER_PATTERN = r"""
     \$                                                      # start with $

{ddeutil_workflow-0.0.82 → ddeutil_workflow-0.0.83}/src/ddeutil/workflow/audits.py

@@ -74,31 +74,38 @@ class ReleaseType(str, Enum):
     Attributes:
         NORMAL: Standard workflow release execution
         RERUN: Re-execution of previously failed workflow
-        EVENT: Event-triggered workflow execution
+        DRYRUN: Dry-execution workflow
         FORCE: Forced execution bypassing normal conditions
     """
 
     NORMAL = "normal"
     RERUN = "rerun"
-    EVENT = "event"
     FORCE = "force"
+    DRYRUN = "dryrun"
 
 
 NORMAL = ReleaseType.NORMAL
 RERUN = ReleaseType.RERUN
-EVENT = ReleaseType.EVENT
+DRYRUN = ReleaseType.DRYRUN
 FORCE = ReleaseType.FORCE
 
 
 class AuditData(BaseModel):
-    """Audit Data model."""
+    """Audit Data model that use to be the core data for any Audit model manage
+    logging at the target pointer system or service like file-system, sqlite
+    database, etc.
+    """
 
     model_config = ConfigDict(use_enum_values=True)
 
     name: str = Field(description="A workflow name.")
     release: datetime = Field(description="A release datetime.")
     type: ReleaseType = Field(
-        default=NORMAL, description="A running type before logging."
+        default=NORMAL,
+        description=(
+            "An execution type that should be value in ('normal', 'rerun', "
+            "'force', 'dryrun')."
+        ),
     )
     context: DictData = Field(
         default_factory=dict,
@@ -121,18 +128,17 @@ class BaseAudit(BaseModel, ABC):
     for logging subclasses like file, sqlite, etc.
     """
 
-    type: str
+    type: Literal["base"] = "base"
+    logging_name: str = "ddeutil.workflow"
     extras: DictData = Field(
         default_factory=dict,
         description="An extras parameter that want to override core config",
     )
 
     @field_validator("extras", mode="before")
-    def validate_extras(cls, v: Any) -> DictData:
+    def __prepare_extras(cls, v: Any) -> Any:
         """Validate extras field to ensure it's a dictionary."""
-        if v is None:
-            return {}
-        return v
+        return {} if v is None else v
 
     @model_validator(mode="after")
     def __model_action(self) -> Self:
@@ -148,7 +154,7 @@ class BaseAudit(BaseModel, ABC):
             self.do_before()
 
         # NOTE: Start setting log config in this line with cache.
-        set_logging("ddeutil.workflow")
+        set_logging(self.logging_name)
         return self
 
     @abstractmethod
@@ -248,7 +254,7 @@ class BaseAudit(BaseModel, ABC):
         raise NotImplementedError("Audit should implement `save` method.")
 
 
-class FileAudit(BaseAudit):
+class LocalFileAudit(BaseAudit):
     """File Audit Pydantic Model for saving log data from workflow execution.
 
     This class inherits from BaseAudit and implements file-based storage
@@ -256,19 +262,25 @@ class FileAudit(BaseAudit):
     in a structured directory hierarchy.
 
     Attributes:
-        filename_fmt: Class variable defining the filename format for audit files.
+        file_fmt: Class variable defining the filename format for audit log.
+        file_release_fmt: Class variable defining the filename format for audit
+            release log.
     """
 
-    filename_fmt: ClassVar[str] = (
-        "workflow={name}/release={release:%Y%m%d%H%M%S}"
-    )
+    file_fmt: ClassVar[str] = "workflow={name}"
+    file_release_fmt: ClassVar[str] = "release={release:%Y%m%d%H%M%S}"
 
     type: Literal["file"] = "file"
-    path: str = Field(
-        default="./audits",
+    path: Path = Field(
+        default=Path("./audits"),
         description="A file path that use to manage audit logs.",
     )
 
+    @field_validator("path", mode="before", json_schema_input_type=str)
+    def __prepare_path(cls, data: Any) -> Any:
+        """Prepare path that passing with string to Path instance."""
+        return Path(data) if isinstance(data, str) else data
+
     def do_before(self) -> None:
         """Create directory of release before saving log file.
 
@@ -278,7 +290,10 @@ class FileAudit(BaseAudit):
         Path(self.path).mkdir(parents=True, exist_ok=True)
 
     def find_audits(
-        self, name: str, *, extras: Optional[DictData] = None
+        self,
+        name: str,
+        *,
+        extras: Optional[DictData] = None,
     ) -> Iterator[AuditData]:
         """Generate audit data found from logs path for a specific workflow name.
 
@@ -292,7 +307,7 @@ class FileAudit(BaseAudit):
         Raises:
             FileNotFoundError: If the workflow directory does not exist.
         """
-        pointer: Path = Path(self.path) / f"workflow={name}"
+        pointer: Path = self.path / self.file_fmt.format(name=name)
         if not pointer.exists():
             raise FileNotFoundError(f"Pointer: {pointer.absolute()}.")
 
@@ -325,7 +340,7 @@ class FileAudit(BaseAudit):
             ValueError: If no releases found when release is None.
         """
         if release is None:
-            pointer: Path = Path(self.path) / f"workflow={name}"
+            pointer: Path = self.path / self.file_fmt.format(name=name)
             if not pointer.exists():
                 raise FileNotFoundError(f"Pointer: {pointer.absolute()}.")
 
@@ -382,8 +397,10 @@ class FileAudit(BaseAudit):
         Returns:
             Path: The directory path for the current workflow and release.
         """
-        return Path(self.path) / self.filename_fmt.format(
-            name=data.name, release=data.release
+        return (
+            self.path
+            / self.file_fmt.format(**data.model_dump(by_alias=True))
+            / self.file_release_fmt.format(**data.model_dump(by_alias=True))
         )
 
     def save(self, data: Any, excluded: Optional[list[str]] = None) -> Self:
@@ -459,7 +476,7 @@ class FileAudit(BaseAudit):
         return cleaned_count
 
 
-class SQLiteAudit(BaseAudit):  # pragma: no cov
+class LocalSQLiteAudit(BaseAudit):  # pragma: no cov
     """SQLite Audit model for database-based audit storage.
 
     This class inherits from BaseAudit and implements SQLite database storage
@@ -467,11 +484,11 @@ class SQLiteAudit(BaseAudit):  # pragma: no cov
 
     Attributes:
         table_name: Class variable defining the database table name.
-        schemas: Class variable defining the database schema.
+        ddl: Class variable defining the database schema.
     """
 
     table_name: ClassVar[str] = "audits"
-    schemas: ClassVar[
+    ddl: ClassVar[
         str
     ] = """
         CREATE TABLE IF NOT EXISTS audits (
@@ -489,22 +506,21 @@ class SQLiteAudit(BaseAudit):  # pragma: no cov
         """
 
     type: Literal["sqlite"] = "sqlite"
-    path: str
+    path: Path = Field(
+        default=Path("./audits.db"),
+        description="A SQLite filepath.",
+    )
 
-    def _ensure_table_exists(self) -> None:
+    def do_before(self) -> None:
         """Ensure the audit table exists in the database."""
-        audit_url = dynamic("audit_url", extras=self.extras)
-        if audit_url is None or not audit_url.path:
+        if self.path.is_dir():
             raise ValueError(
-                "SQLite audit_url must specify a database file path"
+                "SQLite path must specify a database file path not dir."
             )
 
-        audit_url_parse: ParseResult = urlparse(audit_url)
-        db_path = Path(audit_url_parse.path)
-        db_path.parent.mkdir(parents=True, exist_ok=True)
-
-        with sqlite3.connect(db_path) as conn:
-            conn.execute(self.schemas)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with sqlite3.connect(self.path) as conn:
+            conn.execute(self.ddl)
             conn.commit()
 
     def is_pointed(
@@ -771,24 +787,31 @@ class SQLiteAudit(BaseAudit):  # pragma: no cov
             return cursor.rowcount
 
 
+class PostgresAudit(BaseAudit, ABC): ...  # pragma: no cov
+
+
 Audit = Annotated[
     Union[
-        FileAudit,
-        SQLiteAudit,
+        LocalFileAudit,
+        LocalSQLiteAudit,
     ],
     Field(discriminator="type"),
 ]
 
 
-def get_audit(extras: Optional[DictData] = None) -> Audit:  # pragma: no cov
+def get_audit(
+    audit_conf: Optional[DictData] = None,
+    extras: Optional[DictData] = None,
+) -> Audit:  # pragma: no cov
     """Get an audit model dynamically based on the config audit path value.
 
     Args:
+        audit_conf (DictData):
         extras: Optional extra parameters to override the core config.
 
     Returns:
         Audit: The appropriate audit model class based on configuration.
     """
-    audit_conf = dynamic("audit_conf", extras=extras)
+    audit_conf = dynamic("audit_conf", f=audit_conf, extras=extras)
     model = TypeAdapter(Audit).validate_python(audit_conf | {"extras": extras})
     return model

{ddeutil_workflow-0.0.82 → ddeutil_workflow-0.0.83}/src/ddeutil/workflow/errors.py

@@ -184,6 +184,9 @@ class JobCancelError(JobError): ...
 class JobSkipError(JobError): ...
 
 
+class EventError(BaseError): ...
+
+
 class WorkflowError(BaseError): ...
 
 

{ddeutil_workflow-0.0.82 → ddeutil_workflow-0.0.83}/src/ddeutil/workflow/event.py

@@ -16,13 +16,9 @@ Attributes:
     Interval: Type alias for scheduling intervals ('daily', 'weekly', 'monthly')
 
 Classes:
+    CrontabValue:
     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:
     >>> from ddeutil.workflow.event import Crontab
@@ -50,6 +46,8 @@ from pydantic_extra_types.timezone_name import TimeZoneName
 
 from .__cron import WEEKDAYS, CronJob, CronJobYear, CronRunner, Options
 from .__types import DictData
+from .errors import EventError
+from .utils import UTC, replace_sec
 
 Interval = Literal["daily", "weekly", "monthly"]
 
@@ -393,19 +391,16 @@ class Event(BaseModel):
     )
 
     @field_validator("schedule", mode="after")
-    def __on_no_dup_and_reach_limit__(
-        cls,
-        value: list[Crontab],
-    ) -> list[Crontab]:
+    def __prepare_schedule__(cls, value: list[Crontab]) -> list[Crontab]:
         """Validate the on fields should not contain duplicate values and if it
         contains the every minute value more than one value, it will remove to
         only one value.
 
         Args:
-            value: A list of on object.
+            value (list[Crontab]): A list of on object.
 
         Returns:
-            list[CronJobYear | Crontab]: The validated list of Crontab objects.
+            list[Crontab]: The validated list of Crontab objects.
 
         Raises:
             ValueError: If it has some duplicate value.
@@ -434,3 +429,31 @@ class Event(BaseModel):
                 "The number of the on should not more than 10 crontabs."
             )
         return value
+
+    def validate_dt(self, dt: datetime) -> datetime:
+        """Validate the release datetime that should was replaced second and
+        millisecond to 0 and replaced timezone to None before checking it match
+        with the set `on` field.
+
+        Args:
+            dt (datetime): A datetime object that want to validate.
+
+        Returns:
+            datetime: The validated release datetime.
+        """
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=UTC)
+
+        release: datetime = replace_sec(dt.astimezone(UTC))
+
+        # NOTE: Return itself if schedule event does not set.
+        if not self.schedule:
+            return release
+
+        for on in self.schedule:
+            if release == on.cronjob.schedule(release, tz=UTC).next:
+                return release
+        raise EventError(
+            f"This datetime, {datetime}, does not support for this event "
+            f"schedule."
+        )

{ddeutil_workflow-0.0.82 → ddeutil_workflow-0.0.83}/src/ddeutil/workflow/job.py

@@ -73,7 +73,7 @@ from .result import (
 from .reusables import has_template, param2template
 from .stages import Stage
 from .traces import Trace, get_trace
-from .utils import cross_product, filter_func, gen_id
+from .utils import cross_product, extract_id, filter_func, gen_id
 
 MatrixFilter = list[dict[str, Union[str, int]]]
 
@@ -890,8 +890,9 @@ class Job(BaseModel):
             Result: Return Result object that create from execution context.
         """
         ts: float = time.monotonic()
-        parent_run_id: str = run_id
-        run_id: str = gen_id((self.id or "EMPTY"), unique=True)
+        parent_run_id, run_id = extract_id(
+            (self.id or "EMPTY"), run_id=run_id, extras=self.extras
+        )
         trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
@@ -1272,7 +1273,6 @@ def local_execute(
 
         errors: DictData = {}
         statuses: list[Status] = [WAIT] * len_strategy
-        fail_fast: bool = False
 
         if not job.strategy.fail_fast:
             done: Iterator[Future] = as_completed(futures)
@@ -1297,7 +1297,6 @@ def local_execute(
                 )
                 trace.debug(f"[JOB]: ... Job was set Fail-Fast{nd}")
                 done: Iterator[Future] = as_completed(futures)
-                fail_fast: bool = True
 
         for i, future in enumerate(done, start=0):
             try:
@@ -1312,19 +1311,10 @@ def local_execute(
                 pass
 
     status: Status = validate_statuses(statuses)
-
-    # NOTE: Prepare status because it does not cancel from parent event but
-    #   cancel from failed item execution.
-    if fail_fast and status == CANCEL:
-        status = FAILED
-
-    return Result(
-        run_id=run_id,
-        parent_run_id=parent_run_id,
+    return Result.from_trace(trace).catch(
         status=status,
         context=catch(context, status=status, updated=errors),
         info={"execution_time": time.monotonic() - ts},
-        extras=job.extras,
     )
 
 

{ddeutil_workflow-0.0.82 → ddeutil_workflow-0.0.83}/src/ddeutil/workflow/result.py

@@ -8,20 +8,12 @@
 This module provides the core result and status management functionality for
 workflow execution tracking. It includes the Status enumeration for execution
 states and the Result dataclass for context transfer between workflow components.
-
-Classes:
-    Status: Enumeration for execution status tracking
-    Result: Dataclass for execution context and result management
-
-Functions:
-    validate_statuses: Determine final status from multiple status values
-    get_status_from_error: Convert exception types to appropriate status
 """
 from __future__ import annotations
 
 from dataclasses import field
 from enum import Enum
-from typing import Optional, TypedDict, Union
+from typing import Any, Optional, TypedDict, Union
 
 from pydantic import ConfigDict
 from pydantic.dataclasses import dataclass
@@ -126,10 +118,10 @@ def validate_statuses(statuses: list[Status]) -> Status:
         >>> validate_statuses([SUCCESS, SUCCESS, SUCCESS])
         >>> # Returns: SUCCESS
     """
-    if any(s == CANCEL for s in statuses):
-        return CANCEL
-    elif any(s == FAILED for s in statuses):
+    if any(s == FAILED for s in statuses):
         return FAILED
+    elif any(s == CANCEL for s in statuses):
+        return CANCEL
     elif any(s == WAIT for s in statuses):
         return WAIT
     for status in (SUCCESS, SKIP):
@@ -313,3 +305,40 @@ class Context(TypedDict):
     context: NotRequired[DictData]
     errors: NotRequired[Union[list[ErrorData], ErrorData]]
     info: NotRequired[DictData]
+
+
+class Layer(str, Enum):
+    WORKFLOW = "workflow"
+    JOB = "job"
+    STRATEGY = "strategy"
+    STAGE = "stage"
+
+
+def get_context_by_layer(
+    context: DictData,
+    key: str,
+    layer: Layer,
+    context_key: str,
+    *,
+    default: Optional[Any] = None,
+) -> Any:  # pragma: no cov
+    if layer == Layer.WORKFLOW:
+        return context.get("jobs", {}).get(key, {}).get(context_key, default)
+    elif layer == Layer.JOB:
+        return context.get("stages", {}).get(key, {}).get(context_key, default)
+    elif layer == Layer.STRATEGY:
+        return (
+            context.get("strategies", {}).get(key, {}).get(context_key, default)
+        )
+    return context.get(key, {}).get(context_key, default)
+
+
+def get_status(
+    context: DictData,
+    key: str,
+    layer: Layer,
+) -> Status:  # pragma: no cov
+    """Get status from context by a specific key and context layer."""
+    return get_context_by_layer(
+        context, key, layer, context_key="status", default=WAIT
+    )