layover 0.1.0.dev0__py3-none-any.whl

layover/cost/lounge.py

@@ -0,0 +1,110 @@
+"""Lounge access as a scarce budget (DESIGN §8.2).
+
+The owner's programme is DragonPass with a free annual quota *per traveller*, so a
+lounge visit is neither free nor priced at the walk-in rate: its marginal cost is
+the chance that this is the visit you would have wanted later in the membership
+year. That is a shadow price, and it is zero for most of the year.
+
+Access only counts where the lounge is in the terminal the plan actually uses — a
+DragonPass listing on the other side of an airport is not access.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from layover.prefs.profile import LoungePrefs
+from layover.prefs.travelers import Traveler
+
+
+@dataclass(frozen=True, slots=True)
+class LoungeDecision:
+    """What we assumed about a lounge, in terms a human can argue with."""
+
+    used: bool
+    cost: float
+    wait_factor: float
+    note: str
+    consumes_quota: bool = False
+
+
+SCARCE_ENTRIES = 2
+"""At or below this many free entries left, one is worth the full walk-in price."""
+
+
+def quota_shadow_price(traveler: Traveler, prefs: LoungePrefs) -> float:
+    """What spending one free entry costs, given how many are left.
+
+    Zero while entries are plentiful, rising linearly to the walk-in price as the
+    quota empties. "Plentiful" is the smaller of half the annual quota and half a
+    year's trips: with 10 entries against ~8 trips a year, roughly 4 trips are
+    still ahead on average, so entries only start to feel scarce below 4.
+
+    A frequent flyer (high `trips_per_year`) therefore starts economising earlier,
+    which is the intended behaviour — the quota is the constraint, not the calendar.
+    """
+    lounge = traveler.lounge
+    if not lounge.has_program or lounge.quota_remaining <= 0:
+        return prefs.overage_price
+
+    remaining = lounge.quota_remaining
+    ramp_start = max(SCARCE_ENTRIES, min(lounge.annual_quota / 2, prefs.trips_per_year / 2))
+
+    if remaining > ramp_start:
+        return 0.0
+    if remaining <= SCARCE_ENTRIES:
+        return prefs.overage_price
+
+    span = ramp_start - SCARCE_ENTRIES
+    fraction = (ramp_start - remaining) / span
+    return round(prefs.overage_price * fraction, 2)
+
+
+def decide(
+    traveler: Traveler,
+    *,
+    wait_hours: float,
+    dead_time_cost: float,
+    has_lounge_here: bool,
+    prefs: LoungePrefs,
+    policy: str = "if_worth_it",
+) -> LoungeDecision:
+    """Decide, per traveller, whether this wait happens in a lounge.
+
+    `dead_time_cost` is what the wait costs without a lounge, so the comparison is
+    always "does paying beat waiting?" rather than an abstract preference.
+    """
+    if not has_lounge_here:
+        return LoungeDecision(False, 0.0, 1.0, "no lounge access in this terminal")
+    if wait_hours < prefs.min_wait_to_use_h:
+        return LoungeDecision(
+            False, 0.0, 1.0, f"wait under {prefs.min_wait_to_use_h:g}h — not worth the walk"
+        )
+    if policy == "never":
+        return LoungeDecision(False, 0.0, 1.0, "lounge use disabled for this run")
+
+    discounted = dead_time_cost * prefs.wait_factor
+    remaining = traveler.lounge.quota_remaining
+
+    if remaining > 0:
+        price = quota_shadow_price(traveler, prefs)
+        if price + discounted < dead_time_cost:
+            note = (
+                f"free DragonPass entry ({remaining - 1} left after this)"
+                if price == 0
+                else f"free entry, shadow-priced {price:.0f} ({remaining - 1} left)"
+            )
+            return LoungeDecision(True, price, prefs.wait_factor, note, consumes_quota=True)
+        return LoungeDecision(False, 0.0, 1.0, "free entry not worth spending on this wait")
+
+    price = prefs.overage_price
+    if price + discounted < dead_time_cost:
+        return LoungeDecision(
+            True, price, prefs.wait_factor, f"paid entry {price:.0f} (annual quota used up)"
+        )
+    return LoungeDecision(
+        False,
+        0.0,
+        1.0,
+        f"paid entry {price:.0f} does not pay for itself on a {wait_hours:.1f}h wait",
+    )

layover/currency.py

@@ -0,0 +1,166 @@
+"""Currency normalization (DESIGN §9).
+
+Every price is compared in one currency, converted at the ECB's daily reference
+rates. The rule that matters is what happens when a rate is missing: **refuse**. ECB
+does not publish every currency a point-of-sale probe can return, and a guessed
+cross-rate is worse than an absent one — it produces a number that looks comparable
+and is not. Such offers keep their original currency, get no normalized price, and
+are listed separately as uncomparable.
+
+Rates are cached on disk for the day. Nothing here is offer data, so the cache is
+allowed to outlive a session.
+"""
+
+from __future__ import annotations
+
+import json
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime
+from pathlib import Path
+
+ECB_DAILY_URL = "https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml"
+_NS = {
+    "gesmes": "http://www.gesmes.org/xml/2002-08-01",
+    "ecb": "http://www.ecb.int/vocabulary/2002-08-01/eurofxref",
+}
+
+
+class MissingRate(LookupError):
+    """No reference rate for this currency. Deliberately not recoverable by guessing."""
+
+
+@dataclass(frozen=True, slots=True)
+class Rates:
+    """EUR-based reference rates for one day."""
+
+    as_of: date
+    per_eur: dict[str, float] = field(default_factory=dict)
+    source: str = "ecb"
+
+    @classmethod
+    def from_xml(cls, text: str, *, source: str = "ecb") -> Rates:
+        root = ET.fromstring(text)
+        cube = root.find(".//ecb:Cube/ecb:Cube", _NS)
+        if cube is None:
+            raise ValueError("unrecognised ECB rate document")
+        rates = {"EUR": 1.0}
+        for entry in cube.findall("ecb:Cube", _NS):
+            currency = entry.get("currency")
+            rate = entry.get("rate")
+            if currency and rate:
+                rates[currency.upper()] = float(rate)
+        return cls(as_of=date.fromisoformat(cube.get("time")), per_eur=rates, source=source)
+
+    @classmethod
+    def from_mapping(
+        cls, per_eur: dict[str, float], *, as_of: date | None = None, source: str = "manual"
+    ) -> Rates:
+        rates = {"EUR": 1.0, **{k.upper(): float(v) for k, v in per_eur.items()}}
+        return cls(as_of=as_of or datetime.now(UTC).date(), per_eur=rates, source=source)
+
+    # ── conversion ───────────────────────────────────────────────────────────
+
+    def covers(self, currency: str) -> bool:
+        return currency.upper() in self.per_eur
+
+    def convert(self, amount: float, source: str, target: str) -> float:
+        """Convert via the EUR pivot. Raises `MissingRate` rather than guessing."""
+        src, dst = source.upper(), target.upper()
+        if src == dst:
+            return amount
+        for currency in (src, dst):
+            if currency not in self.per_eur:
+                raise MissingRate(
+                    f"no ECB reference rate for {currency} (as of {self.as_of}) — "
+                    f"the offer stays in its own currency and is excluded from ranking"
+                )
+        return amount / self.per_eur[src] * self.per_eur[dst]
+
+    def try_convert(self, amount: float, source: str, target: str) -> float | None:
+        """`None` where `convert` would refuse — the caller marks the offer uncomparable."""
+        try:
+            return self.convert(amount, source, target)
+        except MissingRate:
+            return None
+
+    @property
+    def age_days(self) -> int:
+        return (datetime.now(UTC).date() - self.as_of).days
+
+    @property
+    def is_stale(self) -> bool:
+        """ECB publishes on working days; more than a long weekend old is suspect."""
+        return self.age_days > 4
+
+
+class RateCache:
+    """Daily rates on disk, fetched at most once a day."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = Path(path)
+
+    def load(self) -> Rates | None:
+        if not self.path.is_file():
+            return None
+        try:
+            raw = json.loads(self.path.read_text())
+            return Rates(
+                as_of=date.fromisoformat(raw["as_of"]),
+                per_eur={k: float(v) for k, v in raw["per_eur"].items()},
+                source=raw.get("source", "cache"),
+            )
+        except (json.JSONDecodeError, KeyError, ValueError):
+            return None  # a corrupt cache is a cache miss, not a crash
+
+    def save(self, rates: Rates) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(
+                {
+                    "as_of": rates.as_of.isoformat(),
+                    "per_eur": rates.per_eur,
+                    "source": rates.source,
+                    "cached_at": datetime.now(UTC).isoformat(timespec="seconds"),
+                },
+                indent=2,
+                sort_keys=True,
+            )
+        )
+
+    def fetch(self, *, timeout: float = 10.0) -> Rates:
+        """Download today's rates. The only network call in this module."""
+        import httpx
+
+        response = httpx.get(ECB_DAILY_URL, timeout=timeout)
+        response.raise_for_status()
+        rates = Rates.from_xml(response.text)
+        self.save(rates)
+        return rates
+
+    def get(self, *, allow_fetch: bool = True) -> Rates | None:
+        """Cached rates if they are current, otherwise fetch — or `None` offline.
+
+        Returning stale rates beats failing a search: the report says how old they
+        are, and a day-old EUR/THB rate does not change a ranking.
+        """
+        cached = self.load()
+        if cached is not None and cached.age_days <= 1:
+            return cached
+        if not allow_fetch:
+            return cached
+        try:
+            return self.fetch()
+        except Exception:
+            return cached
+
+
+def default_cache_path() -> Path:
+    return Path.home() / ".local" / "state" / "layover" / "ecb-rates.json"
+
+
+def normalize(amount: float, currency: str, target: str, rates: Rates | None) -> float | None:
+    """Convenience for the oracle layer: `None` means uncomparable, never guessed."""
+    if rates is None:
+        return None
+    return rates.try_convert(amount, currency, target)