ddeutil-workflow 0.0.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

ddeutil/workflow/__about__.py

@@ -1 +1 @@
-__version__: str = "0.0.3"
+__version__: str = "0.0.5"

ddeutil/workflow/{vendors/__schedule.py → __scheduler.py}

@@ -7,10 +7,10 @@ from __future__ import annotations
 
 import copy
 from collections.abc import Iterator
+from dataclasses import dataclass, field
 from datetime import datetime, timedelta, timezone
 from functools import partial, total_ordering
 from typing import (
-    Any,
     Callable,
     Optional,
     Union,
@@ -37,31 +37,55 @@ WEEKDAYS: dict[str, int] = {
     "Sat": 6,
 }
 
-CRON_UNITS: tuple[dict[str, Any], ...] = (
-    {
-        "name": "minute",
-        "range": partial(range, 0, 60),
-        "min": 0,
-        "max": 59,
-    },
-    {
-        "name": "hour",
-        "range": partial(range, 0, 24),
-        "min": 0,
-        "max": 23,
-    },
-    {
-        "name": "day",
-        "range": partial(range, 1, 32),
-        "min": 1,
-        "max": 31,
-    },
-    {
-        "name": "month",
-        "range": partial(range, 1, 13),
-        "min": 1,
-        "max": 12,
-        "alt": [
+
+@dataclass(frozen=True)
+class Unit:
+    name: str
+    range: partial
+    min: int
+    max: int
+    alt: list[str] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__}(name={self.name!r}, range={self.range},"
+            f"min={self.min}, max={self.max}"
+            f"{f', alt={self.alt}' if self.alt else ''})"
+        )
+
+
+@dataclass
+class Options:
+    output_weekday_names: bool = False
+    output_month_names: bool = False
+    output_hashes: bool = False
+
+
+CRON_UNITS: tuple[Unit, ...] = (
+    Unit(
+        name="minute",
+        range=partial(range, 0, 60),
+        min=0,
+        max=59,
+    ),
+    Unit(
+        name="hour",
+        range=partial(range, 0, 24),
+        min=0,
+        max=23,
+    ),
+    Unit(
+        name="day",
+        range=partial(range, 1, 32),
+        min=1,
+        max=31,
+    ),
+    Unit(
+        name="month",
+        range=partial(range, 1, 13),
+        min=1,
+        max=12,
+        alt=[
             "JAN",
             "FEB",
             "MAR",
@@ -75,13 +99,13 @@ CRON_UNITS: tuple[dict[str, Any], ...] = (
             "NOV",
             "DEC",
         ],
-    },
-    {
-        "name": "weekday",
-        "range": partial(range, 0, 7),
-        "min": 0,
-        "max": 6,
-        "alt": [
+    ),
+    Unit(
+        name="weekday",
+        range=partial(range, 0, 7),
+        min=0,
+        max=6,
+        alt=[
             "SUN",
             "MON",
             "TUE",
@@ -90,16 +114,16 @@ CRON_UNITS: tuple[dict[str, Any], ...] = (
             "FRI",
             "SAT",
         ],
-    },
+    ),
 )
 
-CRON_UNITS_AWS: tuple = CRON_UNITS + (
-    {
-        "name": "year",
-        "range": partial(range, 1990, 2101),
-        "min": 1990,
-        "max": 2100,
-    },
+CRON_UNITS_AWS: tuple[Unit, ...] = CRON_UNITS + (
+    Unit(
+        name="year",
+        range=partial(range, 1990, 2101),
+        min=1990,
+        max=2100,
+    ),
 )
 
 
@@ -115,31 +139,54 @@ class CronPart:
 
     def __init__(
         self,
-        unit: dict,
-        values: Union[str, list[int]],
-        options: dict,
-    ):
-        self.unit: dict = unit
-        self.options: dict = options
+        unit: Unit,
+        values: str | list[int],
+        options: Options,
+    ) -> None:
+        self.unit: Unit = unit
+        self.options: Options = options
+
         if isinstance(values, str):
             values: list[int] = self.from_str(values) if values != "?" else []
         elif isinstance_check(values, list[int]):
             values: list[int] = self.replace_weekday(values)
         else:
             raise TypeError(f"Invalid type of value in cron part: {values}.")
-        unique_values: list[int] = self.out_of_range(
+        self.values: list[int] = self.out_of_range(
             sorted(dict.fromkeys(values))
         )
-        self.values: list[int] = unique_values
 
     def __str__(self) -> str:
-        """Return str that use output to ``self.to_str()`` method."""
-        return self.to_str()
+        """Generate String value from part of cronjob."""
+        _hash: str = "H" if self.options.output_hashes else "*"
+
+        if self.is_full:
+            return _hash
+
+        if self.is_interval:
+            if self.is_full_interval:
+                return f"{_hash}/{self.step}"
+            _hash: str = (
+                f"H({self.filler(self.min)}-{self.filler(self.max)})"
+                if _hash == "H"
+                else f"{self.filler(self.min)}-{self.filler(self.max)}"
+            )
+            return f"{_hash}/{self.step}"
+
+        cron_range_strings: list[str] = []
+        for cron_range in self.ranges():
+            if isinstance(cron_range, list):
+                cron_range_strings.append(
+                    f"{self.filler(cron_range[0])}-{self.filler(cron_range[1])}"
+                )
+            else:
+                cron_range_strings.append(f"{self.filler(cron_range)}")
+        return ",".join(cron_range_strings) if cron_range_strings else "?"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return (
             f"{self.__class__.__name__}"
-            f"(unit={self.unit}, values={self.to_str()!r})"
+            f"(unit={self.unit}, values={self.__str__()!r})"
         )
 
     def __lt__(self, other) -> bool:
@@ -148,10 +195,6 @@ class CronPart:
     def __eq__(self, other) -> bool:
         return self.values == other.values
 
-    @property
-    def is_weekday(self) -> bool:
-        return self.unit["name"] == "weekday"
-
     @property
     def min(self) -> int:
         """Returns the smallest value in the range."""
@@ -176,15 +219,13 @@ class CronPart:
     @property
     def is_full(self) -> bool:
         """Returns true if range has all the values of the unit."""
-        return len(self.values) == (
-            self.unit.get("max") - self.unit.get("min") + 1
-        )
+        return len(self.values) == (self.unit.max - self.unit.min + 1)
 
     def from_str(self, value: str) -> tuple[int, ...]:
         """Parses a string as a range of positive integers. The string should
         include only `-` and `,` special strings.
 
-        :param value: a string value
+        :param value: A string value
         :type value: str
 
         TODO: support for `L`, `W`, and `#`
@@ -247,7 +288,7 @@ class CronPart:
             if (value_step and not is_int(value_step)) or value_step == "":
                 raise ValueError(
                     f"Invalid interval step value {value_step!r} for "
-                    f'{self.unit["name"]!r}'
+                    f"{self.unit.name!r}"
                 )
 
             interval_list.append(self._interval(value_range_list, value_step))
@@ -255,16 +296,14 @@ class CronPart:
 
     def replace_alternative(self, value: str) -> str:
         """Replaces the alternative representations of numbers in a string."""
-        for i, alt in enumerate(self.unit.get("alt", [])):
+        for i, alt in enumerate(self.unit.alt):
             if alt in value:
-                value: str = value.replace(alt, str(self.unit["min"] + i))
+                value: str = value.replace(alt, str(self.unit.min + i))
         return value
 
-    def replace_weekday(
-        self, values: Union[list[int], Iterator[int]]
-    ) -> list[int]:
+    def replace_weekday(self, values: list[int] | Iterator[int]) -> list[int]:
         """Replaces all 7 with 0 as Sunday can be represented by both."""
-        if self.is_weekday:
+        if self.unit.name == "weekday":
             return [0 if value == 7 else value for value in values]
         return list(values)
 
@@ -277,20 +316,20 @@ class CronPart:
         :rtype: list[int]
         """
         if values:
-            if (first := values[0]) < self.unit["min"]:
+            if (first := values[0]) < self.unit.min:
                 raise ValueError(
-                    f'Value {first!r} out of range for {self.unit["name"]!r}'
+                    f"Value {first!r} out of range for {self.unit.name!r}"
                 )
-            elif (last := values[-1]) > self.unit["max"]:
+            elif (last := values[-1]) > self.unit.max:
                 raise ValueError(
-                    f'Value {last!r} out of range for {self.unit["name"]!r}'
+                    f"Value {last!r} out of range for {self.unit.name!r}"
                 )
         return values
 
     def _parse_range(self, value: str) -> list[int]:
         """Parses a range string."""
         if value == "*":
-            return list(self.unit["range"]())
+            return list(self.unit.range())
         elif value.count("-") > 1:
             raise ValueError(f"Invalid value {value}")
         try:
@@ -306,7 +345,9 @@ class CronPart:
         return self.replace_weekday(sub_parts)
 
     def _interval(
-        self, values: list[int], step: Optional[int] = None
+        self,
+        values: list[int],
+        step: int | None = None,
     ) -> list[int]:
         """Applies an interval step to a collection of values."""
         if not step:
@@ -314,7 +355,7 @@ class CronPart:
         elif (_step := int(step)) < 1:
             raise ValueError(
                 f"Invalid interval step value {_step!r} for "
-                f'{self.unit["name"]!r}'
+                f"{self.unit.name!r}"
             )
         min_value: int = values[0]
         return [
@@ -340,8 +381,8 @@ class CronPart:
         """Returns true if the range contains all the interval values."""
         if step := self.step:
             return (
-                self.min == self.unit["min"]
-                and (self.max + step) > self.unit["max"]
+                self.min == self.unit.min
+                and (self.max + step) > self.unit.max
                 and (
                     len(self.values)
                     == (round((self.max - self.min) / step) + 1)
@@ -376,33 +417,6 @@ class CronPart:
                 start_number: Optional[int] = value
         return multi_dim_values
 
-    def to_str(self) -> str:
-        """Returns the cron range as a string value."""
-        _hash: str = "H" if self.options.get("output_hashes") else "*"
-
-        if self.is_full:
-            return _hash
-
-        if self.is_interval:
-            if self.is_full_interval:
-                return f"{_hash}/{self.step}"
-            _hash: str = (
-                f"H({self.filler(self.min)}-{self.filler(self.max)})"
-                if _hash == "H"
-                else f"{self.filler(self.min)}-{self.filler(self.max)}"
-            )
-            return f"{_hash}/{self.step}"
-
-        cron_range_strings: list[str] = []
-        for cron_range in self.ranges():
-            if isinstance(cron_range, list):
-                cron_range_strings.append(
-                    f"{self.filler(cron_range[0])}-{self.filler(cron_range[1])}"
-                )
-            else:
-                cron_range_strings.append(f"{self.filler(cron_range)}")
-        return ",".join(cron_range_strings) if cron_range_strings else "?"
-
     def filler(self, value: int) -> int | str:
         """Formats weekday and month names as string when the relevant options
         are set.
@@ -413,15 +427,15 @@ class CronPart:
         :rtype: int | str
         """
         return (
-            self.unit["alt"][value - self.unit["min"]]
+            self.unit.alt[value - self.unit.min]
             if (
                 (
-                    self.options["output_weekday_names"]
-                    and self.unit["name"] == "weekday"
+                    self.options.output_weekday_names
+                    and self.unit.name == "weekday"
                 )
                 or (
-                    self.options["output_month_names"]
-                    and self.unit["name"] == "month"
+                    self.options.output_month_names
+                    and self.unit.name == "month"
                 )
             )
             else value
@@ -433,7 +447,7 @@ class CronJob:
     """The Cron Job Converter object that generate datetime dimension of cron
     job schedule format,
 
-            * * * * * <command to execute>
+            ... * * * * * <command to execute>
 
         (i)     minute (0 - 59)
         (ii)    hour (0 - 23)
@@ -447,25 +461,20 @@ class CronJob:
         Support special value with `/`, `*`, `-`, `,`, and `?` (in day of month
     and day of week value).
 
-    :ref:
+    References:
         - https://github.com/Sonic0/cron-converter
         - https://pypi.org/project/python-crontab/
     """
 
     cron_length: int = 5
-
-    options_defaults: dict[str, bool] = {
-        "output_weekday_names": False,
-        "output_month_names": False,
-        "output_hashes": False,
-    }
+    cron_units: tuple[Unit, ...] = CRON_UNITS
 
     def __init__(
         self,
         value: Union[list[list[int]], str],
         *,
         option: Optional[dict[str, bool]] = None,
-    ):
+    ) -> None:
         if isinstance(value, str):
             value: list[str] = value.strip().split()
         elif not isinstance_check(value, list[list[int]]):
@@ -473,16 +482,22 @@ class CronJob:
                 f"{self.__class__.__name__} cron value does not support "
                 f"type: {type(value)}."
             )
+
+        # NOTE: Validate length of crontab of this class.
         if len(value) != self.cron_length:
             raise ValueError(
                 f"Invalid cron value does not have length equal "
                 f"{self.cron_length}: {value}."
             )
-        self._options: dict[str, bool] = self.options_defaults | (option or {})
-        self._parts: list[CronPart] = [
-            CronPart(unit, values=item, options=self._options)
-            for item, unit in zip(value, CRON_UNITS)
+        self.options: Options = Options(**(option or {}))
+
+        # NOTE: Start initial crontab for each part
+        self.parts: list[CronPart] = [
+            CronPart(unit, values=item, options=self.options)
+            for item, unit in zip(value, self.cron_units)
         ]
+
+        # NOTE: Validate values of `day` and `dow` from parts.
         if self.day == self.dow == []:
             raise ValueError(
                 "Invalid cron value when set the `?` on day of month and "
@@ -490,12 +505,13 @@ class CronJob:
             )
 
     def __str__(self) -> str:
-        return " ".join(str(part) for part in self._parts)
+        """Return joining with space of each value in parts."""
+        return " ".join(str(part) for part in self.parts)
 
     def __repr__(self) -> str:
         return (
             f"{self.__class__.__name__}(value={self.__str__()!r}, "
-            f"option={self._options})"
+            f"option={self.options.__dict__})"
         )
 
     def __lt__(self, other) -> bool:
@@ -510,10 +526,6 @@ class CronJob:
             for part, other_part in zip(self.parts, other.parts)
         )
 
-    @property
-    def parts(self) -> list[CronPart]:
-        return self._parts
-
     @property
     def parts_order(self) -> Iterator[CronPart]:
         return reversed(self.parts[:3] + [self.parts[4], self.parts[3]])
@@ -521,31 +533,31 @@ class CronJob:
     @property
     def minute(self):
         """Return part of minute."""
-        return self._parts[0]
+        return self.parts[0]
 
     @property
     def hour(self):
         """Return part of hour."""
-        return self._parts[1]
+        return self.parts[1]
 
     @property
     def day(self):
         """Return part of day."""
-        return self._parts[2]
+        return self.parts[2]
 
     @property
     def month(self):
         """Return part of month."""
-        return self._parts[3]
+        return self.parts[3]
 
     @property
     def dow(self):
         """Return part of day of month."""
-        return self._parts[4]
+        return self.parts[4]
 
     def to_list(self) -> list[list[int]]:
         """Returns the cron schedule as a 2-dimensional list of integers."""
-        return [part.values for part in self._parts]
+        return [part.values for part in self.parts]
 
     def schedule(
         self, date: Optional[datetime] = None, _tz: Optional[str] = None
@@ -554,6 +566,11 @@ class CronJob:
         return CronRunner(self, date, tz_str=_tz)
 
 
+class CronJobAWS(CronJob):
+    cron_length = 6
+    cron_units = CRON_UNITS_AWS
+
+
 class CronRunner:
     """Create an instance of Date Runner object for datetime generate with
     cron schedule object value.
@@ -661,7 +678,8 @@ class CronRunner:
         return False
 
 
-__all__: tuple[str, ...] = (
+__all__ = (
     "CronJob",
     "CronRunner",
+    "WEEKDAYS",
 )

ddeutil/workflow/loader.py

@@ -37,6 +37,9 @@ class Engine(BaseModel):
 
     @model_validator(mode="before")
     def __prepare_registry(cls, values: DictData) -> DictData:
+        """Prepare registry value that passing with string type. It convert the
+        string type to list of string.
+        """
         if (_regis := values.get("registry")) and isinstance(_regis, str):
             values["registry"] = [_regis]
         return values
@@ -83,7 +86,9 @@ class SimLoad:
 
     @cached_property
     def type(self) -> BaseModelType:
-        """Return object type which implement in `config_object` key."""
+        """Return object of string type which implement on any registry. The
+        object type
+        """
         if not (_typ := self.data.get("type")):
             raise ValueError(
                 f"the 'type' value: {_typ} does not exists in config data."
@@ -100,6 +105,9 @@ class SimLoad:
             return import_string(f"{_typ}")
 
     def load(self) -> AnyModel:
+        """Parsing config data to the object type for initialize with model
+        validate method.
+        """
         return self.type.model_validate(self.data)