mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-20 12:52:30 +01:00
Some checks failed
dependency freshness / dependencies on newest stable (push) Has been cancelled
earned_time pre-commit / pre-commit (push) Has been cancelled
earned_time tests / test (push) Has been cancelled
file length / file-length (push) Has been cancelled
md-naming / markdown naming convention (push) Has been cancelled
palette drift / palette (push) Has been cancelled
repo-contract / repo contract (push) Has been cancelled
shared gate tests / gate unit tests (push) Has been cancelled
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
154 lines
5.6 KiB
Python
154 lines
5.6 KiB
Python
# Copyright (c) 2026 Krzysztof Rudnicki
|
|
"""Day-scoped questions about a gate's signed ledger: when, and how many.
|
|
|
|
:func:`~earned_time._ledger.done_today` asks "is there a credit yet today?".
|
|
These ask about a whole local day: when the first counting credit happened
|
|
(:func:`first_credit_at`) and how many count (:func:`credit_units`, a counted
|
|
earner's units). The same rules hold: paths are passed in, and ``None`` is
|
|
"could not check", never "no".
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from datetime import date, datetime, time
|
|
import logging
|
|
from typing import TYPE_CHECKING, Final
|
|
|
|
from earned_time._ledger import counting_rows
|
|
from earned_time._match import CREDIT_STAMPS, ROW_UNITS
|
|
from earned_time._quota import DAY_UNITS
|
|
|
|
if TYPE_CHECKING:
|
|
from pathlib import Path
|
|
|
|
from earned_time._policy import Earner, Window
|
|
|
|
_logger: Final = logging.getLogger(__name__)
|
|
|
|
|
|
def day_window(day: date) -> Window:
|
|
"""``day``'s local midnight to its last microsecond, as unix seconds.
|
|
|
|
Each end is localised on its own, so a DST day gets its real length.
|
|
"""
|
|
start = datetime.combine(day, time.min).astimezone()
|
|
end = datetime.combine(day, time.max).astimezone()
|
|
return start.timestamp(), end.timestamp()
|
|
|
|
|
|
def credit_time(earner: Earner, row: dict[str, object]) -> float | None:
|
|
"""When a credit row's work happened, as unix seconds; ``None`` if unusable.
|
|
|
|
The detail field its matcher decides on (``CREDIT_STAMPS``) (LeetCode's
|
|
``submitted_at``, reading's ``ended_at`` -- the stamp ``match`` decides
|
|
on), else the row's ``created_at``.
|
|
"""
|
|
detail = row.get("detail")
|
|
stamp = CREDIT_STAMPS.get(earner.match) if earner.match is not None else None
|
|
if stamp is not None and isinstance(detail, dict):
|
|
try:
|
|
return float(str(detail.get(stamp)))
|
|
except ValueError:
|
|
pass
|
|
raw = row.get("created_at")
|
|
try:
|
|
return datetime.fromisoformat(str(raw)).timestamp()
|
|
except ValueError:
|
|
_logger.warning(
|
|
"%s credit %r has no usable time", earner.label, row.get("entry_id")
|
|
)
|
|
return None
|
|
|
|
|
|
def first_credit_at(
|
|
earner: Earner,
|
|
ledger: Path,
|
|
key_file: Path,
|
|
day: date,
|
|
*,
|
|
gate_off: bool = False,
|
|
) -> float | None:
|
|
"""When ``earner``'s first verified credit that counts for ``day`` happened.
|
|
|
|
Args:
|
|
earner: A ledger-backed earner (it must have ``match``).
|
|
ledger: The gate's ledger file, resolved by the caller.
|
|
key_file: The shared HMAC key, resolved by the caller.
|
|
day: The local day the credit must count for (by ``match``).
|
|
gate_off: Whether the gate is off on ``day`` (``counting_rows``).
|
|
|
|
Returns:
|
|
The earliest :func:`credit_time` among the counting rows, as unix
|
|
seconds. ``None`` when no row counts, or when the ledger or key could
|
|
not be read -- never a time that was not checked.
|
|
|
|
Raises:
|
|
ValueError: ``earner`` has no ``match``; its answer is the consumer's.
|
|
"""
|
|
rows = counting_rows(earner, ledger, key_file, day_window(day), gate_off=gate_off)
|
|
if rows is None:
|
|
return None
|
|
times = [t for t in (credit_time(earner, row) for row in rows) if t is not None]
|
|
return min(times, default=None)
|
|
|
|
|
|
def row_units(earner: Earner, row: dict[str, object]) -> int:
|
|
"""Units one counting row pays: its own count (``ROW_UNITS``), else 1.
|
|
|
|
Only the tutor's rows carry a count (``detail.minutes``, 0.8.0); a row
|
|
whose count is unusable pays 0 (``tutor_match`` already refuses it).
|
|
"""
|
|
reader = ROW_UNITS.get(earner.match) if earner.match is not None else None
|
|
return 1 if reader is None else reader(row) or 0
|
|
|
|
|
|
def credit_units(
|
|
earner: Earner,
|
|
ledger: Path,
|
|
key_file: Path,
|
|
day: date,
|
|
*,
|
|
gate_off: bool = False,
|
|
) -> int | None:
|
|
"""How many units the verified credit rows pay for ``day``.
|
|
|
|
Each row pays :func:`row_units`: 1 for most earners (the workout), its
|
|
``detail.minutes`` for the tutor (a 0.7.0 block row without it, 15), so a
|
|
day mixing block rows and minute rows sums both. From
|
|
``TUTOR_QUOTA_FROM`` the tutor's day sum is then scaled to its weekday
|
|
quota (:func:`~earned_time._quota.tutor_day_units`, 0.10.0): units, no
|
|
longer minutes.
|
|
|
|
Args:
|
|
earner: A ledger-backed earner (it must have ``match``).
|
|
ledger: The gate's ledger file, resolved by the caller.
|
|
key_file: The shared HMAC key, resolved by the caller.
|
|
day: The local day the rows must count for (by ``match``).
|
|
gate_off: Whether the gate is off on ``day`` (``counting_rows``).
|
|
|
|
Returns:
|
|
The sum (``0`` included), or ``None`` when the ledger or key could
|
|
not be read -- never "no units". An ``entry_id`` pays once: rows
|
|
repeated under one id (a replayed write) pay the smallest of their
|
|
counts, so a rewrite can never raise a credit. The earner's
|
|
``max_units`` is applied by :func:`~earned_time.resolve`, not here.
|
|
|
|
Raises:
|
|
ValueError: ``earner`` has no ``match``; its answer is the consumer's.
|
|
"""
|
|
rows = counting_rows(earner, ledger, key_file, day_window(day), gate_off=gate_off)
|
|
if rows is None:
|
|
return None
|
|
by_id: dict[object, int] = {}
|
|
anonymous = 0
|
|
for row in rows:
|
|
units = row_units(earner, row)
|
|
entry_id = row.get("entry_id")
|
|
if entry_id is None:
|
|
anonymous += units
|
|
else:
|
|
by_id[entry_id] = min(units, by_id.get(entry_id, units))
|
|
total = anonymous + sum(by_id.values())
|
|
scale = DAY_UNITS.get(earner.match) if earner.match is not None else None
|
|
return total if scale is None else scale(earner, total, day)
|