utils/freedays/freedays/_model.py
Krzysztof kuhy Rudnicki 6154dc09bf Pin pre-commit's ruff to 0.16.7 and satisfy the CPY001 it brings
The three Python packages pinned ruff twice at different versions:
requirements.txt at 0.16.7, .pre-commit-config.yaml at v0.15.2. Only the
older one ever ran, so `select = ["ALL"]` was enforced two minor versions
behind. Measured before aligning: v0.15.2 reports 0 findings, every 0.16.x
reports CPY001 on each file -- 70 crdt-sync, 23 freedays, 71 gatelock, and
no other rule.

Resolved by adding the notice rather than ignoring the rule, so the gate
keeps its teeth.

Two gatelock modules sat at exactly the 250-line cap, so a one-line header
tipped them to 251. Both are split along a real seam rather than shaved:

  _widget_fills.py    colour arithmetic over LockConfig, no tkinter import
  _surfaces_focus.py  selects among existing surfaces, never mutates them

The focus split keeps _surfaces.py's documented containment (it stays the
only module that creates, moves or destroys windows), and the static guard
in test_recovery_invariants.py globs _surfaces*.py, so the new sibling is
covered with no list to extend. widgets.py re-exports the fills helpers,
which keeps gatelock.widgets the single public surface its tests import.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019kMvSMtsVMB3d2uoZ56pbp
2026-09-12 18:11:24 +02:00

133 lines
4.1 KiB
Python

# Copyright (c) 2026 Krzysztof Rudnicki
"""Translating between a free day and a crdt-sync ``Record``.
The record id *is* the ISO date, so two devices marking the same day produce
the same record and converge instead of accumulating duplicates. Marking and
un-marking are a last-writer-wins flip of one field rather than a create and
a delete, because crdt-sync tombstones are monotonic -- deleting the record
would burn that date permanently.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import TYPE_CHECKING
from crdt_sync import Hlc, Record
from freedays._constants import (
FIELD_ACTOR,
FIELD_CONSUMED,
FIELD_REASON,
FIELD_STATE,
STATE_CLEARED,
STATE_FREE,
)
from freedays._day import parse_iso, to_iso
if TYPE_CHECKING:
from datetime import date
from crdt_sync import Log
@dataclass(frozen=True)
class FreeDay:
"""One day's entry, as the rest of the package wants to see it.
Attributes:
day: The calendar date.
is_free: Whether the day currently stands the gates down.
consumed: Whether the day arrived while free, and so stays spent even
after being released.
actor: Which device last changed it.
reason: Optional free text. Never required -- a free day carries no
justification burden by design.
"""
day: date
is_free: bool
consumed: bool = False
actor: str = ""
reason: str = ""
def _field_str(record: Record, name: str) -> str:
field = record.fields.get(name)
if field is None:
return ""
value = field[0]
return value if isinstance(value, str) else ""
def is_consumed_record(record: Record) -> bool:
"""Whether ``record``'s day is spent regardless of its current state."""
field = record.fields.get(FIELD_CONSUMED)
return bool(field[0]) if field is not None else False
def is_free_record(record: Record) -> bool:
"""Whether ``record`` currently marks its day free.
A tombstoned record counts as not free: nothing in this package creates
one, but a hand-edited or future-format log might, and "not free" is the
safe reading of a record we do not understand.
"""
if record.deleted:
return False
return _field_str(record, FIELD_STATE) == STATE_FREE
def to_free_day(record: Record) -> FreeDay | None:
"""Build a :class:`FreeDay` from ``record``, or None if its id is junk."""
try:
day = parse_iso(record.id)
except ValueError:
return None
return FreeDay(
day=day,
is_free=is_free_record(record),
consumed=is_consumed_record(record),
actor=_field_str(record, FIELD_ACTOR),
reason=_field_str(record, FIELD_REASON),
)
def latest_hlc(log: Log, node_id: str) -> Hlc | None:
"""Return the greatest clock this node has issued anywhere in ``log``.
Feeding this back into :meth:`Hlc.new_tick` keeps the node's clock
monotonic across process restarts, which is what stops a fresh process
from issuing a tick that loses to its own earlier write.
"""
ticks = [
hlc
for record in log.values()
for _, hlc in record.fields.values()
if hlc.node_id == node_id
]
return max(ticks) if ticks else None
def build_record(entry: FreeDay, hlc: Hlc) -> Record:
"""Return the record expressing ``entry``, stamped with ``hlc``.
Every field carries the same tick, so a concurrent mark and un-mark of
one day resolve together rather than interleaving into a state from one
device and a reason from the other.
``entry.consumed`` is only ever ``True`` when the caller has already
established the day has arrived; no caller writes it back to ``False``
over a ``True``, which is what keeps it sticky across merges.
"""
state = STATE_FREE if entry.is_free else STATE_CLEARED
return Record(
id=to_iso(entry.day),
fields={
FIELD_STATE: (state, hlc),
FIELD_CONSUMED: (entry.consumed, hlc),
FIELD_ACTOR: (entry.actor, hlc),
FIELD_REASON: (entry.reason, hlc),
},
)