holiplan 0.1.0__py3-none-any.whl

holiplan/engine/bridges.py

@@ -0,0 +1,116 @@
+"""Bridge days: the leave days that buy the most time off.
+
+The calendar splits into alternating runs of free days (weekends, public
+holidays) and gaps of workdays. Taking leave on one gap -- or on a few
+neighbouring gaps -- joins the free runs either side into one stretch off.
+Every such choice within the leave limit is an option, scored by days off per
+leave day. Only stretches with a public holiday on a workday count: without
+one, it's an ordinary long weekend, not a bridge.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Set as AbstractSet
+from dataclasses import dataclass
+from datetime import date, timedelta
+
+from .leave import daterange
+from .models import DayPattern
+
+# How far past the year's edges to look for free days to join onto.
+_MARGIN = timedelta(days=14)
+
+
+@dataclass
+class BridgeOption:
+    leave_dates: list[str]
+    leave_days: float
+    start: str  # first day off
+    end: str  # last day off
+    days_off: int
+    days_off_per_leave_day: float
+    public_holidays: list[str]  # the workday holidays that make it a bridge
+    school: str  # "holiday", "partly" or "term": whether the kids are off too
+
+    def as_dict(self) -> dict:
+        return self.__dict__.copy()
+
+
+def bridge_days(
+    year: int,
+    public_holidays: AbstractSet[str],
+    pattern: DayPattern | None = None,
+    half_holidays: AbstractSet[str] = frozenset(),
+    max_leave: float = 4,
+    school_windows: list[tuple[date, date]] | None = None,
+) -> list[BridgeOption]:
+    """Every bridge in `year` costing at most `max_leave`, best value first.
+
+    `public_holidays` should reach a couple of weeks past the year's edges so
+    stretches around New Year are measured correctly. `school_windows` are
+    effective (start, end) school holidays, used to say whether the children
+    are off during each option. Options may overlap; they are alternatives.
+    """
+    pattern = pattern or DayPattern()
+    first, last = date(year, 1, 1), date(year, 12, 31)
+
+    def free(day: date) -> bool:
+        return not pattern.is_workday(day) or day.isoformat() in public_holidays
+
+    def weight(day: date) -> float:
+        w = pattern.leave_weight(day)
+        return min(w, 0.5) if day.isoformat() in half_holidays else w
+
+    # Alternating runs: (is_free, [days]).
+    runs: list[tuple[bool, list[date]]] = []
+    for day in daterange(first - _MARGIN, last + _MARGIN):
+        if runs and runs[-1][0] == free(day):
+            runs[-1][1].append(day)
+        else:
+            runs.append((free(day), [day]))
+
+    options: list[BridgeOption] = []
+    for i, (is_free, _) in enumerate(runs):
+        if is_free or i == 0:
+            continue
+        leave: list[date] = []
+        for j in range(i, len(runs) - 1, 2):  # gaps i, i+2, ... with free runs between
+            leave += runs[j][1]
+            cost = sum(weight(d) for d in leave)
+            if cost > max_leave:
+                break
+            if leave[0] < first or leave[-1] > last:
+                continue
+            span = runs[i - 1][1][0], runs[j + 1][1][-1]
+            holidays = [
+                d.isoformat()
+                for d in daterange(*span)
+                if pattern.is_workday(d) and d.isoformat() in public_holidays
+            ]
+            if not holidays:
+                continue
+            days_off = (span[1] - span[0]).days + 1
+            options.append(
+                BridgeOption(
+                    leave_dates=[d.isoformat() for d in leave],
+                    leave_days=cost,
+                    start=span[0].isoformat(),
+                    end=span[1].isoformat(),
+                    days_off=days_off,
+                    days_off_per_leave_day=round(days_off / cost, 2),
+                    public_holidays=holidays,
+                    school=_school(span, school_windows),
+                )
+            )
+
+    options.sort(key=lambda o: (-o.days_off_per_leave_day, -o.days_off, o.start))
+    return options
+
+
+def _school(span: tuple[date, date], windows: list[tuple[date, date]] | None) -> str:
+    windows = windows or []
+    if any(start <= span[0] and span[1] <= end for start, end in windows):
+        return "holiday"
+    if any(start <= span[1] and span[0] <= end for start, end in windows):
+        return "partly"
+    return "term"

holiplan/engine/checks.py

@@ -0,0 +1,231 @@
+"""Constraint checks over a ledger, plus the deadlines it implies."""
+
+from __future__ import annotations
+
+from collections.abc import Set as AbstractSet
+from dataclasses import dataclass
+from datetime import date, timedelta
+
+from .leave import year_budget
+from .models import DayPattern, Ledger
+
+_MAX_STRETCH = 14  # days; real stretches are a weekend plus a holiday or two
+
+
+def effective_window(
+    start: date,
+    end: date,
+    public_holidays: set[str],
+    pattern: DayPattern | None = None,
+) -> tuple[date, date]:
+    """Stretch a school-holiday window over the free days that touch it.
+
+    Official windows usually run Monday to Friday, but families leave on the
+    Saturday before and come back on the Sunday after, and a public holiday on
+    either edge (Whit Monday before Bavaria's Pentecost window) adds a day more.
+    Walk outwards from each edge while the neighbouring day is a weekend or a
+    public holiday, at most `_MAX_STRETCH` days, so a pattern with no workdays
+    cannot walk forever.
+    """
+    pattern = pattern or DayPattern()
+
+    def free(day: date) -> bool:
+        return not pattern.is_workday(day) or day.isoformat() in public_holidays
+
+    for _ in range(_MAX_STRETCH):
+        if not free(start - timedelta(days=1)):
+            break
+        start -= timedelta(days=1)
+    for _ in range(_MAX_STRETCH):
+        if not free(end + timedelta(days=1)):
+            break
+        end += timedelta(days=1)
+    return start, end
+
+
+# A school holiday with this many school days or fewer is a closure (All Souls'
+# Day in Austria, Zürich's Ascension bridge), not a window to plan a trip around.
+CLOSURE_MAX_SCHOOL_DAYS = 2
+
+
+def describe_window(
+    name: str | None,
+    start: date,
+    end: date,
+    public_holidays: set[str],
+    groups: list[str] | None = None,
+) -> dict:
+    """A school holiday as the family sees it: raw dates, stretched dates, size.
+
+    `school_days` counts the Monday-to-Friday days inside the raw window that
+    aren't public holidays -- the days the holiday actually takes off school.
+    `groups` lists the school types it applies to where the data says (Zürich
+    splits primary, secondary and vocational); empty means every school.
+    """
+    eff_start, eff_end = effective_window(start, end, public_holidays)
+    school_days = sum(
+        1
+        for offset in range((end - start).days + 1)
+        if (day := start + timedelta(days=offset)).weekday() < 5
+        and day.isoformat() not in public_holidays
+    )
+    return {
+        "name": name,
+        "start": start.isoformat(),
+        "end": end.isoformat(),
+        "effective_start": eff_start.isoformat(),
+        "effective_end": eff_end.isoformat(),
+        "days_off": (eff_end - eff_start).days + 1,
+        "school_days": school_days,
+        "closure": school_days <= CLOSURE_MAX_SCHOOL_DAYS,
+        "groups": groups or [],
+    }
+
+
+@dataclass
+class Issue:
+    level: str  # "error" | "warning"
+    code: str
+    message: str
+    trip_ids: list[str]
+
+    def as_dict(self) -> dict:
+        return self.__dict__.copy()
+
+
+def validate_ledger(
+    ledger: Ledger,
+    public_holidays: set[str],
+    windows: list[dict] | None = None,
+    half_holidays: AbstractSet[str] = frozenset(),
+) -> list[dict]:
+    """Overlaps, budget breaches, bad dates, and trips outside school windows.
+
+    `windows` is an optional list of {"name", "start", "end"} school-holiday
+    windows; trips with intent "trip" that fall outside all of them are flagged
+    as a warning, since that usually means taking the kids out of school.
+    """
+    issues: list[Issue] = []
+    trips = [t for t in ledger.trips if t.status != "cancelled"]
+
+    for trip in trips:
+        if trip.end_date < trip.start_date:
+            issues.append(
+                Issue("error", "bad_dates", f"{trip.label}: end is before start.", [trip.id])
+            )
+
+    ordered = sorted(trips, key=lambda t: t.start_date)
+    for earlier, later in zip(ordered, ordered[1:]):
+        if later.start_date <= earlier.end_date:
+            issues.append(
+                Issue(
+                    "error",
+                    "overlap",
+                    f"{earlier.label} overlaps {later.label}.",
+                    [earlier.id, later.id],
+                )
+            )
+
+    if ledger.profile:
+        account_years = {a.year for a in ledger.profile.leave}
+        for trip in trips:
+            if not trip.consumes_leave or trip.end_date < trip.start_date:
+                continue
+            missing = sorted(
+                y for y in range(trip.start_date.year, trip.end_date.year + 1)
+                if y not in account_years
+            )
+            if missing:
+                years = ", ".join(str(y) for y in missing)
+                issues.append(
+                    Issue(
+                        "warning",
+                        "no_leave_account",
+                        f"{trip.label} takes leave in {years}, which has no leave account.",
+                        [trip.id],
+                    )
+                )
+        for account in ledger.profile.leave:
+            budget = year_budget(
+                ledger, account.year, public_holidays, half_holidays=half_holidays
+            )
+            for warning in budget.warnings:
+                level = "error" if warning.startswith("Over budget") else "warning"
+                code = "over_budget" if level == "error" else "carryover_at_risk"
+                issues.append(Issue(level, code, warning, []))
+
+    if windows:
+        pattern = ledger.profile.day_pattern if ledger.profile else None
+        spans = []
+        for w in windows:
+            start, end = effective_window(
+                date.fromisoformat(w["start"]),
+                date.fromisoformat(w["end"]),
+                public_holidays,
+                pattern,
+            )
+            spans.append((start, end, w.get("name", "window")))
+        for trip in trips:
+            if trip.intent != "trip":
+                continue
+            inside = any(
+                trip.start_date >= start and trip.end_date <= end for start, end, _ in spans
+            )
+            if not inside:
+                issues.append(
+                    Issue(
+                        "warning",
+                        "outside_school_window",
+                        f"{trip.label} is not fully inside a school holiday window.",
+                        [trip.id],
+                    )
+                )
+
+    return [i.as_dict() for i in issues]
+
+
+def deadlines(ledger: Ledger, today: date | None = None) -> list[dict]:
+    """Every dated action the ledger implies, soonest first."""
+    today = today or date.today()
+    out: list[dict] = []
+
+    for trip in ledger.trips:
+        if trip.status == "cancelled":
+            continue
+        for booking in trip.bookings:
+            if booking.book_by and booking.status == "todo":
+                out.append(
+                    {
+                        "due": booking.book_by,
+                        "kind": "book_by",
+                        "trip_id": trip.id,
+                        "message": f"Book {booking.what} for {trip.label}.",
+                        "overdue": date.fromisoformat(booking.book_by) < today,
+                    }
+                )
+            if booking.cancel_by and booking.status == "booked":
+                out.append(
+                    {
+                        "due": booking.cancel_by,
+                        "kind": "cancel_by",
+                        "trip_id": trip.id,
+                        "message": (
+                            f"Free cancellation for {booking.what} "
+                            f"({trip.label}) ends {booking.cancel_by}."
+                        ),
+                        "overdue": date.fromisoformat(booking.cancel_by) < today,
+                    }
+                )
+        # A week at home needs nothing booked; every other plan does.
+        if trip.status in ("idea", "locked") and not trip.bookings and trip.intent != "home":
+            out.append(
+                {
+                    "due": trip.start,
+                    "kind": "unbooked",
+                    "trip_id": trip.id,
+                    "message": f"{trip.label} has no bookings recorded.",
+                    "overdue": trip.start_date < today,
+                }
+            )
+
+    return sorted(out, key=lambda d: d["due"])

holiplan/engine/ics.py

@@ -0,0 +1,91 @@
+"""Minimal .ics export: all-day events for trips, plus VTODOs for deadlines."""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import date, datetime, timedelta, timezone
+
+from .models import Ledger
+
+PRODID = "-//holiplan//family holiday planner//EN"
+
+
+def _stamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def _esc(text: str) -> str:
+    return text.replace("\\", "\\\\").replace(";", "\\;").replace(",", "\\,").replace("\n", "\\n")
+
+
+def _fold(line: str) -> str:
+    """RFC 5545: lines of at most 75 octets, continuation lines start with a space.
+
+    Counted in UTF-8 bytes, never splitting a character, so umlauts stay intact.
+    """
+    lines: list[str] = []
+    current, size = "", 0
+    for char in line:
+        width = len(char.encode("utf-8"))
+        if size + width > 75:
+            lines.append(current)
+            current, size = " ", 1
+        current += char
+        size += width
+    lines.append(current)
+    return "\r\n".join(lines)
+
+
+def _deadline_uid(item: dict) -> str:
+    """Stable across exports, so re-importing updates a VTODO instead of duplicating it."""
+    key = f"{item['kind']}|{item['trip_id']}|{item['message']}".encode("utf-8")
+    return f"deadline-{hashlib.sha1(key).hexdigest()[:16]}@holiplan"
+
+
+def to_ics(ledger: Ledger, include_deadlines: bool = True) -> str:
+    from .checks import deadlines as compute_deadlines
+
+    lines = [
+        "BEGIN:VCALENDAR",
+        "VERSION:2.0",
+        f"PRODID:{PRODID}",
+        "CALSCALE:GREGORIAN",
+    ]
+
+    for trip in ledger.trips:
+        if trip.status == "cancelled":
+            continue
+        # DTEND is exclusive for all-day events
+        end_exclusive = (date.fromisoformat(trip.end) + timedelta(days=1)).strftime("%Y%m%d")
+        summary = trip.label if not trip.destination else f"{trip.label} ({trip.destination})"
+        lines += [
+            "BEGIN:VEVENT",
+            f"UID:{trip.id}@holiplan",
+            f"DTSTAMP:{_stamp()}",
+            f"DTSTART;VALUE=DATE:{date.fromisoformat(trip.start).strftime('%Y%m%d')}",
+            f"DTEND;VALUE=DATE:{end_exclusive}",
+            _fold(f"SUMMARY:{_esc(summary)}"),
+            f"STATUS:{'CONFIRMED' if trip.status == 'booked' else 'TENTATIVE'}",
+            "TRANSP:TRANSPARENT" if trip.intent == "home" else "TRANSP:OPAQUE",
+        ]
+        if trip.notes:
+            lines.append(_fold(f"DESCRIPTION:{_esc(trip.notes)}"))
+        if trip.destination:
+            lines.append(_fold(f"LOCATION:{_esc(trip.destination)}"))
+        lines.append("END:VEVENT")
+
+    if include_deadlines:
+        for item in compute_deadlines(ledger):
+            if item["kind"] == "unbooked":
+                continue
+            lines += [
+                "BEGIN:VTODO",
+                f"UID:{_deadline_uid(item)}",
+                f"DTSTAMP:{_stamp()}",
+                f"DUE;VALUE=DATE:{date.fromisoformat(item['due']).strftime('%Y%m%d')}",
+                _fold(f"SUMMARY:{_esc(item['message'])}"),
+                "END:VTODO",
+            ]
+
+    lines.append("END:VCALENDAR")
+    return "\r\n".join(lines) + "\r\n"

holiplan/engine/leave.py

@@ -0,0 +1,174 @@
+"""Leave arithmetic: what a trip costs, and what's left in the year.
+
+Holiday dates are passed in (a set of ISO date strings) so this module stays
+offline and deterministic. The OpenHolidays client supplies them at runtime.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Set as AbstractSet
+from dataclasses import dataclass, field
+from datetime import date, timedelta
+from typing import Iterable
+
+from .models import DayPattern, FamilyProfile, Ledger, Trip
+
+
+def daterange(start: date, end: date) -> Iterable[date]:
+    day = start
+    while day <= end:
+        yield day
+        day += timedelta(days=1)
+
+
+@dataclass
+class LeaveCost:
+    trip_id: str | None
+    start: str
+    end: str
+    days_away: int
+    leave_days: float
+    public_holidays_used: list[str]  # ISO dates that fell on a workday
+    weekend_days: int
+    half_day_holidays_used: list[str] = field(default_factory=list)  # afternoon off only
+
+    def as_dict(self) -> dict:
+        return {
+            "trip_id": self.trip_id,
+            "start": self.start,
+            "end": self.end,
+            "days_away": self.days_away,
+            "leave_days": self.leave_days,
+            "public_holidays_used": self.public_holidays_used,
+            "weekend_days": self.weekend_days,
+            "half_day_holidays_used": self.half_day_holidays_used,
+        }
+
+
+def leave_cost(
+    start: date,
+    end: date,
+    public_holidays: set[str],
+    pattern: DayPattern | None = None,
+    trip_id: str | None = None,
+    half_holidays: AbstractSet[str] = frozenset(),
+) -> LeaveCost:
+    """Leave days needed to be away from `start` to `end` inclusive.
+
+    `half_holidays` are public holidays that free only half the day (Zürich's
+    Sechseläuten), so a workday on one costs at most half a day of leave.
+    """
+    pattern = pattern or DayPattern()
+    total = 0.0
+    used: list[str] = []
+    half_used: list[str] = []
+    weekend = 0
+    days = 0
+
+    for day in daterange(start, end):
+        days += 1
+        iso = day.isoformat()
+        if not pattern.is_workday(day):
+            weekend += 1
+            continue
+        if iso in public_holidays:
+            used.append(iso)
+            continue
+        weight = pattern.leave_weight(day)
+        if iso in half_holidays:
+            half_used.append(iso)
+            weight = min(weight, 0.5)
+        total += weight
+
+    return LeaveCost(
+        trip_id=trip_id,
+        start=start.isoformat(),
+        end=end.isoformat(),
+        days_away=days,
+        leave_days=total,
+        public_holidays_used=used,
+        weekend_days=weekend,
+        half_day_holidays_used=half_used,
+    )
+
+
+@dataclass
+class YearBudget:
+    year: int
+    allowance: float
+    carryover: float
+    carryover_expires: str | None
+    planned: float
+    carryover_used_before_expiry: float
+    remaining: float
+    carryover_at_risk: float
+    warnings: list[str]
+
+    def as_dict(self) -> dict:
+        return self.__dict__.copy()
+
+
+def year_budget(
+    ledger: Ledger,
+    year: int,
+    public_holidays: set[str],
+    profile: FamilyProfile | None = None,
+    half_holidays: AbstractSet[str] = frozenset(),
+) -> YearBudget:
+    """Leave planned versus available for one year, including carryover expiry.
+
+    Carryover is treated as spent first, but only by trips that finish on or
+    before the expiry date -- that is what makes "use it before June" visible.
+    """
+    profile = profile or ledger.profile
+    if profile is None:
+        raise ValueError("ledger has no profile; pass one explicitly")
+
+    account = next((a for a in profile.leave if a.year == year), None)
+    if account is None:
+        raise ValueError(f"no leave account for {year}")
+
+    expiry = date.fromisoformat(account.carryover_expires) if account.carryover_expires else None
+
+    planned = 0.0
+    before_expiry = 0.0
+    warnings: list[str] = []
+
+    first_day, last_day = date(year, 1, 1), date(year, 12, 31)
+    for trip in ledger.trips:
+        if trip.status == "cancelled" or not trip.consumes_leave:
+            continue
+        # A trip over New Year spends each year's leave only on that year's days.
+        start, end = max(trip.start_date, first_day), min(trip.end_date, last_day)
+        if start > end:
+            continue
+        cost = leave_cost(
+            start, end, public_holidays, profile.day_pattern, trip.id, half_holidays
+        )
+        planned += cost.leave_days
+        if expiry and trip.end_date <= expiry:
+            before_expiry += cost.leave_days
+
+    carryover_used = min(account.carryover, before_expiry)
+    at_risk = round(account.carryover - carryover_used, 2)
+    remaining = round(account.allowance + account.carryover - planned, 2)
+
+    if remaining < 0:
+        warnings.append(f"Over budget by {abs(remaining)} days.")
+    if at_risk > 0 and expiry:
+        warnings.append(
+            f"{at_risk} carried-over day(s) expire on {expiry.isoformat()} "
+            "and no planned trip uses them."
+        )
+
+    return YearBudget(
+        year=year,
+        allowance=account.allowance,
+        carryover=account.carryover,
+        carryover_expires=account.carryover_expires,
+        planned=round(planned, 2),
+        carryover_used_before_expiry=round(carryover_used, 2),
+        remaining=remaining,
+        carryover_at_risk=at_risk,
+        warnings=warnings,
+    )