utils/focus_project/focus_project/_model.py
Krzysztof kuhy Rudnicki c29d0989dd Clear inherited CI debt in the Python libs
main was red on file length, the noqa ban, codespell, test naming and
dart coverage; this change touches every one of those jobs.

- sickdays: set_enabled is keyword-only; the panel test splits in two
  with shared probes; the sync wire format moves to DOCS-sync.md.
- earned_time: _focus types the project as a Protocol, no noqa; the
  gate-maturity section moves to DOCS-maturity.md; codespell knows the
  `checkin` event name.
- focus_project: real fixes for every noqa (local-day clocks, typed
  fakes, logged broad catches, split helpers). The public API that
  focus-guard calls keeps its signatures; their PLR0913 exemption
  lives in pyproject with the reason, not in noqa.
- crdt-sync: pylint gets nacl/argon2, docstrings, and allows the
  public E2eLayout.of; _blobs moves to _e2e_blobs.py.
- crdt_sync_dart: Argon2Params and the header errors move to
  e2e_params.dart (re-exported); tests split and reach 100% lines.
- sql_drills: test helpers get a leading underscore, as in earned_time.

Todo: fda71ed1
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 08:58:01 +01:00

188 lines
7.3 KiB
Python

# Copyright (c) 2026 Krzysztof Rudnicki
"""The :class:`Project` value and the gate vocabulary."""
from __future__ import annotations
from dataclasses import dataclass
from datetime import date, datetime
from typing import TYPE_CHECKING, Any
from focus_project._errors import RegistryError
from focus_project._kind import FOCUS, INTERVIEW, interview_minutes
from focus_project._trips import Trip
if TYPE_CHECKING:
from collections.abc import Mapping
GATES = frozenset({"leetcode", "reading", "tutor"})
_ALIASES = {"book": "reading"}
def normalize_gate(gate: str) -> str:
"""Map the book/reading synonyms onto one name; others pass through."""
return _ALIASES.get(gate, gate)
def _answers(raw: dict[str, Any] | None) -> tuple[tuple[date, bool], ...]:
"""Parse the saturday -> bool map; a non-bool answer is a bad row."""
pairs = []
for key, value in (raw or {}).items():
if not isinstance(value, bool):
msg = f"weekend answer for {key} is not true/false"
raise TypeError(msg)
pairs.append((date.fromisoformat(key), value))
return tuple(sorted(pairs))
@dataclass(frozen=True)
class Limits:
"""The minute targets that held up to and including ``until``."""
until: date
daily_minutes: int
unlock_minutes: int
# None = a row from before 0.7.0: the project's current gates apply.
replaces: tuple[str, ...] | None = None
def to_dict(self) -> dict[str, Any]:
"""The history row in projects.json."""
row: dict[str, Any] = {
"until": self.until.isoformat(),
"daily_minutes": self.daily_minutes,
"unlock_minutes": self.unlock_minutes,
}
if self.replaces is not None:
row["replaces"] = list(self.replaces)
return row
@classmethod
def from_dict(cls, row: Mapping[str, Any]) -> Limits:
"""Parse a history row (errors surface as RegistryError upstream)."""
gates = row.get("replaces")
return cls(
until=date.fromisoformat(row["until"]),
daily_minutes=int(row["daily_minutes"]),
unlock_minutes=int(row["unlock_minutes"]),
replaces=None if gates is None else tuple(gates),
)
@dataclass(frozen=True)
class Project: # pylint: disable=too-many-instance-attributes
"""One time-boxed focus project; at most one is active per day."""
id: str
name: str
start: date
end: date
replaces: tuple[str, ...]
daily_minutes: int
unlock_minutes: int
subjects: tuple[str, ...] = ()
site_patterns: tuple[str, ...] = ()
ended_on: date | None = None
created_ms: int = 0
# Where the work happens (http/https); empty = the first site pattern.
work_url: str = ""
# Earlier targets, oldest first: an edit applies from its day, never back.
history: tuple[Limits, ...] = ()
# "focus" (every pre-interview row) or "interview"; the rest is interview-only.
kind: str = FOCUS
# Local naive datetime of the test; its date is the project's last day.
test_at: datetime | None = None
invite_url: str = ""
trips: tuple[Trip, ...] = ()
# Saturday -> True (trip that weekend) / False (no trip); sorted pairs.
weekend_answers: tuple[tuple[date, bool], ...] = ()
def _limits_on(self, day: date) -> Limits | None:
return next((h for h in self.history if day <= h.until), None)
def daily_on(self, day: date) -> int:
"""The daily target that held on ``day``."""
if self.kind == INTERVIEW:
return interview_minutes(day)
past = self._limits_on(day)
return self.daily_minutes if past is None else past.daily_minutes
def unlock_on(self, day: date) -> int:
"""The unlock target that held on ``day`` (clamped for an interview)."""
past = self._limits_on(day)
held = self.unlock_minutes if past is None else past.unlock_minutes
return min(held, interview_minutes(day)) if self.kind == INTERVIEW else held
def replaces_on(self, day: date) -> tuple[str, ...]:
"""The gates this project switched off on ``day``."""
past = self._limits_on(day)
return self.replaces if past is None or past.replaces is None else past.replaces
@property
def last_day(self) -> date:
"""The last active day: the early-end day if set, else ``end``."""
return self.ended_on if self.ended_on is not None else self.end
def covers(self, day: date) -> bool:
"""Whether this project is active on ``day``."""
return self.start <= day <= self.last_day
def replaces_gate(self, gate: str, day: date) -> bool:
"""Whether this project switches ``gate`` off on ``day``."""
return normalize_gate(gate) in self.replaces_on(day)
def to_dict(self) -> dict[str, Any]:
"""The projects.json row."""
row: dict[str, Any] = {
"id": self.id,
"name": self.name,
"start": self.start.isoformat(),
"end": self.end.isoformat(),
"replaces": list(self.replaces),
"daily_minutes": self.daily_minutes,
"unlock_minutes": self.unlock_minutes,
"subjects": list(self.subjects),
"site_patterns": list(self.site_patterns),
"ended_on": self.ended_on.isoformat() if self.ended_on else None,
"created_ms": self.created_ms,
"work_url": self.work_url,
"history": [h.to_dict() for h in self.history],
"kind": self.kind,
}
if self.kind == INTERVIEW:
row["test_at"] = self.test_at.isoformat() if self.test_at else None
row["invite_url"] = self.invite_url
row["trips"] = [t.to_dict() for t in self.trips]
row["weekend_answers"] = {
day.isoformat(): trip for day, trip in self.weekend_answers
}
return row
@classmethod
def from_dict(cls, row: Mapping[str, Any]) -> Project:
"""Parse a registry row, or raise :class:`RegistryError`."""
try:
ended = row.get("ended_on")
test_at = row.get("test_at")
return cls(
id=str(row["id"]),
name=str(row["name"]),
start=date.fromisoformat(row["start"]),
end=date.fromisoformat(row["end"]),
replaces=tuple(row["replaces"]),
daily_minutes=int(row["daily_minutes"]),
unlock_minutes=int(row["unlock_minutes"]),
subjects=tuple(row.get("subjects", ())),
site_patterns=tuple(row.get("site_patterns", ())),
ended_on=date.fromisoformat(ended) if ended else None,
created_ms=int(row.get("created_ms", 0)),
work_url=str(row.get("work_url") or ""),
history=tuple(Limits.from_dict(h) for h in row.get("history", ())),
kind=str(row.get("kind") or FOCUS),
test_at=datetime.fromisoformat(test_at) if test_at else None,
invite_url=str(row.get("invite_url") or ""),
trips=tuple(Trip.from_dict(t) for t in row.get("trips", ())),
weekend_answers=_answers(row.get("weekend_answers")),
)
except (KeyError, TypeError, ValueError, AttributeError) as exc:
msg = f"bad project row {row!r}: {exc}"
raise RegistryError(msg) from exc