jacobh2
6a79435baf
A hand-rolled month-arithmetic module survived the move to dateutil with no caller left but its own tests, and two predicates alongside it were never wired up at all. An error import was also being deferred inside a function for a circular dependency that does not exist.
227 lines
8.9 KiB
Python
227 lines
8.9 KiB
Python
"""Swedish calendar utilities for leave planning.
|
|
|
|
Single source of truth for "is this day free" across the app (planning
|
|
engine, tips engine). Backed by `app/data/swedish_calendar.json` — a
|
|
validated ~30-year cache (2026-2055) built from the Dagsmart API and
|
|
cross-checked against the `holidays` library. For years outside the cached
|
|
range, falls back to the `holidays` library directly; the fallback only
|
|
knows formal röda dagar (+ every Sunday), not de facto days or klämdagar.
|
|
|
|
Critical trap (see AGENTS.md): the `holidays` library returns *combined*
|
|
names when a fixed holiday lands on a Sunday, e.g. Easter Sunday is the
|
|
single string "Påskdagen; Söndag". Filtering by `"Söndag" in name` would
|
|
silently delete Påskdagen, Pingstdagen, Nationaldagen and Annandag jul
|
|
whenever they fall on a Sunday. Always match the *exact* string "Söndag".
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import datetime
|
|
import json
|
|
from pathlib import Path
|
|
from typing import Dict
|
|
|
|
import holidays
|
|
|
|
_CACHE_PATH = Path(__file__).resolve().parent.parent / "data" / "swedish_calendar.json"
|
|
|
|
# The generic "just a Sunday" marker. Exact-match only — see module docstring.
|
|
# Public so other modules (e.g. allocation_service) share this single
|
|
# constant instead of re-declaring the literal and risking drift.
|
|
SUNDAY_HOLIDAY_NAME = "Söndag"
|
|
_SUNDAY_HOLIDAY_NAME = SUNDAY_HOLIDAY_NAME
|
|
|
|
# Calendar-cache categories that represent a day off. `bridge_day` (klämdag)
|
|
# is deliberately excluded: those are `working_day: true` — cheap days to buy
|
|
# with a vacation day, not free days.
|
|
_FREE_CATEGORIES = {"public", "de_facto"}
|
|
|
|
_holiday_cache: Dict[int, Dict[datetime.date, str]] = {}
|
|
_raw_cache_by_year: Dict[int, list] | None = None
|
|
|
|
|
|
def _load_raw_cache() -> Dict[int, list]:
|
|
"""Lazily load & index `swedish_calendar.json` by year. Empty dict if the
|
|
cache file is missing (all years then fall back to the `holidays` lib)."""
|
|
global _raw_cache_by_year
|
|
if _raw_cache_by_year is None:
|
|
if _CACHE_PATH.exists():
|
|
with open(_CACHE_PATH, encoding="utf-8") as f:
|
|
data = json.load(f)
|
|
_raw_cache_by_year = {
|
|
year_data["year"]: year_data["days"] for year_data in data["years"]
|
|
}
|
|
else:
|
|
_raw_cache_by_year = {}
|
|
return _raw_cache_by_year
|
|
|
|
|
|
def _from_cache(year: int) -> Dict[datetime.date, str] | None:
|
|
"""Build the date->name map for `year` from the JSON cache.
|
|
|
|
Returns None if `year` isn't in the cached range (caller should fall
|
|
back to the `holidays` library).
|
|
|
|
Every Sunday is seeded with the bare "Söndag" marker (the cache itself
|
|
only lists *special* dates, not every ordinary Sunday) so downstream
|
|
free-day logic that predates this cache keeps working unchanged. A
|
|
public/de_facto entry that coincides with a Sunday is combined into
|
|
"<Name>; Söndag", mirroring the `holidays` library's own convention.
|
|
"""
|
|
days = _load_raw_cache().get(year)
|
|
if days is None:
|
|
return None
|
|
|
|
result: Dict[datetime.date, str] = {}
|
|
|
|
day = datetime.date(year, 1, 1)
|
|
one_day = datetime.timedelta(days=1)
|
|
while day.year == year:
|
|
if day.weekday() == 6: # Sunday
|
|
result[day] = _SUNDAY_HOLIDAY_NAME
|
|
day += one_day
|
|
|
|
for entry in days:
|
|
if entry["category"] not in _FREE_CATEGORIES:
|
|
continue
|
|
entry_date = datetime.date.fromisoformat(entry["date"])
|
|
name = entry["name_sv"].capitalize()
|
|
if entry_date in result: # coincides with the bare Sunday seeded above
|
|
name = f"{name}; {_SUNDAY_HOLIDAY_NAME}"
|
|
result[entry_date] = name
|
|
|
|
return result
|
|
|
|
|
|
def _from_library(year: int) -> Dict[datetime.date, str]:
|
|
"""Fallback for years outside the cached range: the `holidays` package.
|
|
|
|
Only knows formal röda dagar + every Sunday (the library's own
|
|
Sweden-specific quirk) — no de facto days, no klämdagar.
|
|
"""
|
|
se_holidays = holidays.Sweden(years=year, language="sv")
|
|
return dict(sorted(se_holidays.items()))
|
|
|
|
|
|
class UncachedYearError(RuntimeError):
|
|
"""Raised by a `strict=True` caller when `year` falls outside
|
|
`swedish_calendar.json`'s range (or the cache file is missing).
|
|
|
|
This should never fire in normal operation: `CalendarService` clamps its
|
|
requested window to `cached_year_bounds()` first, and the planning
|
|
engine's `AllocationInputLoader` surfaces this as a `ValidationError`
|
|
instead of letting it escape as a raw `RuntimeError` — see
|
|
`app.services.allocation_service.AllocationInputLoader.load`. Hitting
|
|
this in either caller is therefore a bug in that guard, not bad user
|
|
input — fail loudly instead of silently falling back to the `holidays`
|
|
library, which gives strictly poorer answers for the same dates (missing
|
|
de facto days like Julafton/Nyårsafton/Midsommarafton) and would defeat
|
|
the whole point of the cache (see module docstring; §6 offline/
|
|
deterministic guarantee).
|
|
"""
|
|
|
|
|
|
def get_swedish_holidays(year: int, *, strict: bool = False) -> Dict[datetime.date, str]:
|
|
"""Get all Swedish public holidays + de facto days + Sundays for a year.
|
|
|
|
Returns a mapping of date -> Swedish display name. Cached per year;
|
|
subsequent calls with the same year return the same object.
|
|
|
|
Args:
|
|
year: Calendar year (e.g., 2026)
|
|
strict: if True, raise `UncachedYearError` instead of silently
|
|
falling back to the `holidays` library when `year` is outside
|
|
the cached range. Checked before consulting the per-year cache
|
|
so a prior non-strict call for the same (uncached) year can
|
|
never mask a later strict call's check.
|
|
|
|
Returns:
|
|
Dict mapping datetime.date to holiday name (e.g. "Juldagen", "Julafton")
|
|
"""
|
|
if strict:
|
|
bounds = cached_year_bounds()
|
|
if bounds is None or not (bounds[0] <= year <= bounds[1]):
|
|
where = f"range {bounds[0]}-{bounds[1]}" if bounds is not None else "cache (missing)"
|
|
raise UncachedYearError(
|
|
f"Year {year} is outside the cached Swedish calendar {where}; "
|
|
"refusing to fall back to the live `holidays` library for a strict caller."
|
|
)
|
|
|
|
if year in _holiday_cache:
|
|
return _holiday_cache[year]
|
|
|
|
result = _from_cache(year)
|
|
if result is None:
|
|
result = _from_library(year)
|
|
|
|
_holiday_cache[year] = result
|
|
return result
|
|
|
|
|
|
def get_red_days(year: int, *, strict: bool = False) -> Dict[datetime.date, str]:
|
|
"""Real red days for `year`: public holidays and de facto days off,
|
|
EXCLUDING ordinary Sundays (the bare "Söndag" marker).
|
|
|
|
Matches the exact string only — "Påskdagen; Söndag" (a holiday that
|
|
happens to fall on a Sunday) is kept; only a standalone "Söndag" is
|
|
dropped. Use this (not `get_swedish_holidays`) for red-day cluster
|
|
detection, where a bare weekend must not be conflated with a real
|
|
holiday.
|
|
|
|
`strict` is forwarded to `get_swedish_holidays` — see there.
|
|
"""
|
|
return {
|
|
d: name
|
|
for d, name in get_swedish_holidays(year, strict=strict).items()
|
|
if name != _SUNDAY_HOLIDAY_NAME
|
|
}
|
|
|
|
|
|
def is_swedish_holiday(date: datetime.date) -> bool:
|
|
"""Check if a date is a Swedish public holiday, de facto day, or Sunday."""
|
|
holidays_for_year = get_swedish_holidays(date.year)
|
|
return date in holidays_for_year
|
|
|
|
|
|
def is_non_working_day(date: datetime.date) -> bool:
|
|
"""True if `date` is a weekend day, a public holiday, or a de facto day
|
|
off (julafton, midsommarafton, nyårsafton, ...).
|
|
|
|
This is the single source of truth for "is this an ordinary free day"
|
|
used by the planning engine and the tips engine. It does NOT know about
|
|
per-workspace `DayOverride`s — those are applied on top by the caller
|
|
(see `app.services.allocation_service.is_free_day`).
|
|
"""
|
|
if date.weekday() >= 5:
|
|
return True
|
|
return is_swedish_holiday(date)
|
|
|
|
|
|
def cached_year_bounds() -> tuple[int, int] | None:
|
|
"""(min_year, max_year) covered by `swedish_calendar.json`, or None if the
|
|
cache file is missing.
|
|
|
|
Used by `app.services.calendar_service` to validate/paginate the
|
|
calendar-days endpoint window without hardcoding the cached-year range.
|
|
"""
|
|
years = _load_raw_cache()
|
|
if not years:
|
|
return None
|
|
return min(years), max(years)
|
|
|
|
|
|
def is_klamdag(date: datetime.date) -> bool:
|
|
"""True if `date` is a klämdag: an ordinary working day sandwiched
|
|
between two non-working days (e.g. a Friday between a Thursday public
|
|
holiday and the weekend).
|
|
|
|
Verified against `swedish_calendar.json`'s `bridge_day` category: every
|
|
date flagged `bridge_day` satisfies this rule, and nothing else does.
|
|
Computed generically (not read from the cache) so it also works for
|
|
years outside the cached range.
|
|
"""
|
|
if is_non_working_day(date):
|
|
return False
|
|
one_day = datetime.timedelta(days=1)
|
|
return is_non_working_day(date - one_day) and is_non_working_day(date + one_day)
|