"""Cron expressions: what they mean, when they fire next, and as systemd ``OnCalendar``. One module answers all three, because a job netOrk writes as a timer must fire exactly when the cron expression the user gave says, and the preview must show the same runs the host will make (NetOrk/netork#1933). """ from __future__ import annotations from datetime import UTC, datetime from zoneinfo import ZoneInfo import pytest from napalm_device_types.cron import is_reboot, next_runs, parse_cron, to_on_calendar BERLIN = ZoneInfo("Europe/Berlin") class TestParse: def test_every_field_is_expanded_to_its_values(self): s = parse_cron("*/15 6-8 1,15 * *") assert s.minutes == frozenset({0, 15, 30, 45}) assert s.hours == frozenset({6, 7, 8}) assert s.days == frozenset({1, 15}) assert s.months == frozenset(range(1, 13)) assert s.weekdays == frozenset(range(7)) def test_a_range_takes_a_step(self): assert parse_cron("1-30/10 * * * *").minutes == frozenset({1, 11, 21}) def test_names_are_months_and_weekdays_in_any_case(self): s = parse_cron("0 0 * Jan,MAR mon-Fri") assert s.months == frozenset({1, 3}) assert s.weekdays == frozenset({1, 2, 3, 4, 5}) def test_seven_is_sunday_too(self): assert parse_cron("0 0 * * 7").weekdays == frozenset({0}) @pytest.mark.parametrize( ("alias", "expanded"), [ ("@hourly", "0 * * * *"), ("@daily", "0 0 * * *"), ("@midnight", "0 0 * * *"), ("@weekly", "0 0 * * 0"), ("@monthly", "0 0 1 * *"), ("@yearly", "0 0 1 1 *"), ("@annually", "0 0 1 1 *"), ], ) def test_an_alias_is_its_expression(self, alias, expanded): assert parse_cron(alias) == parse_cron(expanded) def test_reboot_is_no_calendar(self): assert is_reboot("@reboot") assert not is_reboot("0 0 * * *") with pytest.raises(ValueError, match="reboot"): parse_cron("@reboot") @pytest.mark.parametrize( "bad", [ "", "* * * *", "* * * * * *", "60 * * * *", "* 24 * * *", "* * 0 * *", "* * * 13 *", "* * * * 8", "*/0 * * * *", "5-1 * * * *", "a * * * *", "@often", "1,,2 * * * *", ], ) def test_what_cron_would_not_take_is_refused(self, bad): with pytest.raises(ValueError): parse_cron(bad) def test_day_of_month_and_weekday_are_or_only_when_both_are_restricted(self): assert parse_cron("0 0 1 * 1").either_day assert not parse_cron("0 0 */2 * 1").either_day assert not parse_cron("0 0 1 * *").either_day class TestNextRuns: def test_runs_after_the_instant_in_the_hosts_time(self): after = datetime(2026, 11, 3, 5, 50, tzinfo=UTC) # 06:50 in Berlin runs = next_runs("0 7 * * *", after, BERLIN, count=2) assert runs == [ datetime(2026, 11, 3, 7, 0, tzinfo=BERLIN), datetime(2026, 11, 4, 7, 0, tzinfo=BERLIN), ] def test_the_instant_itself_is_not_a_next_run(self): after = datetime(2026, 11, 3, 6, 0, tzinfo=UTC) assert next_runs("0 6 * * *", after, ZoneInfo("UTC"), count=1)[0].day == 4 def test_either_day_fires_on_both(self): after = datetime(2026, 11, 30, 12, 0, tzinfo=UTC) # a Monday runs = next_runs("0 0 1 * 1", after, ZoneInfo("UTC"), count=3) assert [r.day for r in runs] == [1, 7, 14] def test_a_day_that_never_comes_gives_no_runs(self): assert next_runs("0 0 31 2 *", datetime(2026, 1, 1, tzinfo=UTC), BERLIN) == [] def test_a_time_the_clock_skips_is_left_out(self): # 2026-03-29 02:30 does not exist in Berlin. after = datetime(2026, 3, 28, 12, 0, tzinfo=UTC) runs = next_runs("30 2 * * *", after, BERLIN, count=2) assert [r.day for r in runs] == [30, 31] def test_reboot_has_no_next_run(self): assert next_runs("@reboot", datetime(2026, 1, 1, tzinfo=UTC), BERLIN) == [] class TestOnCalendar: def test_every_field_as_its_values(self): assert to_on_calendar("*/15 6 * * *") == ["*-*-* 06:00,15,30,45:00"] def test_a_restricted_weekday_leads(self): assert to_on_calendar("30 4 * * 1-5") == ["Mon,Tue,Wed,Thu,Fri *-*-* 04:30:00"] def test_months_and_days(self): assert to_on_calendar("0 0 1,15 1,7 *") == ["*-01,07-01,15 00:00:00"] def test_either_day_is_two_lines(self): assert to_on_calendar("0 0 1 * 0") == ["*-*-01 00:00:00", "Sun *-*-* 00:00:00"] def test_both_days_with_a_star_are_one_line(self): assert to_on_calendar("0 0 */10 * 6") == ["Sat *-*-01,11,21,31 00:00:00"] def test_an_alias(self): assert to_on_calendar("@daily") == ["*-*-* 00:00:00"] def test_reboot_is_refused(self): with pytest.raises(ValueError, match="reboot"): to_on_calendar("@reboot")