From 0566722e96d8ff61e814ad40cd632289aa33e95a Mon Sep 17 00:00:00 2001 From: Adam Moussa Date: Tue, 1 Sep 2026 19:56:07 -0400 Subject: [PATCH] docs(meals): clarify week-key dual-read is same-instant (PLAT-134) --- src/shared/shared/week_keys.py | 6 ++++++ tests/test_week_keys.py | 1 + 2 files changed, 7 insertions(+) diff --git a/src/shared/shared/week_keys.py b/src/shared/shared/week_keys.py index d546be2..e16cac6 100644 --- a/src/shared/shared/week_keys.py +++ b/src/shared/shared/week_keys.py @@ -24,6 +24,12 @@ def week_id_iso(dt: datetime) -> str: def candidate_week_ids(dt: datetime) -> tuple[str, ...]: + """Return U-week then ISO encodings of the same instant. + + Dual-read does not advance the calendar week. ``%Y-W%U`` and ``%G-W%V`` + are two strftime renderings of ``dt``. Example: 2026-01-01 encodes as + ("2026-W00", "2026-W01"), not as "this week" then "next week". + """ u_week = week_id_ustrftime(dt) iso_week = week_id_iso(dt) if u_week == iso_week: diff --git a/tests/test_week_keys.py b/tests/test_week_keys.py index 1400f81..ed2bce9 100644 --- a/tests/test_week_keys.py +++ b/tests/test_week_keys.py @@ -24,6 +24,7 @@ def test_ustrftime_and_iso_differ_on_new_year(): def test_candidate_week_ids_u_week_first_then_iso(): + # 2026-01-01: same instant encoded two ways, not a next-week lookup. assert candidate_week_ids(MISMATCH_DT) == ("2026-W00", "2026-W01")