flight-alloc 0.0.1__py3-none-any.whl

src/web/overrides/filters.py

@@ -0,0 +1,187 @@
+"""User-defined extraction filters, stored under the top-level
+``extraction_filters:`` key in ``configs/config.yml``.
+
+Each filter is a dict with any subset of {ac_type, ac_owner, ac, dep,
+arr, custom_header, custom_value}. Empty fields are skipped during
+matching (AND semantics across specified fields, case-insensitive
+exact). Writes splice the block in place so surrounding comments live.
+"""
+
+from __future__ import annotations
+
+import re
+
+import yaml
+
+from .config_yaml import CONFIG_YML, config_write_lock
+
+#: The fields a filter may specify. Anything else in a submitted dict is
+#: dropped by _normalize_filter.
+_FILTER_FIELDS = (
+    "ac_type", "ac_owner", "ac", "dep", "arr",
+    "custom_header", "custom_value",
+)
+
+
+
+
+def list_extraction_filters() -> list[dict[str, str]]:
+    """Read current extraction filters from config.yml. Only returns
+    fields that have a non-empty value — pad-with-empties would
+    produce YAML `''` scalars on round-trip and corrupt the file."""
+    raw = yaml.safe_load(CONFIG_YML.read_text(encoding="utf-8"))
+    filters = raw.get("extraction_filters") or []
+    out: list[dict[str, str]] = []
+    for f in filters:
+        if not isinstance(f, dict):
+            continue
+        entry: dict[str, str] = {}
+        for k in _FILTER_FIELDS:
+            v = f.get(k)
+            if v is None:
+                continue
+            sv = str(v).strip()
+            if sv:
+                entry[k] = sv
+        if entry:
+            out.append(entry)
+    return out
+
+
+def _normalize_filter(filt: dict[str, str]) -> dict[str, str]:
+    """Strip whitespace and uppercase the short codes (airport / type).
+    Custom header/value are stripped only (case preserved for header
+    since that needs to match the SV-portal column header exactly).
+    """
+    n: dict[str, str] = {}
+    for key in _FILTER_FIELDS:
+        v = str(filt.get(key) or "").strip()
+        if not v:
+            continue
+        if key in ("ac_type", "ac_owner", "ac", "dep", "arr"):
+            n[key] = v.upper()
+        else:
+            n[key] = v
+    if not n:
+        raise ValueError("filter has no fields set — at least one of "
+                         f"{_FILTER_FIELDS} must be non-empty")
+    # If only one of custom_header / custom_value is set, that's a
+    # config error — both required together.
+    if ("custom_header" in n) ^ ("custom_value" in n):
+        raise ValueError(
+            "custom_header and custom_value must be provided together"
+        )
+    return n
+
+
+def _yaml_scalar(v: str) -> str:
+    """Render a string scalar safely for inline YAML. Plain strings
+    are written as-is; if the value contains characters YAML would
+    interpret (`:`, `#`, `&`, `*`, leading `-`, etc.) we quote it.
+    yaml.safe_dump is NOT used here because it appends a `\n...\n`
+    document-end marker for scalars, which corrupts the splice.
+    """
+    s = str(v)
+    needs_quote = (
+        s == ""
+        or any(c in s for c in ":#&*!|>%@`")
+        or s[0] in "-?,[]{}"
+        or s.lower() in ("yes", "no", "true", "false", "null", "~", "on", "off")
+    )
+    if needs_quote:
+        # Single-quoted YAML: escape any internal single quotes by doubling.
+        escaped = s.replace("'", "''")
+        return f"'{escaped}'"
+    return s
+
+
+def _render_filters_block(filters: list[dict[str, str]]) -> str:
+    """Format a list of filter dicts as YAML under the top-level
+    ``extraction_filters:`` key. Always terminates with a newline.
+    """
+    if not filters:
+        return "extraction_filters: []\n"
+    out = "extraction_filters:\n"
+    for entry in filters:
+        lines = [f"{k}: {_yaml_scalar(v)}" for k, v in entry.items()]
+        out += f"  - {lines[0]}\n"
+        for ln in lines[1:]:
+            out += f"    {ln}\n"
+    return out
+
+
+def _splice_filters_into_config(filters: list[dict[str, str]]) -> None:
+    """Write ``filters`` back into ``configs/config.yml``'s
+    ``extraction_filters:`` section, leaving every other byte of the
+    file intact (comments, whitespace, order)."""
+    raw_text = CONFIG_YML.read_text(encoding="utf-8")
+    new_block = _render_filters_block(filters).rstrip("\n") + "\n"
+    # Match the extraction_filters key + its current value (whether
+    # `[]`, `:` followed by a list, or just `:` followed by a blank).
+    # Use ^extraction_filters\s*: as anchor; consume up to (but not
+    # including) the next top-level key OR end of file.
+    pattern = re.compile(
+        r"^extraction_filters\s*:[^\n]*\n(?:[ \t-].*\n)*",
+        re.MULTILINE,
+    )
+    if pattern.search(raw_text):
+        new_text = pattern.sub(new_block, raw_text, count=1)
+    else:
+        # Defensive — config.yml ships with the key, so this branch
+        # is for upgrades where it was missing.
+        new_text = raw_text.rstrip() + "\n\n" + new_block
+    CONFIG_YML.write_text(new_text, encoding="utf-8")
+
+
+def add_extraction_filter(filt: dict[str, str]) -> dict[str, str]:
+    """Validate and append one extraction filter to config.yml.
+    Returns the normalised dict that was written. Idempotent — a
+    duplicate filter is a no-op (same dict returned)."""
+    norm = _normalize_filter(filt)
+    with config_write_lock:
+        existing = list_extraction_filters()
+        # Idempotent: skip duplicates (compare non-empty fields only).
+        for e in existing:
+            if {k: v for k, v in e.items() if v} == norm:
+                return norm
+        existing.append(norm)
+        _splice_filters_into_config(existing)
+    return norm
+
+
+def remove_extraction_filter(idx: int) -> dict[str, str]:
+    """Remove the filter at 1-based index ``idx``. Returns the removed
+    filter dict. Raises IndexError if out of range."""
+    with config_write_lock:
+        existing = list_extraction_filters()
+        if idx < 1 or idx > len(existing):
+            raise IndexError(
+                f"extraction_filter index {idx} out of range (1..{len(existing)})"
+            )
+        removed = existing.pop(idx - 1)
+        _splice_filters_into_config(existing)
+    return removed
+
+
+def update_extraction_filter(
+    idx: int, new_filter: dict[str, str],
+) -> tuple[dict[str, str], dict[str, str]]:
+    """Replace the filter at 1-based index ``idx`` with ``new_filter``
+    atomically (single config write). Returns (old, new) so the caller
+    can render a diff. Raises IndexError if out of range, ValueError
+    if the new filter is invalid (e.g. all fields empty)."""
+    norm = _normalize_filter(new_filter)
+    with config_write_lock:
+        existing = list_extraction_filters()
+        if idx < 1 or idx > len(existing):
+            raise IndexError(
+                f"extraction_filter index {idx} out of range (1..{len(existing)})"
+            )
+        old = existing[idx - 1]
+        if {k: v for k, v in old.items() if v} == norm:
+            return old, norm   # idempotent — no write needed
+        existing[idx - 1] = norm
+        _splice_filters_into_config(existing)
+    return old, norm
+
+

src/web/overrides/rows.py

@@ -0,0 +1,110 @@
+"""Override-row mutation: the drawer's table rows, the recommender's
+one-click fixes, and the staged add/remove forms.
+
+Override rows live in ``state.STATE.overrides`` as dicts keyed by the
+column names in ``state.OVERRIDE_HEADERS``. Each row type uses its own
+subset of those keys (a ``p2f`` row cares about employee + shift; a
+``waive_h10_pair`` row about flight + std + other_std), so nothing here
+validates the shape — the reader for each type does that at solve time,
+exactly as it would for a row typed in by hand.
+"""
+
+from __future__ import annotations
+
+from ...state import OVERRIDE_HEADERS, OVERRIDE_HEADERS_VISIBLE, AppState
+
+# Which columns each recommender "kind" must supply.
+_PHASE_R_PAYLOAD_COLS = {
+    "waive_h10_pair":    ("flight", "std", "employee", "other_std"),
+    "raise_cap":         ("flight", "std", "employee"),
+    "skip_p2f_buffer":   ("flight", "std", "employee"),
+    "skip_intl_removal": ("flight", "std"),
+}
+
+
+def add_override(state: AppState, values: list[str]) -> int:
+    """Append a drawer row. ``values`` are positional against
+    ``OVERRIDE_HEADERS_VISIBLE``. Returns the new row's index."""
+    row = {
+        h: v for h, v in zip(OVERRIDE_HEADERS_VISIBLE, values)
+        if str(v).strip()
+    }
+    return state.add_override(row)
+
+
+def update_override(state: AppState, index: int, values: list[str]) -> None:
+    """Overwrite the visible cells of row ``index``, preserving any
+    type-specific fields (Phase-R flight / std) already on the row."""
+    with state.lock:
+        if not 0 <= index < len(state.overrides):
+            raise IndexError(f"no override row at index {index}")
+        merged = dict(state.overrides[index])
+        for h, v in zip(OVERRIDE_HEADERS_VISIBLE, values):
+            s = str(v).strip()
+            if s:
+                merged[h] = s
+            else:
+                merged.pop(h, None)
+        state.update_override(index, merged)
+
+
+def delete_override(state: AppState, index: int) -> None:
+    state.delete_override(index)
+
+
+def clear_all_overrides(state: AppState) -> int:
+    """Drop every override row. Returns the count removed.
+
+    A fresh Plan resets the list so leftover nominations from the
+    previous cycle don't silently shadow the new roster's handler picks.
+    """
+    with state.lock:
+        n = len(state.overrides)
+        state.overrides = []
+        return n
+
+
+def apply_phase_r_override(
+    state: AppState, kind: str, payload: dict[str, str],
+) -> int:
+    """Write a Phase-R recommender suggestion as an override row.
+
+    ``kind`` is one of waive_h10_pair / raise_cap / skip_p2f_buffer /
+    skip_intl_removal. Returns the new row's index. Raises ValueError on
+    an unknown kind and KeyError when a required field is missing.
+    """
+    if kind not in _PHASE_R_PAYLOAD_COLS:
+        raise ValueError(f"unknown recommender kind: {kind!r}")
+    row: dict[str, str] = {"type": kind}
+    for col in _PHASE_R_PAYLOAD_COLS[kind]:
+        value = str(payload.get(col, "")).strip()
+        if not value:
+            raise KeyError(f"missing payload field {col!r} for kind {kind!r}")
+        row[col] = value
+    return state.add_override(row)
+
+
+def write_staged_override(
+    state: AppState, op_type: str, payload: dict[str, str],
+) -> int:
+    """Write a staged-form row (Add flight / Remove flight / Add staff /
+    Remove staff). The caller is expected to follow up with
+    ``staged_overrides.apply_staged_overrides`` so the change shows on
+    the dashboard immediately.
+
+    Unknown payload keys are dropped rather than stored, so a typo in a
+    form field can't quietly become a column nothing reads.
+    """
+    from ...schemas import STAGED_FORM_OVERRIDE_TYPES
+    valid = {t.value for t in STAGED_FORM_OVERRIDE_TYPES}
+    if op_type not in valid:
+        raise ValueError(
+            f"unknown op_type: {op_type!r}. Valid: {sorted(valid)}"
+        )
+    row: dict[str, str] = {"type": op_type}
+    for key, value in payload.items():
+        k = str(key).strip().lower()
+        if k in OVERRIDE_HEADERS and str(value).strip():
+            row[k] = str(value).strip()
+    return state.add_override(row)
+

src/web/readback/__init__.py

@@ -0,0 +1,67 @@
+"""Serialise the in-memory state into the JSON shapes the UI needs.
+
+Every function takes the ``AppState`` and returns plain dicts/lists
+ready for ``json.dumps``. Nothing here reads a file, so a GET is cheap
+and can re-serialise on every request.
+
+The package is split by what the caller is looking at:
+
+    common      run date / INTL codes / roster-liveness predicates
+    dashboard   headline stat cards + the at-risk table
+    tables      the per-tab row lists (allocations, workload, pairs, ...)
+    planning    Plan summary, handlers, staffing, roster, shift bands
+    session     uploads, override rows, SV-portal columns
+
+Import the names from here, not from the sub-modules — this is the
+stable surface the API layer binds its routes to.
+"""
+
+from __future__ import annotations
+
+from ...schemas import Severity
+from .dashboard import read_dashboard
+from .planning import (
+    read_handlers,
+    read_plan_summary,
+    read_roster_full,
+    read_shift_limits,
+    read_staff_names,
+    read_staffing,
+)
+from .session import (
+    read_inputs,
+    read_overrides,
+    read_roster_counts,
+    read_server_date,
+    read_sv_portal_columns,
+)
+from .tables import (
+    read_allocations,
+    read_pairs,
+    read_recommendations,
+    read_unallocated,
+    read_warnings,
+    read_workload,
+)
+
+__all__ = [
+    "Severity",
+    "read_allocations",
+    "read_dashboard",
+    "read_handlers",
+    "read_inputs",
+    "read_overrides",
+    "read_pairs",
+    "read_plan_summary",
+    "read_recommendations",
+    "read_roster_counts",
+    "read_roster_full",
+    "read_server_date",
+    "read_shift_limits",
+    "read_staff_names",
+    "read_staffing",
+    "read_sv_portal_columns",
+    "read_unallocated",
+    "read_warnings",
+    "read_workload",
+]

src/web/readback/common.py

@@ -0,0 +1,68 @@
+"""Shared primitives for the readback modules.
+
+Everything here is pure: it reads ``AppState`` (or the config file) and
+returns plain values. Keeping it in one place means a new readback
+module never has to re-derive the run date or the INTL code set.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ...schemas import CrewStatus
+from ...state import AppState
+
+# Absolute path to configs/config.yml relative to THIS source file, so a
+# readback works whatever CWD the server was launched from.
+CONFIG_PATH = Path(__file__).resolve().parents[3] / "configs" / "config.yml"
+
+#: Canonical shift order used by every per-shift readback.
+SHIFTS: tuple[str, ...] = ("M", "A", "N", "M1", "A1")
+
+
+def intl_codes() -> set[str]:
+    from ...config import load_config
+    cfg = load_config(CONFIG_PATH)
+    return {c.upper() for c in cfg.io.sv_portal.international_airport_codes}
+
+
+def run_date_iso(state: AppState) -> str:
+    return state.run_date.isoformat() if state.run_date else ""
+
+
+def is_live(state: AppState, av: Any) -> bool:
+    """A roster row counts for the dashboard when it is assignable, sits
+    on a shift, and belongs to the run date."""
+    if not av.assignable or not av.current_shift:
+        return False
+    d_iso = run_date_iso(state)
+    return not d_iso or av.date.isoformat() == d_iso
+
+
+def canonical_status(raw: str) -> CrewStatus | None:
+    """Resolve a status literal, tolerating the legacy slash-reversed
+    form (``P2F/M``) by sorting the parts alphabetically."""
+    try:
+        return CrewStatus(raw)
+    except ValueError:
+        pass
+    if "/" in raw:
+        canonical = "/".join(
+            sorted(p.strip().upper() for p in raw.split("/") if p.strip())
+        )
+        try:
+            return CrewStatus(canonical)
+        except ValueError:
+            return None
+    return None
+
+
+__all__ = [
+    "CONFIG_PATH",
+    "SHIFTS",
+    "canonical_status",
+    "intl_codes",
+    "is_live",
+    "run_date_iso",
+]

src/web/readback/dashboard.py

@@ -0,0 +1,83 @@
+"""Dashboard headline readback — the stat cards and the at-risk table.
+
+One function, deliberately: the dashboard is the aggregate view, so it
+touches allocations, roster and warnings at once. Per-tab detail lives
+in the sibling modules.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...state import AppState
+from .common import run_date_iso
+
+
+
+def read_dashboard(state: AppState) -> dict[str, Any]:
+    """Run-status block + the headline counts behind the stat cards."""
+    with state.lock:
+        # Per-class cards show CLEANED counts (flights to plan), so the
+        # numbers are real right after Plan rather than zeros that only
+        # fill in after Allocate.
+        by_class = {ops.value: len(rows) for ops, rows in state.cleaned.items()}
+        special_sub = {
+            "test": by_class.get("test", 0),
+            "ferry": by_class.get("ferry", 0),
+            "charter": by_class.get("charter", 0),
+        }
+
+        # "Flights allocated" counts allocation rows. A pre-plan-deferred
+        # row has empty staff but a populated planned_by — someone is
+        # preparing it, so it is not unallocated.
+        flights_total = len(state.allocations)
+
+        staff_at_risk: list[dict[str, Any]] = []
+        for w in state.workload:
+            # At risk = real cap violations only. Under-preferred is just
+            # a light load; above-preferred is informational.
+            joined = "; ".join(w.violations)
+            lowered = joined.lower()
+            if not any(p in lowered for p in (
+                "above hard cap", "exceeds cap", "exceeds hard cap",
+                "over hard cap",
+            )):
+                continue
+            staff_at_risk.append({
+                "employee_id": w.employee_id,
+                "name": w.name,
+                "shift": w.shift or "",
+                "actual": w.actual,
+                "target_preferred": w.target_preferred,
+                "hard_cap": w.hard_cap,
+                "violations": joined,
+            })
+
+        warnings_total = len(state.warnings)
+
+        return {
+            "run_date": run_date_iso(state),
+            "last_run": state.last_run,
+            "mode": state.mode,
+            "solver_status": state.solver_status,
+            "duration_s": state.duration_s,
+            "has_inputs": not state.missing_inputs(),
+            "missing_inputs": state.missing_inputs(),
+            "stats": {
+                "flights_total": flights_total,
+                "flights_unallocated": len(state.unallocated),
+                "day_ops": by_class.get("day", 0),
+                "night_ops": by_class.get("night", 0),
+                "p2f": by_class.get("p2f", 0),
+                "special_ops": sum(special_sub.values()),
+                "special_ops_test": special_sub["test"],
+                "special_ops_ferry": special_sub["ferry"],
+                "special_ops_charter": special_sub["charter"],
+                "staff_total": len(state.workload),
+                "staff_at_risk": len(staff_at_risk),
+                "warnings_total": warnings_total,
+            },
+            "staff_at_risk": staff_at_risk[:10],
+        }
+
+