glidepath 0.2.0__py3-none-any.whl

glidepath/app/files.py

@@ -0,0 +1,249 @@
+"""Plan file save and load for shells (planning §4.5, §4.7).
+
+The app-layer face of :mod:`glidepath.persistence`: the File menu's
+copy, the session-state ↔ plan-document conversions, and save/load
+transitions that fold every failure into a status message instead of
+raising at a shell. The document stores the household, the scenarios,
+and the user's assumption *overrides*; shipped defaults re-resolve on
+every load, and a load records nothing back to disk — plans live
+wherever the user chooses (§4.5).
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final
+
+from glidepath.app.forms import form_cannot_represent
+from glidepath.app.plan import (
+    PlanState,
+    check_table_override,
+    region_for,
+    replanned_state,
+)
+from glidepath.core import AssumptionTarget
+from glidepath.persistence import (
+    PersistenceError,
+    PlanDocument,
+    assumption_overrides_from,
+    load_plan,
+    resolve_assumptions,
+    save_plan,
+)
+from glidepath.regions.uk import default_assumption_set
+
+if TYPE_CHECKING:
+    from datetime import date
+    from pathlib import Path
+
+    from glidepath.core import AssumptionKey
+
+PLAN_REGION: Final = "uk"
+
+PLAN_FILE_SUFFIX: Final = ".glidepath.json"
+
+PLAN_FILE_FILTER: Final = "glidepath plan (*.glidepath.json)"
+
+FILE_MENU_LABEL: Final = "File"
+
+OPEN_PLAN_LABEL: Final = "Open plan…"
+
+SAVE_PLAN_LABEL: Final = "Save plan"
+
+SAVE_PLAN_AS_LABEL: Final = "Save plan as…"
+
+QUIT_LABEL: Final = "Quit"
+
+OPEN_DIALOG_TITLE: Final = "Open plan"
+
+SAVE_DIALOG_TITLE: Final = "Save plan"
+
+UNSAVED_CHANGES_TITLE: Final = "Unsaved changes"
+
+UNSAVED_CHANGES_PROMPT: Final = (
+    "This plan has unsaved changes. Save them before closing?"
+)
+
+NOTHING_TO_SAVE_MESSAGE: Final = (
+    "Nothing to save yet — save facts on the Facts tab first."
+)
+
+_SAVE_FAILED_PREFIX: Final = "Could not save the plan: "
+
+_OPEN_FAILED_PREFIX: Final = "Could not open the plan: "
+
+_WRONG_REGION_MESSAGE: Final = "this plan's region {region!r} is not supported"
+
+_UNREPRESENTABLE_MESSAGE: Final = (
+    "this plan holds {reason}, which the facts form cannot edit yet — "
+    "opening it would lose that data on the next save"
+)
+
+_DEFAULTS_MOVED_NOTE: Final = (
+    "Note: the shipped default assumptions have changed since this plan "
+    "was last saved — review the stated-vs-assumed view."
+)
+
+
+@dataclass(frozen=True)
+class SaveOutcome:
+    """Whether a save wrote the file, and the status line saying so."""
+
+    saved: bool
+    message: str
+
+
+@dataclass(frozen=True)
+class LoadOutcome:
+    """The loaded session state, or the message explaining the failure.
+
+    ``message`` always carries the status line to show — success and
+    failure alike.
+    """
+
+    state: PlanState | None
+    message: str
+
+
+def _shipped_data_version() -> str:
+    """The shipped region data's content version, defaults applied.
+
+    Computed from the shipped defaults rather than the session's
+    effective assumptions, so the recorded version moves exactly when
+    the shipped data (or a shipped default policy) moves — never when
+    the user overrides an assumption.
+    """
+    return region_for(default_assumption_set()).data_version
+
+
+def document_from_state(state: PlanState) -> PlanDocument | None:
+    """The session as a storable plan document; ``None`` without a plan."""
+    if state.household is None:
+        return None
+    return PlanDocument(
+        region=PLAN_REGION,
+        assumptions_resolved_against=_shipped_data_version(),
+        household=state.household,
+        assumption_overrides=assumption_overrides_from(state.assumptions),
+        scenarios=state.scenarios,
+    )
+
+
+def has_unsaved_changes(state: PlanState) -> bool:
+    """Whether closing now would discard plan edits (issue #136).
+
+    True only when a plan-mutating transition has touched the state
+    since the last save or load *and* there is a plan a save could
+    write — an assumption overridden before any facts exist has no
+    document to preserve, so a prompt would offer a save that does
+    nothing.
+    """
+    return state.modified and state.household is not None
+
+
+def save_plan_state(state: PlanState, path: Path) -> SaveOutcome:
+    """Write the session's plan to ``path``, reporting the outcome."""
+    document = document_from_state(state)
+    if document is None:
+        return SaveOutcome(saved=False, message=NOTHING_TO_SAVE_MESSAGE)
+    try:
+        save_plan(document, path)
+    except (PersistenceError, OSError) as exc:
+        return SaveOutcome(saved=False, message=f"{_SAVE_FAILED_PREFIX}{exc}")
+    return SaveOutcome(saved=True, message=f"Plan saved to {path}.")
+
+
+def _table_error(key: AssumptionKey, value: object) -> str | None:
+    """The policy parser's objection to a stored table value, if any."""
+    if not isinstance(value, Mapping):
+        return None
+    try:
+        check_table_override(key, value)
+    except ValueError as exc:
+        return f"override on {key.value!r}: {exc}"
+    return None
+
+
+def _table_override_error(document: PlanDocument) -> str | None:
+    """The first stored table override its policy parser rejects.
+
+    ``resolve_assumptions`` checks only broad value shape (mapping vs
+    scalar); a structurally defective table would otherwise decode
+    cleanly and raise mid-run, past the load's failure boundary. The
+    same policy parsers the editors use are the contract here (issue
+    #71), for the base overrides and every scenario's alike.
+    """
+    for override in document.assumption_overrides:
+        error = _table_error(override.key, override.value)
+        if error is not None:
+            return error
+    for scenario in document.scenarios:
+        for entry in scenario.overrides:
+            target = entry.target
+            if not isinstance(target, AssumptionTarget):
+                continue
+            error = _table_error(target.key, entry.value)
+            if error is not None:
+                return f"scenario {scenario.name!r} {error}"
+    return None
+
+
+def load_plan_state(path: Path, *, today: date) -> LoadOutcome:
+    """Read the plan at ``path`` into a freshly projected session state.
+
+    Assumptions re-resolve against the current shipped defaults with
+    the stored overrides on top (§4.5); when the shipped data moved
+    since the file was saved, the status message says so rather than
+    silently re-pricing the plan. A run failure inside an otherwise
+    loadable plan still loads — the state carries the run error, and
+    the result panes report it exactly as they do after a facts edit.
+    A plan the facts form cannot faithfully edit is refused outright:
+    opening it would silently discard the extra data on the next save.
+    """
+    try:
+        document = load_plan(path)
+    except (PersistenceError, OSError) as exc:
+        return LoadOutcome(state=None, message=f"{_OPEN_FAILED_PREFIX}{exc}")
+    if document.region != PLAN_REGION:
+        detail = _WRONG_REGION_MESSAGE.format(region=document.region)
+        return LoadOutcome(state=None, message=f"{_OPEN_FAILED_PREFIX}{detail}")
+    reason = form_cannot_represent(document.household)
+    if reason is not None:
+        detail = _UNREPRESENTABLE_MESSAGE.format(reason=reason)
+        return LoadOutcome(state=None, message=f"{_OPEN_FAILED_PREFIX}{detail}")
+    table_error = _table_override_error(document)
+    if table_error is not None:
+        return LoadOutcome(state=None, message=f"{_OPEN_FAILED_PREFIX}{table_error}")
+    try:
+        assumptions = resolve_assumptions(document, default_assumption_set())
+    except PersistenceError as exc:
+        return LoadOutcome(state=None, message=f"{_OPEN_FAILED_PREFIX}{exc}")
+    state = replanned_state(
+        assumptions, document.household, document.scenarios, today=today, modified=False
+    )
+    message = f"Plan loaded from {path}."
+    if document.assumptions_resolved_against != _shipped_data_version():
+        message = f"{message} {_DEFAULTS_MOVED_NOTE}"
+    return LoadOutcome(state=state, message=message)
+
+
+__all__ = [
+    "FILE_MENU_LABEL",
+    "NOTHING_TO_SAVE_MESSAGE",
+    "OPEN_DIALOG_TITLE",
+    "OPEN_PLAN_LABEL",
+    "PLAN_FILE_FILTER",
+    "PLAN_FILE_SUFFIX",
+    "PLAN_REGION",
+    "QUIT_LABEL",
+    "SAVE_DIALOG_TITLE",
+    "SAVE_PLAN_AS_LABEL",
+    "SAVE_PLAN_LABEL",
+    "UNSAVED_CHANGES_PROMPT",
+    "UNSAVED_CHANGES_TITLE",
+    "LoadOutcome",
+    "SaveOutcome",
+    "document_from_state",
+    "has_unsaved_changes",
+    "load_plan_state",
+    "save_plan_state",
+]

glidepath/app/firstrun.py

@@ -0,0 +1,114 @@
+"""Local per-user settings: disclaimer state and the last plan (§1, §4.7).
+
+A tiny local JSON file records the disclaimer acknowledgement date and
+the path of the last plan file saved or opened, so the next launch can
+skip the first-run screen and reopen the user's plan. Anything
+unreadable — missing file, bad JSON, wrong shape, a schema version
+this reader does not know — degrades to an empty state, so the
+disclaimer is shown again (and no plan auto-opens) rather than
+guessing. The state lives in the platform's per-user configuration
+directory; shells pass ``default_state_path()`` (or a substitute) in,
+so this module never touches Qt or a display.
+"""
+
+import json
+import os
+import sys
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+_STATE_SCHEMA_VERSION = 1
+_SCHEMA_KEY = "schema"
+_ACKNOWLEDGED_KEY = "disclaimer_acknowledged_on"
+_LAST_PLAN_KEY = "last_plan_path"
+
+
+@dataclass(frozen=True)
+class FirstRunState:
+    """What the local state file says about previous runs."""
+
+    disclaimer_acknowledged_on: date | None
+    last_plan_path: Path | None = None
+
+
+_EMPTY_STATE = FirstRunState(disclaimer_acknowledged_on=None)
+
+
+def default_state_path() -> Path:
+    """Per-user settings file location, following platform convention."""
+    if sys.platform == "win32":
+        base = Path(os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming")
+    else:
+        base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    return base / "glidepath" / "settings.json"
+
+
+def _acknowledged_from(raw: dict[str, Any]) -> date | None:
+    """The recorded acknowledgement date; ``None`` on any defect."""
+    try:
+        return date.fromisoformat(raw[_ACKNOWLEDGED_KEY])
+    except ValueError, KeyError, TypeError:
+        return None
+
+
+def _last_plan_from(raw: dict[str, Any]) -> Path | None:
+    """The recorded last plan path; ``None`` on any defect."""
+    text = raw.get(_LAST_PLAN_KEY)
+    if not isinstance(text, str) or not text:
+        return None
+    return Path(text)
+
+
+def load_state(path: Path) -> FirstRunState:
+    """Read the local state, degrading to an empty state on any defect.
+
+    Each field degrades independently: a defective acknowledgement
+    date never discards a readable last-plan path, and vice versa.
+    """
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        if raw[_SCHEMA_KEY] != _STATE_SCHEMA_VERSION:
+            return _EMPTY_STATE
+    except OSError, ValueError, KeyError, TypeError:
+        return _EMPTY_STATE
+    return FirstRunState(
+        disclaimer_acknowledged_on=_acknowledged_from(raw),
+        last_plan_path=_last_plan_from(raw),
+    )
+
+
+def _write_state(path: Path, state: FirstRunState) -> None:
+    """Persist the whole state, omitting unset fields."""
+    payload: dict[str, Any] = {_SCHEMA_KEY: _STATE_SCHEMA_VERSION}
+    if state.disclaimer_acknowledged_on is not None:
+        payload[_ACKNOWLEDGED_KEY] = state.disclaimer_acknowledged_on.isoformat()
+    if state.last_plan_path is not None:
+        payload[_LAST_PLAN_KEY] = str(state.last_plan_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def record_disclaimer_acknowledged(path: Path, acknowledged_on: date) -> None:
+    """Persist the acknowledgement so later runs skip the first-run screen."""
+    state = load_state(path)
+    _write_state(
+        path,
+        FirstRunState(
+            disclaimer_acknowledged_on=acknowledged_on,
+            last_plan_path=state.last_plan_path,
+        ),
+    )
+
+
+def record_last_plan_path(path: Path, plan_path: Path) -> None:
+    """Persist the plan file just saved or opened, for the next launch."""
+    state = load_state(path)
+    _write_state(
+        path,
+        FirstRunState(
+            disclaimer_acknowledged_on=state.disclaimer_acknowledged_on,
+            last_plan_path=plan_path,
+        ),
+    )