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

ddeutil/workflow/event.py

@@ -3,10 +3,36 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-"""An Event module keep all triggerable object to the Workflow model. The simple
-event trigger that use to run workflow is `Crontab` model.
-Now, it has only `Crontab` and `CrontabYear` event models in this module because
-I think it is the core event for workflow orchestration.
+"""Event Scheduling Module for Workflow Orchestration.
+
+This module provides event-driven scheduling capabilities for workflows, with
+a primary focus on cron-based scheduling. It includes models for defining
+when workflows should be triggered and executed.
+
+The core event trigger is the Crontab model, which wraps cron functionality
+in a Pydantic model for validation and easy integration with the workflow system.
+
+Attributes:
+    Interval: Type alias for scheduling intervals ('daily', 'weekly', 'monthly')
+
+Classes:
+    Crontab: Main cron-based event scheduler.
+    CrontabYear: Enhanced cron scheduler with year constraints.
+    ReleaseEvent: Release-based event triggers.
+    SensorEvent: Sensor-based event monitoring.
+
+Example:
+    >>> from ddeutil.workflow.event import Crontab
+    >>> # NOTE: Create daily schedule at 9 AM
+    >>> schedule = Crontab.model_validate(
+    ...     {
+    ...         "cronjob": "0 9 * * *",
+    ...         "timezone": "America/New_York",
+    ...     }
+    ... )
+    >>> # NOTE: Generate next run times
+    >>> runner = schedule.generate(datetime.now())
+    >>> next_run = runner.next
 """
 from __future__ import annotations
 
@@ -19,11 +45,9 @@ from pydantic import BaseModel, ConfigDict, Field, ValidationInfo
 from pydantic.functional_serializers import field_serializer
 from pydantic.functional_validators import field_validator, model_validator
 from pydantic_extra_types.timezone_name import TimeZoneName
-from typing_extensions import Self
 
 from .__cron import WEEKDAYS, CronJob, CronJobYear, CronRunner, Options
-from .__types import DictData, DictStr
-from .conf import YamlParser
+from .__types import DictData
 
 Interval = Literal["daily", "weekly", "monthly"]
 
@@ -34,13 +58,16 @@ def interval2crontab(
     day: Optional[str] = None,
     time: str = "00:00",
 ) -> str:
-    """Return the crontab string that was generated from specific values.
+    """Convert interval specification to cron expression.
 
-    :param interval: An interval value that is one of 'daily', 'weekly', or
-        'monthly'.
-    :param day: A day value that will be day of week. The default value is
-        monday if it is weekly interval.
-    :param time: A time value that passing with format '%H:%M'.
+    Args:
+        interval: Scheduling interval ('daily', 'weekly', or 'monthly').
+        day: Day of week for weekly intervals or monthly schedules. Defaults to
+            Monday for weekly intervals.
+        time: Time of day in 'HH:MM' format. Defaults to '00:00'.
+
+    Returns:
+        Generated crontab expression string.
 
     Examples:
         >>> interval2crontab(interval='daily', time='01:30')
@@ -51,8 +78,6 @@ def interval2crontab(
         '0 0 1 * *'
         >>> interval2crontab(interval='monthly', day='tuesday', time='12:00')
         '12 0 1 * 2'
-
-    :rtype: str
     """
     d: str = "*"
     if interval == "weekly":
@@ -66,119 +91,35 @@ def interval2crontab(
     return f"{h} {m} {'1' if interval == 'monthly' else '*'} * {d}"
 
 
-class Crontab(BaseModel):
-    """Cron event model (Warped the CronJob object by Pydantic model) to keep
-    crontab value and generate CronRunner object from this crontab value.
+class BaseCrontab(BaseModel):
+    """Base class for crontab-based scheduling models.
 
-    Methods:
-        - generate: is the main use-case of this schedule object.
+    Attributes:
+        extras: Additional parameters to pass to the CronJob field.
+        tz: Timezone string value (alias: timezone).
     """
 
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    extras: Annotated[
-        DictData,
-        Field(
-            default_factory=dict,
-            description=(
-                "An extras parameters that want to pass to the CronJob field."
-            ),
-        ),
-    ]
-    cronjob: Annotated[
-        CronJob,
-        Field(
-            description=(
-                "A Cronjob object that use for validate and generate datetime."
-            ),
-        ),
-    ]
-    tz: Annotated[
-        TimeZoneName,
-        Field(
-            description="A timezone string value.",
-            alias="timezone",
+    extras: DictData = Field(
+        default_factory=dict,
+        description=(
+            "An extras parameters that want to pass to the CronJob field."
         ),
-    ] = "UTC"
-
-    @classmethod
-    def from_value(cls, value: DictStr, extras: DictData) -> Self:
-        """Constructor from values that will generate crontab by function.
-
-        :param value: (DictStr) A mapping value that will generate crontab
-            before create schedule model.
-        :param extras: (DictData) An extra parameter that use to override core
-            config value.
-        """
-        passing: DictStr = {}
-
-        if "timezone" in value:
-            passing["tz"] = value.pop("timezone")
-        elif "tz" in value:
-            passing["tz"] = value.pop("tz")
-
-        passing["cronjob"] = interval2crontab(
-            **{v: value[v] for v in value if v in ("interval", "day", "time")}
-        )
-        return cls(extras=extras | passing.pop("extras", {}), **passing)
-
-    @classmethod
-    def from_conf(
-        cls,
-        name: str,
-        *,
-        extras: DictData | None = None,
-    ) -> Self:
-        """Constructor from the name of config loader that will use loader
-        object for getting the `Crontab` data.
-
-        :param name: (str) A name of config that will get from loader.
-        :param extras: (DictData) An extra parameter that use to override core
-            config values.
-
-        :rtype: Self
-        """
-        extras: DictData = extras or {}
-        loader: YamlParser = YamlParser(name, extras=extras, obj=cls)
-
-        # NOTE: Validate the config type match with current connection model
-        if loader.type != cls.__name__:
-            raise ValueError(f"Type {loader.type} does not match with {cls}")
-
-        loader_data: DictData = loader.data
-        if "interval" in loader_data:
-            return cls.model_validate(
-                obj=dict(
-                    cronjob=interval2crontab(
-                        **{
-                            v: loader_data[v]
-                            for v in loader_data
-                            if v in ("interval", "day", "time")
-                        }
-                    ),
-                    extras=extras | loader_data.pop("extras", {}),
-                    **loader_data,
-                )
-            )
-        if "cronjob" not in loader_data:
-            raise ValueError("Config does not set `cronjob` or `interval` keys")
-        return cls.model_validate(
-            obj=dict(
-                cronjob=loader_data.pop("cronjob"),
-                extras=extras | loader_data.pop("extras", {}),
-                **loader_data,
-            )
-        )
+    )
+    tz: TimeZoneName = Field(
+        default="UTC",
+        description="A timezone string value.",
+        alias="timezone",
+    )
 
     @model_validator(mode="before")
     def __prepare_values(cls, data: Any) -> Any:
-        """Extract a `tz` key from data and change the key name from `tz` to
-        `timezone`.
+        """Extract and rename timezone key in input data.
 
-        :param data: (DictData) A data that want to pass for create a Crontab
-            model.
+        Args:
+            data: Input data dictionary for creating Crontab model.
 
-        :rtype: DictData
+        Returns:
+            Modified data dictionary with standardized timezone key.
         """
         if isinstance(data, dict) and (tz := data.pop("tz", None)):
             data["timezone"] = tz
@@ -186,10 +127,16 @@ class Crontab(BaseModel):
 
     @field_validator("tz")
     def __validate_tz(cls, value: str) -> str:
-        """Validate timezone value that able to initialize with ZoneInfo after
-        it passing to this model in before mode.
+        """Validate timezone value.
 
-        :rtype: str
+        Args:
+            value: Timezone string to validate.
+
+        Returns:
+            Validated timezone string.
+
+        Raises:
+            ValueError: If timezone is invalid.
         """
         try:
             _ = ZoneInfo(value)
@@ -197,21 +144,118 @@ class Crontab(BaseModel):
         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.
+        time: Time of day in 'HH:MM' format.
+    """
+
+    interval: Interval
+    day: Optional[str] = Field(default=None)
+    time: str = Field(default="00:00")
+
+    @property
+    def cronjob(self) -> CronJob:
+        """Get CronJob object built from interval format.
+
+        Returns:
+            CronJob instance configured with interval-based schedule.
+        """
+        return CronJob(
+            value=interval2crontab(self.interval, day=self.day, time=self.time)
+        )
+
+    def generate(self, start: Union[str, datetime]) -> CronRunner:
+        """Generate CronRunner from initial datetime.
+
+        Args:
+            start: Starting datetime (string or datetime object).
+
+        Returns:
+            CronRunner instance for schedule generation.
+
+        Raises:
+            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)
+
+    def next(self, start: Union[str, datetime]) -> CronRunner:
+        """Get next scheduled datetime after given start time.
+
+        Args:
+            start: Starting datetime for schedule generation.
+
+        Returns:
+            CronRunner instance positioned at next scheduled time.
+        """
+        runner: CronRunner = self.generate(start=start)
+
+        # NOTE: ship the next date of runner object that create from start.
+        _ = runner.next
+
+        return runner
+
+
+class Crontab(BaseCrontab):
+    """Cron event model wrapping CronJob functionality.
+
+    A Pydantic model that encapsulates crontab scheduling functionality with
+    validation and datetime generation capabilities.
+
+    Attributes:
+        cronjob: CronJob instance for schedule validation and datetime generation.
+        tz: Timezone string value (alias: timezone).
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    cronjob: CronJob = Field(
+        description=(
+            "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:
+        """Prepare input data by standardizing timezone key.
+
+        Args:
+            data: Input dictionary for model creation.
+
+        Returns:
+            Modified dictionary with standardized timezone key.
+        """
+        if isinstance(data, dict) and (tz := data.pop("tz", None)):
+            data["timezone"] = tz
+        return data
+
     @field_validator(
         "cronjob", mode="before", json_schema_input_type=Union[CronJob, str]
     )
     def __prepare_cronjob(
         cls, value: Union[str, CronJob], info: ValidationInfo
     ) -> CronJob:
-        """Prepare crontab value that able to receive with string type.
-        This step will get options kwargs from extras field and pass to the
-        CronJob object.
+        """Prepare and validate cronjob input.
 
-        :param value: (str | CronJobYear) A cronjob value that want to create.
-        :param info: (ValidationInfo) A validation info object that use to get
-            the extra parameters for create cronjob.
+        Args:
+            value: Raw cronjob value (string or CronJob instance).
+            info: Validation context containing extra parameters.
 
-        :rtype: CronJob
+        Returns:
+            Configured CronJob instance.
         """
         extras: DictData = info.data.get("extras", {})
         return (
@@ -229,21 +273,27 @@ class Crontab(BaseModel):
 
     @field_serializer("cronjob")
     def __serialize_cronjob(self, value: CronJob) -> str:
-        """Serialize the cronjob field that store with CronJob object.
+        """Serialize CronJob instance to string representation.
 
-        :param value: (CronJob) The CronJob field.
+        Args:
+            value: CronJob instance to serialize.
 
-        :rtype: str
+        Returns:
+            String representation of the CronJob.
         """
         return str(value)
 
     def generate(self, start: Union[str, datetime]) -> CronRunner:
-        """Return CronRunner object from an initial datetime.
+        """Generate schedule runner from start time.
+
+        Args:
+            start: Starting datetime (string or datetime object).
 
-        :param start: (str | datetime) A string or datetime for generate the
-            CronRunner object.
+        Returns:
+            CronRunner instance for schedule generation.
 
-        :rtype: CronRunner
+        Raises:
+            TypeError: If start parameter is neither string nor datetime.
         """
         if isinstance(start, str):
             start: datetime = datetime.fromisoformat(start)
@@ -252,13 +302,13 @@ class Crontab(BaseModel):
         return self.cronjob.schedule(date=start, tz=self.tz)
 
     def next(self, start: Union[str, datetime]) -> CronRunner:
-        """Return a next datetime from Cron runner object that start with any
-        date that given from input.
+        """Get runner positioned at next scheduled time.
 
-        :param start: (str | datetime) A start datetime that use to generate
-            the CronRunner object.
+        Args:
+            start: Starting datetime for schedule generation.
 
-        :rtype: CronRunner
+        Returns:
+            CronRunner instance positioned at next scheduled time.
         """
         runner: CronRunner = self.generate(start=start)
 
@@ -269,21 +319,22 @@ class Crontab(BaseModel):
 
 
 class CrontabYear(Crontab):
-    """Cron event with enhance Year Pydantic model for limit year matrix that
-    use by some data schedule tools like AWS Glue.
-    """
+    """Cron event model with enhanced year-based scheduling.
 
-    model_config = ConfigDict(arbitrary_types_allowed=True)
+    Extends the base Crontab model to support year-specific scheduling,
+    particularly useful for tools like AWS Glue.
 
-    # NOTE: This is fields of the base schedule.
-    cronjob: Annotated[
-        CronJobYear,
+    Attributes:
+        cronjob: CronJobYear instance for year-aware schedule validation and generation.
+    """
+
+    cronjob: CronJobYear = (
         Field(
             description=(
                 "A Cronjob object that use for validate and generate datetime."
             ),
         ),
-    ]
+    )
 
     @field_validator(
         "cronjob",
@@ -293,15 +344,14 @@ class CrontabYear(Crontab):
     def __prepare_cronjob(
         cls, value: Union[CronJobYear, str], info: ValidationInfo
     ) -> CronJobYear:
-        """Prepare crontab value that able to receive with string type.
-        This step will get options kwargs from extras field and pass to the
-        CronJobYear object.
+        """Prepare and validate year-aware cronjob input.
 
-        :param value: (str | CronJobYear) A cronjob value that want to create.
-        :param info: (ValidationInfo) A validation info object that use to get
-            the extra parameters for create cronjob.
+        Args:
+            value: Raw cronjob value (string or CronJobYear instance).
+            info: Validation context containing extra parameters.
 
-        :rtype: CronJobYear
+        Returns:
+            Configured CronJobYear instance with applied options.
         """
         extras: DictData = info.data.get("extras", {})
         return (
@@ -318,24 +368,73 @@ class CrontabYear(Crontab):
         )
 
 
-class ReleaseEvent(BaseModel):  # pragma: no cov
-    """Release trigger event."""
+Cron = Annotated[
+    Union[
+        CrontabYear,
+        Crontab,
+        CrontabValue,
+    ],
+    Field(
+        union_mode="smart",
+        description="Event model type supporting year-based, standard, and interval-based cron scheduling.",
+    ),
+]  # pragma: no cov
+
+
+class Event(BaseModel):
+    """Event model."""
 
+    schedule: list[Cron] = Field(
+        default_factory=list,
+        description="A list of Cron schedule.",
+    )
     release: list[str] = Field(
+        default_factory=list,
         description=(
             "A list of workflow name that want to receive event from release"
             "trigger."
-        )
+        ),
     )
 
+    @field_validator("schedule", mode="after")
+    def __on_no_dup_and_reach_limit__(
+        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.
 
-Event = Annotated[
-    Union[
-        CronJobYear,
-        CronJob,
-    ],
-    Field(
-        union_mode="smart",
-        description="An event models.",
-    ),
-]  # pragma: no cov
+        Returns:
+            list[CronJobYear | Crontab]: The validated list of Crontab objects.
+
+        Raises:
+            ValueError: If it has some duplicate value.
+        """
+        set_ons: set[str] = {str(on.cronjob) for on in value}
+        if len(set_ons) != len(value):
+            raise ValueError(
+                "The on fields should not contain duplicate on value."
+            )
+
+        # WARNING:
+        # if '* * * * *' in set_ons and len(set_ons) > 1:
+        #     raise ValueError(
+        #         "If it has every minute cronjob on value, it should have "
+        #         "only one value in the on field."
+        #     )
+        set_tz: set[str] = {on.tz for on in value}
+        if len(set_tz) > 1:
+            raise ValueError(
+                f"The on fields should not contain multiple timezone, "
+                f"{list(set_tz)}."
+            )
+
+        if len(set_ons) > 10:
+            raise ValueError(
+                "The number of the on should not more than 10 crontabs."
+            )
+        return value