414 lines
17 KiB
Python
414 lines
17 KiB
Python
# DISPOSABLE CALENDAR-LIBRARY PROBE — NOT PRODUCTION CODE.
|
|
# See README.md in this directory. Requires croniter==6.2.4 and tzdata
|
|
# (plus apscheduler==3.11.0 for the Part B rejected-candidate evidence)
|
|
# on Python 3.14 (isolated env, not repo env).
|
|
"""Pin the croniter 6.2.4 calendar contract for deployment scheduling.
|
|
|
|
Policy: croniter owns calendar calculation, including DST resolution.
|
|
The adapter consumes it thinly — convert the query instant into the
|
|
schedule's named zone, ask for the next/previous occurrence, convert
|
|
the result to UTC — and applies no correction of its own. Each test
|
|
prints OBSERVED lines pinning 6.2.4 behavior. After any
|
|
calendar-dependency upgrade a failure IS the finding: re-probe, do not
|
|
hand-roll around it.
|
|
|
|
Part A pins the chosen-library contract (shipping acceptance).
|
|
Part B preserves rejected-candidate evidence (NOT acceptance).
|
|
|
|
Run:
|
|
uv run --project <isolated-probe-project> python -m pytest <this file>
|
|
-q -p no:cacheprovider -o addopts=""
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import time
|
|
from datetime import datetime, timedelta, timezone
|
|
|
|
import pytest
|
|
|
|
# This probe runs ONLY in the isolated calendar env (see README.md).
|
|
# Skip — do not error — when collected by a default repo test run.
|
|
pytest.importorskip("apscheduler", reason="isolated calendar-probe env only")
|
|
pytest.importorskip("croniter", reason="isolated calendar-probe env only")
|
|
|
|
from apscheduler.triggers.cron import CronTrigger # noqa: E402 (Part B only)
|
|
from croniter import ( # noqa: E402
|
|
CroniterBadCronError,
|
|
CroniterBadDateError,
|
|
)
|
|
from croniter import (
|
|
croniter as Croniter,
|
|
)
|
|
|
|
try: # noqa: E402
|
|
from zoneinfo import ZoneInfo
|
|
except ImportError: # pragma: no cover
|
|
from backports.zoneinfo import ZoneInfo # type: ignore[no-redef]
|
|
|
|
from importlib.metadata import version as _pkg_version # noqa: E402
|
|
|
|
import apscheduler # noqa: E402
|
|
|
|
CRONITER_VERSION = _pkg_version("croniter")
|
|
|
|
print(f"croniter=={CRONITER_VERSION}")
|
|
print(f"apscheduler=={apscheduler.__version__} (rejected candidate, Part B only)")
|
|
|
|
UTC = timezone.utc
|
|
HCMC = ZoneInfo("Asia/Ho_Chi_Minh")
|
|
NYC = ZoneInfo("America/New_York")
|
|
|
|
# 2026 DST transitions (US): spring forward 2026-03-08 02:00 -> 03:00,
|
|
# fall back 2026-11-01 02:00 -> 01:00.
|
|
|
|
|
|
def utc(*args) -> datetime:
|
|
return datetime(*args, tzinfo=UTC)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Part A — chosen-library contract (croniter; shipping acceptance)
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
def test_versions_pinned():
|
|
print(f"OBSERVED croniter version={CRONITER_VERSION}")
|
|
print(f"OBSERVED apscheduler.__version__={apscheduler.__version__}")
|
|
# Exact pin: a calendar-dependency upgrade must fail here deliberately,
|
|
# forcing a re-probe before any pin update.
|
|
assert CRONITER_VERSION == "6.2.4"
|
|
assert apscheduler.__version__.startswith("3.")
|
|
|
|
|
|
def test_utc_daily_next_is_strictly_increasing_and_unique():
|
|
it = Croniter("30 9 * * *", utc(2026, 9, 1, 0, 0, 0))
|
|
seen: set[datetime] = set()
|
|
prev = None
|
|
for _ in range(10):
|
|
nxt = it.get_next(datetime)
|
|
assert nxt.tzinfo is not None
|
|
as_utc = nxt.astimezone(UTC)
|
|
assert as_utc not in seen, f"duplicate UTC instant {as_utc}"
|
|
seen.add(as_utc)
|
|
if prev is not None:
|
|
assert as_utc > prev, "not strictly increasing"
|
|
print(f"OBSERVED utc-daily next={as_utc.isoformat()}")
|
|
prev = as_utc
|
|
assert len(seen) == 10
|
|
|
|
|
|
def test_hcmc_daily_converts_and_hourly_counts():
|
|
# Asia/Ho_Chi_Minh is UTC+7 with no DST. 09:30 local == 02:30 UTC.
|
|
nxt = Croniter("30 9 * * *", datetime(2026, 9, 1, 0, 0, tzinfo=HCMC)).get_next(
|
|
datetime
|
|
)
|
|
as_utc = nxt.astimezone(UTC)
|
|
print(f"OBSERVED hcmc next local={nxt.isoformat()} utc={as_utc.isoformat()}")
|
|
assert (as_utc.hour, as_utc.minute) == (2, 30)
|
|
assert as_utc.date().isoformat() == "2026-09-01"
|
|
# No-DST zone: hourly occurrence count over two 48-hour windows
|
|
# (March and November, starting off-tick) must be exactly 48 each.
|
|
for label, start in (
|
|
("march", utc(2026, 3, 7, 17, 30, 0)),
|
|
("november", utc(2026, 10, 31, 17, 30, 0)),
|
|
):
|
|
it = Croniter("0 * * * *", start.astimezone(HCMC))
|
|
count = 0
|
|
while True:
|
|
hit = it.get_next(datetime).astimezone(UTC)
|
|
if hit >= start + timedelta(hours=48):
|
|
break
|
|
count += 1
|
|
assert count < 60
|
|
print(f"OBSERVED hcmc hourly count window={label} count={count}")
|
|
assert count == 48, f"{label}: no-DST zone must yield exactly 48, got {count}"
|
|
|
|
|
|
def test_expression_forms_wildcard_step_list_range():
|
|
"""Wildcards, steps, lists, and ranges resolve through plain
|
|
get_next on an ordinary day (no DST involved)."""
|
|
cases = {
|
|
"* * * * *": (datetime(2026, 9, 8, 0, 0, tzinfo=UTC), "2026-09-08T00:01:00"),
|
|
"5/15 * * * *": (datetime(2026, 9, 8, 0, 0, tzinfo=UTC), "2026-09-08T00:05:00"),
|
|
"0,30 1-2 * * *": (
|
|
datetime(2026, 9, 8, 0, 0, tzinfo=UTC),
|
|
"2026-09-08T01:00:00",
|
|
),
|
|
"*/20 1-3 * * *": (
|
|
datetime(2026, 9, 8, 1, 50, tzinfo=UTC),
|
|
"2026-09-08T02:00:00",
|
|
),
|
|
}
|
|
for expr, (start, want) in cases.items():
|
|
nxt = Croniter(expr, start).get_next(datetime)
|
|
print(
|
|
f"OBSERVED croniter {expr!r} from {start.isoformat()} -> {nxt.isoformat()}"
|
|
)
|
|
assert nxt.astimezone(UTC).isoformat() == want + "+00:00"
|
|
|
|
|
|
def test_weekday_names_and_numbers_unix():
|
|
"""Pin croniter 6.2.4 weekday dialect (re-probe on upgrade). Unix
|
|
convention: numeric 0 AND 7 mean Sunday; 1/mon mean Monday."""
|
|
monday = datetime(2026, 9, 7, 0, 0, tzinfo=UTC) # a Monday
|
|
cases = {
|
|
"0 12 * * 0": 6, # Sunday
|
|
"0 12 * * 7": 6, # Sunday (alias)
|
|
"0 12 * * 1": 0, # Monday
|
|
"0 12 * * mon": 0,
|
|
"0 12 * * sun": 6,
|
|
}
|
|
for expr, want_wd in cases.items():
|
|
nxt = Croniter(expr, monday).get_next(datetime)
|
|
print(
|
|
f"OBSERVED croniter {expr!r} -> {nxt.date().isoformat()} weekday={nxt.weekday()}"
|
|
)
|
|
assert nxt.weekday() == want_wd, f"{expr}: want weekday={want_wd}"
|
|
assert Croniter("0 12 * * 0", monday).get_next(datetime) == Croniter(
|
|
"0 12 * * sun", monday
|
|
).get_next(datetime)
|
|
|
|
|
|
def test_dom_dow_day_or_true_is_selected():
|
|
"""Day-of-month/day-of-week uses croniter's standard day_or=True
|
|
(Unix OR). The alternative (AND) is pinned for reference only."""
|
|
start = datetime(2026, 9, 1, 0, 0, tzinfo=UTC)
|
|
it_or = Croniter("0 12 13 * fri", start, day_or=True)
|
|
hits_or = [it_or.get_next(datetime).date().isoformat() for _ in range(4)]
|
|
print(f"OBSERVED croniter day_or=True hits={hits_or}")
|
|
# Fridays plus the 13th (a Sunday): classic Unix OR.
|
|
assert hits_or == ["2026-09-04", "2026-09-11", "2026-09-13", "2026-09-18"]
|
|
it_and = Croniter("0 12 13 * fri", start, day_or=False)
|
|
first_and = it_and.get_next(datetime).date()
|
|
print(
|
|
f"OBSERVED croniter day_or=False first={first_and.isoformat()} (not selected)"
|
|
)
|
|
assert (first_and.day, first_and.weekday()) == (13, 4)
|
|
|
|
|
|
def test_zone_conversion_is_the_callers_job():
|
|
"""croniter iterates in the tz of the supplied datetime and performs
|
|
no conversion: a UTC start yields UTC results. The adapter converts
|
|
now into the schedule zone before querying and back to UTC after."""
|
|
utc_start = Croniter(
|
|
"30 2 * * *", datetime(2026, 3, 7, 12, 0, tzinfo=UTC)
|
|
).get_next(datetime)
|
|
print(
|
|
f"OBSERVED croniter utc-start gap next={utc_start.isoformat()} (no zone conversion)"
|
|
)
|
|
assert utc_start.tzinfo is UTC
|
|
hcmc_start = Croniter(
|
|
"30 9 * * *", datetime(2026, 9, 1, 0, 0, tzinfo=HCMC)
|
|
).get_next(datetime)
|
|
print(f"OBSERVED croniter hcmc-start next={hcmc_start.isoformat()}")
|
|
assert hcmc_start.utcoffset() == timedelta(hours=7)
|
|
|
|
|
|
def test_gap_nonexistent_wall_times_resolve_forward():
|
|
"""Observed 6.2.4 gap behavior: daily 02:30 on 2026-03-08 (a wall
|
|
time that never existed in America/New_York) resolves to 03:00-04:00
|
|
the same day. That resolution IS the occurrence — there is no
|
|
separate validity concept and no day is skipped over."""
|
|
first = Croniter("30 2 * * *", datetime(2026, 3, 7, 12, 0, tzinfo=NYC)).get_next(
|
|
datetime
|
|
)
|
|
print(f"OBSERVED croniter gap-day daily-0230 resolves={first.isoformat()}")
|
|
assert first.isoformat() == "2026-03-08T03:00:00-04:00"
|
|
following = Croniter("30 2 * * *", first).get_next(datetime)
|
|
print(f"OBSERVED croniter gap following={following.isoformat()}")
|
|
assert following.isoformat() == "2026-03-09T02:30:00-04:00"
|
|
|
|
|
|
def test_gap_per_minute_stream_jumps_forward():
|
|
"""Per-minute iteration across the spring gap jumps 01:59 EST
|
|
straight to 03:00 EDT: no 02:xx wall times are emitted, UTC is
|
|
strictly increasing and unique."""
|
|
it = Croniter("* * * * *", datetime(2026, 3, 8, 0, 0, tzinfo=NYC))
|
|
seq = [it.get_next(datetime) for _ in range(300)]
|
|
us = [d.astimezone(UTC) for d in seq]
|
|
assert all(b > a for a, b in zip(us, us[1:]))
|
|
assert len(set(us)) == len(us)
|
|
gap_day = [d for d in seq if d.date().isoformat() == "2026-03-08"]
|
|
assert all(d.hour != 2 for d in gap_day), "no 02:xx wall times emitted"
|
|
assert "2026-03-08T01:59:00-05:00" in (d.isoformat() for d in gap_day)
|
|
assert "2026-03-08T03:00:00-04:00" in (d.isoformat() for d in gap_day)
|
|
print(
|
|
"OBSERVED per-minute gap jump 01:59-05:00 -> 03:00-04:00, "
|
|
f"{len(gap_day)} gap-day hits"
|
|
)
|
|
|
|
|
|
def test_gap_backward_queries_return_library_resolution():
|
|
"""Backward queries resolve the same way: get_prev on the gap day
|
|
returns the forward-resolved 03:00-04:00, not a skipped-over day.
|
|
Latest-missed on a gap day is that resolved instant."""
|
|
cases = {
|
|
"2026-03-08T12:00": "2026-03-08T03:00:00-04:00",
|
|
"2026-03-09T00:00": "2026-03-08T03:00:00-04:00",
|
|
"2026-03-07T12:00": "2026-03-07T02:30:00-05:00",
|
|
"2026-03-09T12:00": "2026-03-09T02:30:00-04:00",
|
|
}
|
|
for start_iso, want in cases.items():
|
|
start = datetime.fromisoformat(start_iso).replace(tzinfo=NYC)
|
|
got = Croniter("30 2 * * *", start).get_prev(datetime)
|
|
print(f"OBSERVED croniter gap get_prev from {start_iso} -> {got.isoformat()}")
|
|
assert got.isoformat() == want
|
|
|
|
|
|
def test_fold_repeated_times_are_distinct_utc():
|
|
"""Both 01:30s on 2026-11-01 occur as distinct UTC instants
|
|
(05:30Z EDT, then 06:30Z EST)."""
|
|
it = Croniter("30 1 * * *", datetime(2026, 10, 31, 12, 0, tzinfo=NYC))
|
|
first = it.get_next(datetime)
|
|
second = it.get_next(datetime)
|
|
print(
|
|
f"OBSERVED croniter fold first={first.isoformat()} second={second.isoformat()}"
|
|
)
|
|
assert first.astimezone(UTC) == utc(2026, 11, 1, 5, 30)
|
|
assert second.astimezone(UTC) == utc(2026, 11, 1, 6, 30)
|
|
|
|
|
|
def test_fold_per_minute_unique_increasing():
|
|
"""Per-minute iteration across the fall fold emits both fold hours
|
|
with strictly increasing unique UTC instants."""
|
|
it = Croniter("* * * * *", datetime(2026, 10, 31, 20, 0, tzinfo=NYC))
|
|
seq = [it.get_next(datetime) for _ in range(560)]
|
|
us = [d.astimezone(UTC) for d in seq]
|
|
print(f"OBSERVED croniter fold-span count={len(us)} last={us[-1].isoformat()}")
|
|
assert all(b > a for a, b in zip(us, us[1:])), "must be strictly increasing"
|
|
assert len(set(us)) == len(us), "UTC identities must be unique"
|
|
iso = {d.isoformat() for d in us}
|
|
assert "2026-11-01T05:30:00+00:00" in iso, "first 01:30 (EDT) must occur"
|
|
assert "2026-11-01T06:30:00+00:00" in iso, "second 01:30 (EST) must occur"
|
|
|
|
|
|
def test_latest_missed_after_years_of_downtime():
|
|
"""Per-minute schedule, ~3 years of downtime: get_prev answers the
|
|
latest missed occurrence directly — no enumeration of missed years."""
|
|
now = utc(2026, 9, 8, 12, 0, 0)
|
|
t0 = time.perf_counter()
|
|
latest = Croniter("* * * * *", now).get_prev(datetime)
|
|
elapsed = time.perf_counter() - t0
|
|
print(
|
|
f"OBSERVED croniter get_prev({now.isoformat()})={latest.isoformat()} "
|
|
f"elapsed={elapsed:.4f}s"
|
|
)
|
|
assert latest.tzinfo is not None, "get_prev must preserve tz-awareness"
|
|
assert elapsed < 5, "latest-missed lookup must be bounded"
|
|
assert latest <= now
|
|
assert (now - latest) < timedelta(minutes=2)
|
|
now_nyc = datetime(2026, 9, 8, 12, 0, tzinfo=NYC)
|
|
latest_nyc = Croniter("* * * * *", now_nyc).get_prev(datetime)
|
|
print(
|
|
f"OBSERVED croniter nyc get_prev now={now_nyc.isoformat()} "
|
|
f"latest={latest_nyc.isoformat()}"
|
|
)
|
|
assert latest_nyc.tzinfo is not None
|
|
assert latest_nyc <= now_nyc
|
|
assert (now_nyc - latest_nyc) < timedelta(minutes=2)
|
|
assert latest_nyc.astimezone(UTC).isoformat() == "2026-09-08T15:59:00+00:00"
|
|
|
|
|
|
def test_iteration_is_exclusive_both_directions():
|
|
"""Both get_next and get_prev are exclusive of their start: a query
|
|
from exactly a due instant returns the neighboring occurrence, not
|
|
the instant itself. Adapter consequence (T01, not enforced here):
|
|
query forward from the last-consumed instant and compare catch-up
|
|
results against the same watermark, so a due occurrence is admitted
|
|
exactly once — neither missed by exclusivity nor admitted twice."""
|
|
due = utc(2026, 9, 8, 13, 0, 0)
|
|
fwd = Croniter("0 13 * * *", due).get_next(datetime)
|
|
back = Croniter("0 13 * * *", due).get_prev(datetime)
|
|
print(f"OBSERVED exclusive get_next(due)={fwd.isoformat()}")
|
|
print(f"OBSERVED exclusive get_prev(due)={back.isoformat()}")
|
|
assert fwd.astimezone(UTC) == utc(2026, 9, 9, 13, 0, 0)
|
|
assert (back.year, back.month, back.day, back.hour, back.minute) == (
|
|
2026,
|
|
9,
|
|
7,
|
|
13,
|
|
0,
|
|
)
|
|
just_before = Croniter("0 13 * * *", due - timedelta(seconds=1)).get_next(datetime)
|
|
assert just_before.astimezone(UTC) == due, "a tick just before due admits it"
|
|
|
|
|
|
def test_impossible_schedule_raises_promptly():
|
|
"""February 30th never occurs: the library raises its documented
|
|
exhaustion error promptly instead of searching forever. The adapter
|
|
maps this to exhausted — exhaustion must never look like progress."""
|
|
start = time.perf_counter()
|
|
with pytest.raises(CroniterBadDateError):
|
|
Croniter("0 12 30 2 *", utc(2026, 1, 1)).get_next(datetime)
|
|
elapsed = time.perf_counter() - start
|
|
print(
|
|
f"OBSERVED impossible-schedule raised CroniterBadDateError elapsed={elapsed:.3f}s"
|
|
)
|
|
assert elapsed < 5, f"search must be bounded, took {elapsed:.1f}s"
|
|
|
|
|
|
def test_bad_expressions_rejected_naive_passes_through():
|
|
"""Malformed expressions fail at construction with a documented
|
|
error. Naive datetimes are NOT rejected by the library — they pass
|
|
straight through — so the adapter rejects naive itself per spec."""
|
|
with pytest.raises(CroniterBadCronError):
|
|
Croniter("nonsense", utc(2026, 1, 1))
|
|
print("OBSERVED malformed expression rejected with CroniterBadCronError")
|
|
naive = Croniter("* * * * *", datetime(2026, 9, 8, 12, 0)).get_next(datetime)
|
|
print(f"OBSERVED naive start passes through tzinfo={naive.tzinfo}")
|
|
assert naive.tzinfo is None
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Part B — rejected-candidate evidence (APScheduler; NOT acceptance)
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
@pytest.mark.xfail(
|
|
strict=True,
|
|
reason="REJECTED CANDIDATE: APScheduler 3.11.0 fabricates a phantom "
|
|
"02:30-05:00 for the DST gap. Kept as evidence for the rejection; "
|
|
"the chosen library's gap behavior is pinned in Part A. Strict so "
|
|
"re-opening the candidacy fails loudly. See implementation plan.",
|
|
)
|
|
def test_rejected_candidate_gap_phantom():
|
|
# 02:30 does not exist in America/New_York on 2026-03-08. The
|
|
# disqualifier is the phantom itself: whatever the library returns
|
|
# must not be a nonexistent wall time.
|
|
trig = CronTrigger(hour=2, minute=30, second=0, timezone="America/New_York")
|
|
nxt = trig.get_next_fire_time(None, utc(2026, 3, 7, 12, 0, 0))
|
|
assert nxt is not None
|
|
local = nxt.astimezone(NYC)
|
|
print(f"OBSERVED apscheduler dst-gap next local={local.isoformat()}")
|
|
assert not (
|
|
(local.year, local.month, local.day) == (2026, 3, 8) and local.hour == 2
|
|
), f"library must not fabricate a nonexistent wall time, got {local.isoformat()}"
|
|
|
|
|
|
@pytest.mark.xfail(
|
|
strict=True,
|
|
reason="REJECTED CANDIDATE: APScheduler 3.11.0 replays 05:01Z-06:00Z "
|
|
"(~59 past minutes) after the fall fold, duplicating UTC occurrence "
|
|
"identities. Kept as evidence for the rejection; the chosen "
|
|
"library's fold behavior is pinned in Part A. See implementation plan.",
|
|
)
|
|
def test_rejected_candidate_fold_replay():
|
|
trig = CronTrigger(minute="*", second=0, timezone="America/New_York")
|
|
now = utc(2026, 11, 1, 0, 0, 0)
|
|
prev = None
|
|
seen: set[str] = set()
|
|
last: datetime | None = None
|
|
for _ in range(450): # spans past 07:00Z: covers BOTH fold hours
|
|
nxt = trig.get_next_fire_time(prev, now)
|
|
assert nxt is not None
|
|
as_utc = nxt.astimezone(UTC)
|
|
ident = f"sched-1|{as_utc.isoformat()}"
|
|
assert ident not in seen, f"duplicate occurrence identity {ident}"
|
|
seen.add(ident)
|
|
if last is not None:
|
|
assert as_utc > last, "occurrences must be strictly increasing"
|
|
last = as_utc
|
|
prev, now = nxt, nxt
|
|
print(f"OBSERVED fold-span count={len(seen)} unique, last={last.isoformat()}")
|