pyfect-dev 0.1.0__py3-none-any.whl

pyfect/cron/_search.py

@@ -0,0 +1,268 @@
+"""Matching a datetime against a ``Cron`` and searching for the next or
+previous matching instant, following Effect's ``Cron.next`` / ``prev``
+field by field (and its DST handling) on a wall-clock time in the cron's
+zone."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable, Iterator
+from datetime import UTC, datetime, timedelta, timezone
+from zoneinfo import ZoneInfo
+
+from pyfect.cron._model import Cron
+from pyfect.cron._wall import days_in_month, weekday, with_fields
+from pyfect.date_time._zones import make_zoned, zone_of
+
+_SEARCH_BUDGET = 10_000
+
+
+def match(cron: Cron, date: datetime) -> bool:
+    """Whether ``date`` (an aware datetime), read in the cron's zone, is one
+    of the cron's times."""
+    zone_of(date, "date")
+    wall = (date if cron.tz is None else date.astimezone(cron.tz)).replace(tzinfo=None)
+    fields = (
+        (cron.seconds, wall.second),
+        (cron.minutes, wall.minute),
+        (cron.hours, wall.hour),
+        (cron.months, wall.month),
+    )
+    return all(not allowed or value in allowed for allowed, value in fields) and _day_matches(
+        cron, wall
+    )
+
+
+def _day_matches(cron: Cron, wall: datetime) -> bool:
+    """Days and weekdays both restricted match either, unless ``and_``."""
+    in_days = wall.day in cron.days
+    in_weekdays = weekday(wall) in cron.weekdays
+    if cron.and_ or not cron.days or not cron.weekdays:
+        return (not cron.days or in_days) and (not cron.weekdays or in_weekdays)
+    return in_days or in_weekdays
+
+
+def next(cron: Cron, now: datetime | None = None) -> datetime:
+    """The first of the cron's times strictly after ``now`` (default: the
+    current time), in the cron's zone. A wall time a DST change repeats
+    runs once, at its first occurrence; one a DST change skips runs at the
+    matching time after the gap. Raises ``ValueError`` when no time
+    matches (such as February 30)."""
+    return _Walk(cron, _start(cron, now), reverse=False).run()
+
+
+def prev(cron: Cron, now: datetime | None = None) -> datetime:
+    """The last of the cron's times strictly before ``now`` (default: the
+    current time), in the cron's zone. Raises ``ValueError`` when no time
+    matches."""
+    return _Walk(cron, _start(cron, now), reverse=True).run()
+
+
+def sequence(cron: Cron, now: datetime | None = None) -> Iterator[datetime]:
+    """The cron's times after ``now`` (default: the current time), forever."""
+    current = now
+    while True:
+        current = next(cron, current)
+        yield current
+
+
+def _start(cron: Cron, now: datetime | None) -> datetime:
+    """``now`` in the zone the search runs in: the cron's, else ``now``'s
+    own, else the local offset at the current time."""
+    if now is None:
+        now = datetime.now(UTC).astimezone()
+    zone_of(now, "now")
+    return now if cron.tz is None else now.astimezone(cron.tz)
+
+
+class _NoMatch(ValueError):
+    def __init__(self) -> None:
+        super().__init__("Unable to find cron date")
+
+
+type _Step = Callable[[datetime], datetime | None]
+
+
+class _Walk:
+    """One search. Each field step either moves the wall time (to the
+    field's nearest allowed value, resetting the smaller fields to their
+    boundary) or accepts it; the search ends when every field accepts."""
+
+    def __init__(self, cron: Cron, start: datetime, *, reverse: bool) -> None:
+        plan = cron._plan
+        self.cron = cron
+        self.start = start
+        self.zone = zone = zone_of(start, "now")
+        self.reverse = reverse
+        self.tick = -1 if reverse else 1
+        self.table = plan.prev if reverse else plan.next
+        self.bound = plan.last if reverse else plan.first
+        self.dst = not isinstance(zone, timezone) and not (
+            isinstance(zone, ZoneInfo) and zone.key == "UTC"
+        )
+
+    def run(self) -> datetime:
+        try:
+            return self._run()
+        except (OverflowError, ValueError):
+            # Running off ``datetime``'s years 1-9999 means nothing matched.
+            raise _NoMatch() from None
+
+    def _run(self) -> datetime:
+        steps: tuple[_Step, ...] = (self._second, self._minute, self._hour, self._day, self._month)
+        first = self.start.replace(tzinfo=None)
+        # Start from the nearest whole second strictly past the input in the
+        # search direction. Going backward, a fractional input already has one.
+        offset = 0 if self.reverse and first.microsecond > 0 else self.tick
+        wall = with_fields(first, second=first.second + offset)
+        attempts = 0
+        while attempts < _SEARCH_BUDGET:
+            attempts += 1
+            moved = _first_move(steps, wall)
+            if moved is not None:
+                wall = self._adjust(moved)
+            elif self._before_start(wall):
+                wall += timedelta(seconds=1)
+                attempts = 0  # skipped fold candidates do not count against the budget
+            else:
+                return make_zoned(wall, self.zone)
+        raise _NoMatch()
+
+    def _needs_step(self, target: int, current: int) -> bool:
+        return target < current if self.reverse else target > current
+
+    def _adjust(self, wall: datetime) -> datetime:
+        """Move a wall time that a DST change skips out of the gap."""
+        if not self.dst:
+            return wall
+        disambiguation = "later" if self.reverse else "compatible"
+        resolved = make_zoned(wall, self.zone, disambiguation=disambiguation)
+        drift = wall - resolved.replace(tzinfo=None)
+        if self.reverse:
+            return wall - drift
+        return wall + drift if drift > timedelta(0) else wall
+
+    def _before_start(self, wall: datetime) -> bool:
+        """A repeated wall time resolves to its first occurrence, which is in
+        the past when the search starts in the second one."""
+        if not self.dst or self.reverse:
+            return False
+        return make_zoned(wall, self.zone).timestamp() <= self.start.timestamp()
+
+    def _day_start(self, wall: datetime, *, day: int) -> datetime:
+        b = self.bound
+        return with_fields(wall, day=day, hour=b.hour, minute=b.minute, second=b.second)
+
+    def _second(self, wall: datetime) -> datetime | None:
+        if not self.cron.seconds:
+            return None
+        target = self.table.second[wall.second]
+        if target is None:
+            return with_fields(wall, minute=wall.minute + self.tick, second=self.bound.second)
+        return with_fields(wall, second=target) if self._needs_step(target, wall.second) else None
+
+    def _minute(self, wall: datetime) -> datetime | None:
+        if not self.cron.minutes:
+            return None
+        b = self.bound
+        target = self.table.minute[wall.minute]
+        if target is None:
+            return with_fields(wall, hour=wall.hour + self.tick, minute=b.minute, second=b.second)
+        if self._needs_step(target, wall.minute):
+            return with_fields(wall, minute=target, second=b.second)
+        return None
+
+    def _hour(self, wall: datetime) -> datetime | None:
+        if not self.cron.hours:
+            return None
+        b = self.bound
+        target = self.table.hour[wall.hour]
+        if target is None:
+            return self._day_start(wall, day=wall.day + self.tick)
+        if self._needs_step(target, wall.hour):
+            return with_fields(wall, hour=target, minute=b.minute, second=b.second)
+        return None
+
+    def _day(self, wall: datetime) -> datetime | None:
+        cron = self.cron
+        if not cron.weekdays and not cron.days:
+            return None
+        if cron.and_:
+            day_ok = not cron.days or wall.day in cron.days
+            weekday_ok = not cron.weekdays or weekday(wall) in cron.weekdays
+            return (
+                None if day_ok and weekday_ok else self._day_start(wall, day=wall.day + self.tick)
+            )
+        add_days = self._days_to_candidate(wall)
+        return None if add_days == 0 else self._day_start(wall, day=wall.day + add_days)
+
+    def _days_to_candidate(self, wall: datetime) -> int:
+        """Days to the nearest day matching the day-of-month or the weekday
+        restriction (whichever comes first), 0 if ``wall``'s day does."""
+        by_weekday = by_day = -math.inf if self.reverse else math.inf
+        if self.cron.weekdays:
+            by_weekday = self._days_by_weekday(wall)
+        if self.cron.days and by_weekday != 0:
+            by_day = self._days_by_day(wall)
+        return int(max(by_weekday, by_day) if self.reverse else min(by_weekday, by_day))
+
+    def _days_by_weekday(self, wall: datetime) -> int:
+        current = weekday(wall)
+        target = self.table.weekday[current]
+        if target is not None:
+            return target - current
+        if self.reverse:
+            return self.bound.weekday - 7 - current
+        return 7 - current + self.bound.weekday
+
+    def _days_by_day(self, wall: datetime) -> int:
+        current = wall.day
+        target = self.table.day[current]
+        month_days = days_in_month(wall.year, wall.month)
+        if target is None and self.reverse:
+            # Day zero is the previous month's last day. These two probes
+            # cover every valid day of the month.
+            previous = with_fields(wall, day=0)
+            found = self.table.day[previous.day]
+            if found is None:
+                previous = with_fields(previous, day=0)
+                found = self.table.day[previous.day]
+            if found is None:
+                raise _NoMatch()
+            return (with_fields(previous, day=found) - wall).days
+        if target is None or (not self.reverse and target > month_days):
+            # A next matching day missing from this month must not overflow
+            # past the earlier matching days of the next one.
+            return month_days - current + self.bound.day
+        return target - current
+
+    def _month(self, wall: datetime) -> datetime | None:
+        if not self.cron.months:
+            return None
+        b = self.bound
+        target = self.table.month[wall.month]
+        if target is None:
+            wall = with_fields(wall, year=wall.year + self.tick)
+            target = b.month
+        elif not self._needs_step(target, wall.month):
+            return None
+        wall = with_fields(wall, month=target, day=self._month_start_day(wall.year, target))
+        return with_fields(wall, hour=b.hour, minute=b.minute, second=b.second)
+
+    def _month_start_day(self, year: int, month: int) -> int:
+        last_day = days_in_month(year, month)
+        if self.cron.days and not self.cron.weekdays:
+            if not self.reverse:
+                return self.bound.day
+            found = self.table.day[last_day]
+            return last_day if found is None else found
+        return last_day if self.reverse else 1
+
+
+def _first_move(steps: tuple[_Step, ...], wall: datetime) -> datetime | None:
+    for step in steps:
+        moved = step(wall)
+        if moved is not None:
+            return moved
+    return None

pyfect/cron/_text.py

@@ -0,0 +1,202 @@
+"""Cron expressions: ``parse`` text into a ``Cron`` and ``format`` one back."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import tzinfo
+
+from pyfect._digits import parse_digits
+from pyfect.cron._model import Cron
+from pyfect.date_time import zone_from_string
+from pyfect.errors import TaggedError
+from pyfect.result import Err, Ok, Result
+
+
+@dataclass(eq=False)
+class CronParseError(TaggedError, ValueError):
+    """A cron expression (or its time zone) that ``parse`` rejects.
+    ``input`` is the rejected text."""
+
+    message: str
+    input: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class _Field:
+    low: int
+    high: int
+    aliases: dict[str, int] | None = None
+    sunday_is_7: bool = False
+
+
+_SECOND = _Field(0, 59)
+_MINUTE = _Field(0, 59)
+_HOUR = _Field(0, 23)
+_DAY = _Field(1, 31)
+_MONTH = _Field(
+    1,
+    12,
+    {
+        name: i + 1
+        for i, name in enumerate(
+            ("jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec")
+        )
+    },
+)
+_WEEKDAY = _Field(
+    0,
+    7,
+    {name: i for i, name in enumerate(("sun", "mon", "tue", "wed", "thu", "fri", "sat"))},
+    sunday_is_7=True,
+)
+
+
+def parse(expression: str, tz: tzinfo | str | None = None) -> Result[Cron, CronParseError]:
+    """Parse a cron expression of five fields (minute hour day month
+    weekday) or six (with seconds first). Fields take ``*``, values, ranges
+    ``a-b``, steps ``/n`` and lists ``a,b``; months and weekdays also take
+    three-letter names. ``tz`` is a zone or a zone string
+    (``"Europe/Berlin"``, ``"+02:00"``)."""
+    segments = expression.split()
+    if len(segments) not in (5, 6):
+        return Err(CronParseError("Invalid number of segments in cron expression", expression))
+    if len(segments) == 5:
+        segments.insert(0, "0")
+    zone = zone_from_string(tz) if isinstance(tz, str) else tz
+    if isinstance(tz, str) and zone is None:
+        return Err(CronParseError("Invalid time zone in cron expression", tz))
+    parsed: list[tuple[set[int], bool]] = []
+    for segment, spec in zip(
+        segments, (_SECOND, _MINUTE, _HOUR, _DAY, _MONTH, _WEEKDAY), strict=True
+    ):
+        result = _parse_segment(segment, spec)
+        if isinstance(result, CronParseError):
+            return Err(result)
+        parsed.append(result)
+    seconds, minutes, hours, (days, days_wild), months, (weekdays, weekdays_wild) = parsed
+    return Ok(
+        Cron(
+            tz=zone,
+            seconds=seconds[0],
+            minutes=minutes[0],
+            hours=hours[0],
+            days=days,
+            months=months[0],
+            weekdays=weekdays,
+            and_=(days_wild or weekdays_wild) and bool(days) and bool(weekdays),
+        )
+    )
+
+
+def parse_unsafe(expression: str, tz: tzinfo | str | None = None) -> Cron:
+    """``parse``, raising ``CronParseError`` for a bad expression."""
+    return parse(expression, tz).get_or_raise()
+
+
+def _number(text: str) -> int | None:
+    """A plain decimal integer, or ``None`` (Effect's ``NaN``)."""
+    return parse_digits(text)
+
+
+def _split_step(text: str) -> tuple[str, bool, int | None]:
+    raw, slash, step = text.partition("/")
+    return (raw, True, _number(step)) if slash else (raw, False, None)
+
+
+def _value(text: str, spec: _Field) -> int | None:
+    alias = spec.aliases.get(text.lower()) if spec.aliases else None
+    return alias if alias is not None else _number(text)
+
+
+def _parse_segment(text: str, spec: _Field) -> tuple[set[int], bool] | CronParseError:
+    """The segment's values and whether it starts with ``*``. A leading
+    ``*`` with no step leaves the field unrestricted."""
+    values: set[int] = set()
+    fields = text.split(",")
+    first = _split_step(fields[0])
+    wildcard = first[0] == "*"
+    unrestricted = wildcard and (not first[1] or first[2] == 1)
+    for index, part in enumerate(fields):
+        raw, has_step, step = first if index == 0 else _split_step(part)
+        error = _step_error(has_step, step, spec)
+        if error is not None:
+            return CronParseError(error, text)
+        by = 1 if step is None else step
+        if raw == "*" and index == 0 and by == 1:
+            continue
+        bounds = (spec.low, spec.high) if raw == "*" else _bounds(raw, has_step, spec)
+        if isinstance(bounds, str):
+            return CronParseError(bounds, text)
+        if not unrestricted:
+            start, stop = bounds
+            values.update(
+                0 if spec.sunday_is_7 and v == 7 else v for v in range(start, stop + 1, by)
+            )
+    return values, wildcard
+
+
+def _step_error(has_step: bool, step: int | None, spec: _Field) -> str | None:
+    if not has_step:
+        return None
+    if step is None:
+        return "Expected step value to be a positive integer"
+    if step < 1:
+        return "Expected step value to be greater than 0"
+    if step > spec.high:
+        return f"Expected step value to be less than or equal to {spec.high}"
+    return None
+
+
+def _bounds(raw: str, has_step: bool, spec: _Field) -> tuple[int, int] | str:
+    """The first and last value of ``a``, ``a/n`` (up to the field's
+    maximum) or ``a-b``, or an error message."""
+    left_text, dash, right_text = raw.partition("-")
+    left = _checked_value(left_text, spec)
+    if isinstance(left, str) or not dash:
+        return left if isinstance(left, str) else (left, spec.high if has_step else left)
+    right = _checked_value(right_text, spec)
+    if isinstance(right, str):
+        return right
+    return "Invalid value range" if left > right else (left, right)
+
+
+def _checked_value(text: str, spec: _Field) -> int | str:
+    value = _value(text, spec)
+    if value is None:
+        return "Expected a positive integer"
+    if not spec.low <= value <= spec.high:
+        return f"Expected a value between {spec.low} and {spec.high}"
+    return value
+
+
+def format(cron: Cron, *, include_seconds: bool = False) -> str:
+    """The cron expression for ``cron``, compacting runs into ranges and
+    steps. The seconds field is left out when it is just 0, unless
+    ``include_seconds``. The zone is not part of the expression."""
+    fields = (cron.seconds, cron.minutes, cron.hours, cron.days, cron.months, cron.weekdays)
+    segments = [_format_segment(values) for values in fields]
+    if not include_seconds and cron.seconds == frozenset({0}):
+        segments = segments[1:]
+    return " ".join(segments)
+
+
+def _format_segment(values: frozenset[int]) -> str:
+    if not values:
+        return "*"
+    array = sorted(values)
+    segments: list[str] = []
+    index = 0
+    while index < len(array):
+        start = array[index]
+        if index + 2 < len(array):
+            step = array[index + 1] - start
+            if array[index + 2] - array[index + 1] == step:
+                end = index + 2
+                while end + 1 < len(array) and array[end + 1] - array[end] == step:
+                    end += 1
+                segments.append(f"{start}-{array[end]}" + ("" if step == 1 else f"/{step}"))
+                index = end + 1
+                continue
+        segments.append(str(start))
+        index += 1
+    return ",".join(segments)

pyfect/cron/_wall.py

@@ -0,0 +1,42 @@
+"""Wall-clock arithmetic with JavaScript ``Date``'s overflow rules, which
+Effect's cron search relies on: setting day 0 gives the previous month's
+last day, minute 60 the next hour, month 13 January of the next year.
+
+A wall-clock time is a naive ``datetime`` read in the cron's zone."""
+
+from __future__ import annotations
+
+import calendar
+from datetime import datetime, timedelta
+
+
+def with_fields(
+    wall: datetime,
+    *,
+    year: int | None = None,
+    month: int | None = None,
+    day: int | None = None,
+    hour: int | None = None,
+    minute: int | None = None,
+    second: int | None = None,
+) -> datetime:
+    """``wall`` with the given fields replaced, each free to overflow into
+    the next as with ``Date.UTC`` (months are 1-based). Sub-second parts
+    are dropped."""
+    carry, month_index = divmod((wall.month if month is None else month) - 1, 12)
+    first_of_month = datetime((wall.year if year is None else year) + carry, month_index + 1, 1)
+    return first_of_month + timedelta(
+        days=(wall.day if day is None else day) - 1,
+        hours=wall.hour if hour is None else hour,
+        minutes=wall.minute if minute is None else minute,
+        seconds=wall.second if second is None else second,
+    )
+
+
+def days_in_month(year: int, month: int) -> int:
+    return calendar.monthrange(year, month)[1]
+
+
+def weekday(wall: datetime) -> int:
+    """0 for Sunday to 6 for Saturday, as ``Date.getUTCDay``."""
+    return wall.isoweekday() % 7