ddeutil-workflow 0.0.4__py3-none-any.whl → 0.0.6__py3-none-any.whl

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

@@ -7,14 +7,10 @@ from __future__ import annotations
 
 import copy
 from collections.abc import Iterator
-from datetime import datetime, timedelta, timezone
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
 from functools import partial, total_ordering
-from typing import (
-    Any,
-    Callable,
-    Optional,
-    Union,
-)
+from typing import Callable, Optional, Union
 from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 from ddeutil.core import (
@@ -37,31 +33,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 +95,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 +110,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_YEAR: tuple[Unit, ...] = CRON_UNITS + (
+    Unit(
+        name="year",
+        range=partial(range, 1990, 2101),
+        min=1990,
+        max=2100,
+    ),
 )
 
 
@@ -115,42 +135,68 @@ 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:
-        return self.values < other.values
+        if isinstance(other, CronPart):
+            return self.values < other.values
+        elif isinstance(other, list):
+            return self.values < other
 
     def __eq__(self, other) -> bool:
-        return self.values == other.values
-
-    @property
-    def is_weekday(self) -> bool:
-        return self.unit["name"] == "weekday"
+        if isinstance(other, CronPart):
+            return self.values == other.values
+        elif isinstance(other, list):
+            return self.values == other
 
     @property
     def min(self) -> int:
@@ -176,19 +222,17 @@ 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 that want to parse
         :type value: str
 
         TODO: support for `L`, `W`, and `#`
-        TODO:     if you didn't care what day of the week the 7th was, you
+        TODO: if you didn't care what day of the week the 7th was, you
             could enter ? in the Day-of-week field.
         TODO: L : the Day-of-month or Day-of-week fields specifies the last day
             of the month or week.
@@ -198,7 +242,7 @@ class CronPart:
         TODO: # : 3#2 would be the second Tuesday of the month,
             the 3 refers to Tuesday because it is the third day of each week.
 
-        Examples:
+        Noted:
             -   0 10 * * ? *
                 Run at 10:00 am (UTC) every day
 
@@ -247,7 +291,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,17 +299,20 @@ 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]:
-        """Replaces all 7 with 0 as Sunday can be represented by both."""
-        if self.is_weekday:
-            return [0 if value == 7 else value for value in values]
+    def replace_weekday(self, values: list[int] | Iterator[int]) -> list[int]:
+        """Replaces all 7 with 0 as Sunday can be represented by both.
+
+        :param values: list or iter of int that want to mode by 7
+        :rtype: list[int]
+        """
+        if self.unit.name == "weekday":
+            # NOTE: change weekday value in range 0-6 (div-mod by 7).
+            return [value % 7 for value in values]
         return list(values)
 
     def out_of_range(self, values: list[int]) -> list[int]:
@@ -277,20 +324,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 +353,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 +363,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 +389,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 +425,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 +435,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 +455,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 +469,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 +490,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 +513,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,48 +534,63 @@ 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]])
 
     @property
-    def minute(self):
+    def minute(self) -> CronPart:
         """Return part of minute."""
-        return self._parts[0]
+        return self.parts[0]
 
     @property
-    def hour(self):
+    def hour(self) -> CronPart:
         """Return part of hour."""
-        return self._parts[1]
+        return self.parts[1]
 
     @property
-    def day(self):
+    def day(self) -> CronPart:
         """Return part of day."""
-        return self._parts[2]
+        return self.parts[2]
 
     @property
-    def month(self):
+    def month(self) -> CronPart:
         """Return part of month."""
-        return self._parts[3]
+        return self.parts[3]
 
     @property
-    def dow(self):
+    def dow(self) -> CronPart:
         """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
+        self,
+        date: datetime | None = None,
+        *,
+        tz: str | None = None,
     ) -> CronRunner:
-        """Returns the time the schedule would run next."""
-        return CronRunner(self, date, tz_str=_tz)
+        """Returns the schedule datetime runner with this cronjob. It would run
+        ``next``, ``prev``, or ``reset`` to generate running date that you want.
+
+        :param date: An initial date that want to mark as the start point.
+        :param tz: A string timezone that want to change on runner.
+        :rtype: CronRunner
+        """
+        return CronRunner(self, date, tz=tz)
+
+
+class CronJobYear(CronJob):
+    cron_length = 6
+    cron_units = CRON_UNITS_YEAR
+
+    @property
+    def year(self) -> CronPart:
+        """Return part of year."""
+        return self.parts[5]
 
 
 class CronRunner:
@@ -569,33 +608,37 @@ class CronRunner:
 
     def __init__(
         self,
-        cron: CronJob,
-        date: Optional[datetime] = None,
+        cron: CronJob | CronJobYear,
+        date: datetime | None = None,
         *,
-        tz_str: Optional[str] = None,
+        tz: str | None = None,
     ) -> None:
-        # NOTE: Prepare date and tz_info
-        self.tz = timezone.utc
-        if tz_str:
+        # NOTE: Prepare timezone if this value does not set, it will use UTC.
+        self.tz: ZoneInfo = ZoneInfo("UTC")
+        if tz:
             try:
-                self.tz = ZoneInfo(tz_str)
+                self.tz = ZoneInfo(tz)
             except ZoneInfoNotFoundError as err:
-                raise ValueError(f"Invalid timezone: {tz_str}") from err
+                raise ValueError(f"Invalid timezone: {tz}") from err
+
+        # NOTE: Prepare date
         if date:
             if not isinstance(date, datetime):
                 raise ValueError(
                     "Input schedule start time is not a valid datetime object."
                 )
-            self.tz = date.tzinfo
-            self.date: datetime = date
+            if tz is None:
+                self.tz = date.tzinfo
+            self.date: datetime = date.astimezone(self.tz)
         else:
             self.date: datetime = datetime.now(tz=self.tz)
 
+        # NOTE: Add one minute if the second value more than 0.
         if self.date.second > 0:
-            self.date: datetime = self.date + timedelta(minutes=+1)
+            self.date: datetime = self.date + timedelta(minutes=1)
 
         self.__start_date: datetime = self.date
-        self.cron: CronJob = cron
+        self.cron: CronJob | CronJobYear = cron
         self.reset_flag: bool = True
 
     def reset(self) -> None:
@@ -620,7 +663,11 @@ class CronRunner:
         return self.find_date(reverse=True)
 
     def find_date(self, reverse: bool = False) -> datetime:
-        """Returns the time the schedule would run by `next` or `prev`."""
+        """Returns the time the schedule would run by `next` or `prev`.
+
+        :param reverse: A reverse flag.
+        """
+        # NOTE: Set reset flag to false if start any action.
         self.reset_flag: bool = False
         for _ in range(25):
             if all(
@@ -639,7 +686,7 @@ class CronRunner:
             "minute": "hour",
         }
         current_value: int = getattr(self.date, switch[mode])
-        _addition: Callable[[], bool] = (
+        _addition_condition: Callable[[], bool] = (
             (
                 lambda: WEEKDAYS.get(self.date.strftime("%a"))
                 not in self.cron.dow.values
@@ -647,21 +694,20 @@ class CronRunner:
             if mode == "day"
             else lambda: False
         )
+        # NOTE: Start while-loop for checking this date include in this cronjob.
         while (
             getattr(self.date, mode) not in getattr(self.cron, mode).values
-        ) or _addition():
-            self.date: datetime = next_date(
-                self.date, mode=mode, reverse=reverse
-            )
-            self.date: datetime = replace_date(
-                self.date, mode=mode, reverse=reverse
-            )
+        ) or _addition_condition():
+            self.date: datetime = next_date(self.date, mode, reverse=reverse)
+            self.date: datetime = replace_date(self.date, mode, reverse=reverse)
             if current_value != getattr(self.date, switch[mode]):
                 return mode != "month"
         return False
 
 
-__all__: tuple[str, ...] = (
+__all__ = (
     "CronJob",
+    "CronJobYear",
     "CronRunner",
+    "WEEKDAYS",
 )