leadger 0.1.0__py3-none-any.whl

leadger/core/storage.py

@@ -0,0 +1,385 @@
+"""Storage: the YAML-backed orchestrator for tasks, days and metrics.
+
+Implements the product's core rules:
+  - lazy snapshot + rollover at config.day_start (regras 1-2)
+  - the "% do dia entregue" hero metric, including over-delivery and
+    the goal=0 bonus-day case (regra 3)
+  - external-edit detection via mtime, last-write-wins (regra 7)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from pathlib import Path
+from typing import Optional
+
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+
+from .ids import generate_task_id
+from .recur import next_occurrence
+from .tasks import Task, TaskStatus
+from .time_utils import leadger_today, now_in_zone, parse_day_start
+from .yaml_io import read_yaml, write_yaml_atomic
+
+DEFAULT_TIMEZONE = "America/Sao_Paulo"
+DEFAULT_DAY_START = "05:00"
+
+# sentinel distinguishing "leave unchanged" from "remove" in update_task(recur=...)
+_UNSET: object = object()
+
+
+@dataclass(frozen=True)
+class DayMetrics:
+    """The hero metric for a single day."""
+
+    date: date
+    goal: int
+    snapshot_done: int
+    extras_done: int
+    extras_total: int
+    done: int
+    pct: Optional[float]
+    bonus_day: bool
+    over_delivery: bool
+
+
+class Storage:
+    """Loads/saves a single leadger.yaml and applies the business rules."""
+
+    def __init__(self, path: Path | str) -> None:
+        self.path = Path(path).expanduser()
+        self._mtime: Optional[float] = None
+        self.data: CommentedMap = CommentedMap()
+        self.reload()
+
+    # ------------------------------------------------------------------
+    # IO
+    # ------------------------------------------------------------------
+    def reload(self) -> None:
+        """Force a re-read from disk. Raises CorruptedYAMLError if invalid."""
+        self.data = read_yaml(self.path)
+        self._mtime = self.path.stat().st_mtime if self.path.exists() else None
+
+    def _sync(self) -> None:
+        """Reload if the file changed on disk since our last read (regra 7)."""
+        if not self.path.exists():
+            return
+        mtime = self.path.stat().st_mtime
+        if self._mtime is None or mtime != self._mtime:
+            self.reload()
+
+    def save(self) -> None:
+        write_yaml_atomic(self.path, self.data)
+        self._mtime = self.path.stat().st_mtime
+
+    # ------------------------------------------------------------------
+    # Config / time
+    # ------------------------------------------------------------------
+    @property
+    def config(self) -> CommentedMap:
+        return self.data.setdefault("config", CommentedMap())
+
+    @property
+    def timezone_name(self) -> str:
+        return str(self.config.get("timezone", DEFAULT_TIMEZONE))
+
+    @property
+    def day_start(self):  # -> datetime.time
+        return parse_day_start(str(self.config.get("day_start", DEFAULT_DAY_START)))
+
+    def now(self) -> datetime:
+        return now_in_zone(self.timezone_name)
+
+    def today(self, now: Optional[datetime] = None) -> date:
+        now = now or self.now()
+        return leadger_today(now, self.day_start)
+
+    # ------------------------------------------------------------------
+    # Tasks
+    # ------------------------------------------------------------------
+    @property
+    def _tasks_seq(self) -> CommentedSeq:
+        return self.data.setdefault("tasks", CommentedSeq())
+
+    @property
+    def _days_seq(self) -> CommentedSeq:
+        return self.data.setdefault("days", CommentedSeq())
+
+    def all_tasks(self) -> list[Task]:
+        self._sync()
+        return [Task(raw) for raw in self._tasks_seq]
+
+    def get_task(self, task_id: str) -> Task:
+        self._sync()
+        for raw in self._tasks_seq:
+            if raw["id"] == task_id:
+                return Task(raw)
+        raise KeyError(task_id)
+
+    def _existing_ids(self) -> set[str]:
+        return {raw["id"] for raw in self._tasks_seq}
+
+    def add_task(
+        self,
+        title: str,
+        *,
+        target: Optional[date] = None,
+        tags: Optional[list[str]] = None,
+        recur: Optional[str] = None,
+        now: Optional[datetime] = None,
+    ) -> Task:
+        self._sync()
+        now = now or self.now()
+        today = self.today(now)
+        target = target or today
+
+        self.ensure_day(now=now)
+
+        task_id = generate_task_id(self._existing_ids())
+        task = Task.new(
+            task_id=task_id, title=title, target=target, created=now, tags=tags, recur=recur
+        )
+        self._tasks_seq.append(task.raw)
+
+        if target == today:
+            self._get_day_record(today)["extras"].append(task_id)
+
+        self.save()
+        return task
+
+    def set_task_status(
+        self, task_id: str, status: TaskStatus, now: Optional[datetime] = None
+    ) -> Task:
+        self._sync()
+        now = now or self.now()
+        self.ensure_day(now=now)
+        task = self.get_task(task_id)
+        changed = task.set_status(status, now)
+        if changed and status is TaskStatus.DONE:
+            self._spawn_next_if_recurring(task, now)
+        self.save()
+        return task
+
+    def update_task(
+        self,
+        task_id: str,
+        *,
+        title: Optional[str] = None,
+        target: Optional[date] = None,
+        tags: Optional[list[str]] = None,
+        status: Optional[TaskStatus] = None,
+        recur: object = _UNSET,
+        now: Optional[datetime] = None,
+    ) -> Task:
+        """Edit title/target/tags/status/recur of an existing task.
+
+        Raises KeyError (unknown id) or InvalidTransitionError (bad status
+        edge). Retargeting onto today adds the task to today's `extras` —
+        it counts toward delivery if done, but never inflates the goal.
+        `recur` uses a sentinel: omitted = unchanged; None = end the series.
+        """
+        self._sync()
+        now = now or self.now()
+        today = self.today(now)
+        self.ensure_day(now=now)
+        task = self.get_task(task_id)
+
+        if title is not None:
+            task.title = title
+        if tags is not None:
+            task.tags = tags
+        if recur is not _UNSET:
+            task.recur = recur  # type: ignore[assignment]
+        if target is not None and target != task.target:
+            task.target = target
+            if target == today:
+                day_record = self._get_day_record(today)
+                snapshot_ids = list(day_record.get("snapshot", []))
+                extras_ids = list(day_record.get("extras", []))
+                if task_id not in snapshot_ids and task_id not in extras_ids:
+                    day_record["extras"].append(task_id)
+        if status is not None:
+            changed = task.set_status(status, now)
+            if changed and status is TaskStatus.DONE:
+                self._spawn_next_if_recurring(task, now)
+
+        self.save()
+        return task
+
+    def _spawn_next_if_recurring(
+        self, task: Task, now: datetime
+    ) -> Optional[Task]:
+        """Completing a recurring occurrence creates the next one (series rule).
+
+        Cancelling or deleting the open occurrence ends the series. If an
+        open future occurrence of the same series already exists (e.g. the
+        task was reopened and completed again), nothing is created.
+        """
+        recur = task.recur
+        if not recur:
+            return None
+        today = self.today(now)
+        for raw in self._tasks_seq:
+            other = Task(raw)
+            if (
+                other.id != task.id
+                and other.recur == recur
+                and other.title == task.title
+                and other.status in (TaskStatus.TODO, TaskStatus.PAUSED)
+                and other.target > today
+            ):
+                return None
+        target = next_occurrence(recur, max(task.target, today))
+        next_task = Task.new(
+            task_id=generate_task_id(self._existing_ids()),
+            title=task.title,
+            target=target,
+            created=now,
+            tags=task.tags,
+            recur=recur,
+        )
+        self._tasks_seq.append(next_task.raw)
+        return next_task
+
+    # ------------------------------------------------------------------
+    # Days / snapshot lazy / rollover
+    # ------------------------------------------------------------------
+    def _get_day_record(self, day: date) -> Optional[CommentedMap]:
+        for raw in self._days_seq:
+            if _as_date(raw["date"]) == day:
+                return raw
+        return None
+
+    def ensure_day(
+        self, day: Optional[date] = None, now: Optional[datetime] = None
+    ) -> CommentedMap:
+        """Lazily run the day-turnover (rollover + snapshot) for `day`.
+
+        No-op if `day` already has an entry in `days`. Otherwise:
+          1. rollover stale todo/paused tasks (target < day) onto `day`,
+             bumping their migration count;
+          2. snapshot the (now up to date) todo/paused tasks targeting
+             `day` as `goal`/`snapshot`, with empty `extras`.
+        """
+        self._sync()
+        now = now or self.now()
+        target_day = day or self.today(now)
+
+        existing = self._get_day_record(target_day)
+        if existing is not None:
+            return existing
+
+        for raw in self._tasks_seq:
+            task = Task(raw)
+            if task.status in (TaskStatus.TODO, TaskStatus.PAUSED) and task.target < target_day:
+                task.migrate(target_day)
+
+        snapshot_ids = [
+            task.id
+            for task in (Task(raw) for raw in self._tasks_seq)
+            if task.target == target_day and task.status in (TaskStatus.TODO, TaskStatus.PAUSED)
+        ]
+
+        day_record = CommentedMap()
+        day_record["date"] = target_day
+        day_record["goal"] = len(snapshot_ids)
+        day_record["snapshot"] = CommentedSeq(snapshot_ids)
+        day_record["extras"] = CommentedSeq()
+        self._days_seq.append(day_record)
+
+        self.save()
+        return day_record
+
+    def delete_task(self, task_id: str, now: Optional[datetime] = None) -> None:
+        """Remove a task permanently. Raises KeyError if unknown.
+
+        The id is also removed from every day's `extras`, but stays in
+        `snapshot` (the frozen photo): deleting a planned task does NOT
+        reduce that day's goal, same anti-gaming rule as cancelling.
+        """
+        self._sync()
+        now = now or self.now()
+        self.ensure_day(now=now)
+        seq = self._tasks_seq
+        for i, raw in enumerate(seq):
+            if raw["id"] == task_id:
+                del seq[i]
+                break
+        else:
+            raise KeyError(task_id)
+        for day_record in self._days_seq:
+            extras = day_record.get("extras")
+            if extras is not None and task_id in list(extras):
+                extras.remove(task_id)
+        self.save()
+
+    def recorded_days(self) -> list[date]:
+        """Sorted dates of every entry in `days`."""
+        self._sync()
+        return sorted(_as_date(raw["date"]) for raw in self._days_seq)
+
+    # ------------------------------------------------------------------
+    # Metrics
+    # ------------------------------------------------------------------
+    def get_day_metrics(
+        self, day: Optional[date] = None, now: Optional[datetime] = None
+    ) -> DayMetrics:
+        self._sync()
+        now = now or self.now()
+        today = self.today(now)
+        target_day = day or today
+
+        if target_day == today:
+            day_record = self.ensure_day(target_day, now=now)
+        else:
+            day_record = self._get_day_record(target_day)
+
+        if day_record is None:
+            day_record = CommentedMap(
+                date=target_day, goal=0, snapshot=CommentedSeq(), extras=CommentedSeq()
+            )
+
+        goal = int(day_record.get("goal", 0))
+        tasks_by_id = {task.id: task for task in self.all_tasks()}
+
+        snapshot_done = sum(
+            1
+            for task_id in day_record.get("snapshot", [])
+            if tasks_by_id.get(task_id) and tasks_by_id[task_id].status is TaskStatus.DONE
+        )
+        # ids that don't resolve (task deleted / file edited by hand) don't count
+        extras_ids = [
+            task_id for task_id in day_record.get("extras", []) if task_id in tasks_by_id
+        ]
+        extras_done = sum(
+            1 for task_id in extras_ids if tasks_by_id[task_id].status is TaskStatus.DONE
+        )
+        done = snapshot_done + extras_done
+
+        if goal == 0:
+            pct = None if done > 0 else 0.0
+            bonus_day = done > 0
+        else:
+            pct = done / goal * 100
+            bonus_day = False
+
+        return DayMetrics(
+            date=target_day,
+            goal=goal,
+            snapshot_done=snapshot_done,
+            extras_done=extras_done,
+            extras_total=len(extras_ids),
+            done=done,
+            pct=pct,
+            bonus_day=bonus_day,
+            over_delivery=pct is not None and pct > 100,
+        )
+
+
+def _as_date(value: object) -> date:
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    return date.fromisoformat(str(value))

leadger/core/tasks.py

@@ -0,0 +1,161 @@
+"""Task model: a typed view over a YAML task entry, plus its state machine.
+
+`Task` wraps the ruamel CommentedMap loaded from leadger.yaml and mutates
+it in place, so any comments the user attached to that task survive.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from enum import Enum
+from typing import Optional
+
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+
+from .yaml_io import to_yaml_timestamp
+
+
+class TaskStatus(str, Enum):
+    TODO = "todo"
+    DONE = "done"
+    PAUSED = "paused"
+    CANCELLED = "cancelled"
+
+
+class InvalidTransitionError(ValueError):
+    """Raised when a task status transition is not allowed."""
+
+
+# todo <-> paused, todo|paused -> done|cancelled, done|cancelled -> todo
+_VALID_TRANSITIONS: dict[TaskStatus, frozenset[TaskStatus]] = {
+    TaskStatus.TODO: frozenset({TaskStatus.PAUSED, TaskStatus.DONE, TaskStatus.CANCELLED}),
+    TaskStatus.PAUSED: frozenset({TaskStatus.TODO, TaskStatus.DONE, TaskStatus.CANCELLED}),
+    TaskStatus.DONE: frozenset({TaskStatus.TODO}),
+    TaskStatus.CANCELLED: frozenset({TaskStatus.TODO}),
+}
+
+
+def _as_date(value: object) -> date:
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    return date.fromisoformat(str(value))
+
+
+class Task:
+    """Typed view over a task's CommentedMap."""
+
+    def __init__(self, raw: CommentedMap) -> None:
+        self._raw = raw
+
+    @property
+    def raw(self) -> CommentedMap:
+        return self._raw
+
+    @property
+    def id(self) -> str:
+        return self._raw["id"]
+
+    @property
+    def title(self) -> str:
+        return self._raw["title"]
+
+    @title.setter
+    def title(self, value: str) -> None:
+        self._raw["title"] = value
+
+    @property
+    def status(self) -> TaskStatus:
+        return TaskStatus(self._raw["status"])
+
+    @property
+    def target(self) -> date:
+        return _as_date(self._raw["target"])
+
+    @target.setter
+    def target(self, value: date) -> None:
+        self._raw["target"] = value
+
+    @property
+    def created(self) -> datetime:
+        return self._raw["created"]
+
+    @property
+    def completed(self) -> Optional[datetime]:
+        return self._raw.get("completed")
+
+    @property
+    def tags(self) -> list[str]:
+        return list(self._raw.get("tags") or [])
+
+    @tags.setter
+    def tags(self, value: list[str]) -> None:
+        self._raw["tags"] = CommentedSeq(value)
+
+    @property
+    def migrations(self) -> int:
+        return int(self._raw.get("migrations", 0))
+
+    @property
+    def recur(self) -> Optional[str]:
+        """Recurrence spec ("dia" | "seg".."dom") or None. See core/recur.py."""
+        value = self._raw.get("recur")
+        return str(value) if value else None
+
+    @recur.setter
+    def recur(self, value: Optional[str]) -> None:
+        if value:
+            self._raw["recur"] = value
+        else:
+            self._raw.pop("recur", None)
+
+    def migrate(self, new_target: date) -> None:
+        """Roll this task over to `new_target`, bumping its migration count."""
+        self._raw["target"] = new_target
+        self._raw["migrations"] = self.migrations + 1
+
+    def set_status(self, new_status: TaskStatus, now: datetime) -> bool:
+        """Apply a status transition. Returns False if already in that state.
+
+        Raises InvalidTransitionError for disallowed transitions (e.g.
+        done -> paused). Sets/clears `completed` for the done <-> todo edge.
+        """
+        current = self.status
+        if new_status == current:
+            return False
+        allowed = _VALID_TRANSITIONS.get(current, frozenset())
+        if new_status not in allowed:
+            raise InvalidTransitionError(
+                f"Transicao invalida: {current.value} -> {new_status.value}"
+            )
+        self._raw["status"] = new_status.value
+        if new_status is TaskStatus.DONE:
+            self._raw["completed"] = to_yaml_timestamp(now)
+        elif current is TaskStatus.DONE and new_status is TaskStatus.TODO:
+            self._raw["completed"] = None
+        return True
+
+    @classmethod
+    def new(
+        cls,
+        *,
+        task_id: str,
+        title: str,
+        target: date,
+        created: datetime,
+        tags: Optional[list[str]] = None,
+        recur: Optional[str] = None,
+    ) -> "Task":
+        raw = CommentedMap()
+        raw["id"] = task_id
+        raw["title"] = title
+        raw["status"] = TaskStatus.TODO.value
+        raw["target"] = target
+        raw["created"] = to_yaml_timestamp(created)
+        raw["completed"] = None
+        raw["tags"] = CommentedSeq(tags or [])
+        raw["migrations"] = 0
+        if recur:  # only write the key when there is recurrence (lean YAML)
+            raw["recur"] = recur
+        return cls(raw)

leadger/core/time_utils.py

@@ -0,0 +1,43 @@
+"""Timezone-aware 'leadger day' calculations.
+
+The 'leadger day' is the date used for `target`/`days[].date`. It only
+rolls over at `config.day_start`: at 03:00 with day_start=05:00, it's
+still 'yesterday'.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta, timezone
+from zoneinfo import ZoneInfo
+
+
+def now_in_zone(tz_name: str) -> datetime:
+    """Current time in `tz_name`, with a fixed UTC-offset tzinfo.
+
+    A fixed offset (vs. a ZoneInfo) is what ruamel.yaml's round-trip
+    representer needs to dump a clean `+HH:MM`/`-HH:MM` suffix.
+    """
+    return _to_fixed_offset(datetime.now(ZoneInfo(tz_name)))
+
+
+def _to_fixed_offset(dt: datetime) -> datetime:
+    offset = dt.utcoffset()
+    if offset is None:
+        return dt.replace(microsecond=0)
+    total_minutes = int(offset.total_seconds() // 60)
+    sign = "+" if total_minutes >= 0 else "-"
+    hours, minutes = divmod(abs(total_minutes), 60)
+    fixed = timezone(offset, f"{sign}{hours:02d}:{minutes:02d}")
+    return dt.replace(microsecond=0, tzinfo=fixed)
+
+
+def leadger_today(now: datetime, day_start: time) -> date:
+    """The 'leadger day' for `now`, given the configured day_start cutoff."""
+    if now.time() < day_start:
+        return now.date() - timedelta(days=1)
+    return now.date()
+
+
+def parse_day_start(value: str) -> time:
+    hour_str, minute_str = value.split(":")
+    return time(hour=int(hour_str), minute=int(minute_str))

leadger/core/yaml_io.py

@@ -0,0 +1,97 @@
+"""Low-level YAML round-trip IO: atomic writes, backups, corruption handling.
+
+Uses ruamel.yaml in round-trip mode so comments and key order in the
+user's leadger.yaml survive every read/write cycle.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+from ruamel.yaml.error import YAMLError
+from ruamel.yaml.timestamp import TimeStamp
+
+SCHEMA_VERSION = 1
+
+yaml = YAML(typ="rt")
+yaml.indent(mapping=2, sequence=4, offset=2)
+yaml.preserve_quotes = True
+
+
+class CorruptedYAMLError(Exception):
+    """Raised when the data file exists but cannot be parsed safely."""
+
+
+def to_yaml_timestamp(dt: datetime) -> TimeStamp:
+    """Wrap a tz-aware datetime so it dumps as `YYYY-MM-DDTHH:MM:SS+HH:MM`.
+
+    ruamel uses `tzinfo.tzname()` as the dumped suffix, so the tzinfo is
+    normalized to a fixed offset named `+HH:MM`/`-HH:MM` — an unnamed
+    `timezone(timedelta(...))` would dump as `UTC-03:00`, which ruamel
+    cannot parse back.
+    """
+    offset = dt.utcoffset()
+    if offset is not None:
+        total_minutes = int(offset.total_seconds() // 60)
+        sign = "+" if total_minutes >= 0 else "-"
+        hours, minutes = divmod(abs(total_minutes), 60)
+        dt = dt.replace(tzinfo=timezone(offset, f"{sign}{hours:02d}:{minutes:02d}"))
+    ts = TimeStamp(
+        dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second, dt.microsecond, dt.tzinfo
+    )
+    ts._yaml["t"] = True
+    return ts
+
+
+def default_document() -> CommentedMap:
+    """A fresh leadger.yaml document with a minimal commented config."""
+    doc = CommentedMap()
+    doc["version"] = SCHEMA_VERSION
+    config = CommentedMap()
+    config["day_start"] = "05:00"
+    config.yaml_add_eol_comment("hora em que o dia vira", "day_start")
+    config["timezone"] = "America/Sao_Paulo"
+    doc["config"] = config
+    doc["tasks"] = CommentedSeq()
+    doc["days"] = CommentedSeq()
+    return doc
+
+
+def read_yaml(path: Path) -> CommentedMap:
+    """Load `path`, or return a fresh default document if it doesn't exist yet.
+
+    Raises CorruptedYAMLError if the file exists but isn't valid YAML, or its
+    root isn't a mapping. Callers must not write back in that case.
+    """
+    if not path.exists():
+        return default_document()
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data = yaml.load(fh)
+    except YAMLError as exc:
+        raise CorruptedYAMLError(f"{path} nao e um YAML valido: {exc}") from exc
+    if not isinstance(data, CommentedMap):
+        raise CorruptedYAMLError(f"{path} nao tem o formato esperado (mapa no nivel raiz)")
+    data.setdefault("version", SCHEMA_VERSION)
+    data.setdefault("config", CommentedMap())
+    data.setdefault("tasks", CommentedSeq())
+    data.setdefault("days", CommentedSeq())
+    return data
+
+
+def write_yaml_atomic(path: Path, data: CommentedMap) -> None:
+    """Write `data` to `path` atomically, keeping `<path>.bak` of the prior version."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_name(path.name + ".tmp")
+    bak_path = path.with_name(path.name + ".bak")
+
+    with tmp_path.open("w", encoding="utf-8") as fh:
+        yaml.dump(data, fh)
+
+    if path.exists():
+        os.replace(path, bak_path)
+    os.replace(tmp_path, path)