mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-22 19:32:25 +01:00
Export term_for: one derivation of a term
Some checks are pending
earned_time pre-commit / pre-commit (push) Waiting to run
earned_time tests / test (push) Waiting to run
file length / file-length (push) Waiting to run
gatelock tests / test (push) Waiting to run
kuhy_credit drift / drift (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
palette drift / palette (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
shared gate tests / gate unit tests (push) Waiting to run
Some checks are pending
earned_time pre-commit / pre-commit (push) Waiting to run
earned_time tests / test (push) Waiting to run
file length / file-length (push) Waiting to run
gatelock tests / test (push) Waiting to run
kuhy_credit drift / drift (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
palette drift / palette (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
shared gate tests / gate unit tests (push) Waiting to run
term_for(earner, day, *, answer, progress=None) returns the Term an earner pays: the ladder rung, the share of a row, the full-pay cap and the review's dated rule. resolve builds every term through it, so a consumer pricing one earner cannot disagree with resolve and never re-derives a share. A grid test pins term_for == resolve's term for every earner, answer, row and day either side of REVIEW_PROGRESS_FROM, and a second test checks the minutes against the written rules, not the library code. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WzxdWZLyjnLjB1THD6ckou
This commit is contained in:
parent
77827e9abb
commit
c06f2daa9a
@ -103,6 +103,25 @@ earners:
|
||||
Before `REVIEW_PROGRESS_FROM` the review pays as in 0.23.0 (a yes pays 20, a no
|
||||
0) and ignores every progress row.
|
||||
|
||||
## One derivation: `term_for`
|
||||
|
||||
`term_for(earner, day, *, answer, progress=None) -> Term` is the only place an
|
||||
earner's pay for a day is derived, and `resolve` builds every one of its terms
|
||||
through it. A consumer that prices one earner (the screen-locker's live pass)
|
||||
reads the row with `read_progress` and calls it; it reads `shutdown_minutes`
|
||||
and `gaming_minutes` off the `Term`. **Consumers never re-derive a share**: the
|
||||
review's dated rule, the ladder rung, the floor and the cap at full all live
|
||||
here, and a local `full * done // target` goes stale the day a rule changes.
|
||||
|
||||
```python
|
||||
fact = earned_time.read_progress(earner, ledger, key_file, day, gate_off=off)
|
||||
pay = earned_time.term_for(earner, day, answer=answer, progress=fact).shutdown_minutes
|
||||
```
|
||||
|
||||
`answer` is the unit count (`True`/`False` are 1/0) or `None`; `progress` is the
|
||||
verified row or `None`. A test pins that the two always agree for every earner,
|
||||
answer, row and day either side of `REVIEW_PROGRESS_FROM`.
|
||||
|
||||
## Not credits
|
||||
|
||||
A `progress` row has `amount` 0 and its own kind. `done_today`, `credit_units`,
|
||||
|
||||
@ -130,6 +130,8 @@ nothing, as ever; with no row anywhere every output is 0.23.0's, the review
|
||||
excepted. The row, the reader and every fail-closed case are in
|
||||
[DOCS-progress.md](DOCS-progress.md). The review differs from `REVIEW_PROGRESS_FROM` (2026-11-24): a credited review
|
||||
pays only by its row (`20 * done // target`), and with no verified row pays 0.
|
||||
One earner's pay for a day is `term_for(earner, day, *, answer, progress=None)`,
|
||||
the code `resolve` itself uses: consumers never re-derive a share.
|
||||
|
||||
## Gate maturity (0.6.0)
|
||||
|
||||
@ -168,7 +170,8 @@ How far to trust a gate, computed from its ledger by `maturity()`, is in
|
||||
- `progress_map(day, home, key_file, *, earners=None, gate_off=()) ->
|
||||
dict[str, Progress]`, `read_progress(earner, ledger, key_file, day, *,
|
||||
gate_off=False) -> Progress | None`, `Progress(done, target)`,
|
||||
`Earner.progress_source`, `Term.progress`, `REVIEW_PROGRESS_FROM` (0.24.0).
|
||||
`Earner.progress_source`, `Term.progress`, `REVIEW_PROGRESS_FROM`,
|
||||
`term_for(earner, day, *, answer, progress=None) -> Term` (0.24.0).
|
||||
|
||||
## The workout ledger
|
||||
|
||||
|
||||
@ -122,6 +122,7 @@ from earned_time._review import (
|
||||
paid_reviews,
|
||||
review_match,
|
||||
)
|
||||
from earned_time._share import term_for
|
||||
from earned_time._sick import SICK_SHUTDOWN_FLOOR_MINUTES, sick_shutdown_from
|
||||
|
||||
__all__ = [
|
||||
@ -204,6 +205,7 @@ __all__ = [
|
||||
"shutdown_ceiling_for",
|
||||
"shutdown_minutes_for",
|
||||
"sick_shutdown_from",
|
||||
"term_for",
|
||||
"today_window",
|
||||
"tutor_quota_for",
|
||||
"verified",
|
||||
|
||||
@ -27,12 +27,11 @@ from typing import TYPE_CHECKING, Final
|
||||
|
||||
from earned_time._floor import gaming_cut, is_penalised, shutdown_floor
|
||||
from earned_time._gaming import gaming_enforced
|
||||
from earned_time._ladder import REVIEW_PROGRESS_FROM, shutdown_ceiling_for
|
||||
from earned_time._ladder import shutdown_ceiling_for
|
||||
from earned_time._leisure import base_minutes, ceiling_minutes, is_leisure
|
||||
from earned_time._registry import all_earners, earners_for
|
||||
from earned_time._resolution import Base, Resolution, Term
|
||||
from earned_time._review import ReviewEarner
|
||||
from earned_time._share import review_term, share_term
|
||||
from earned_time._share import term_for
|
||||
from earned_time._sick import sick_or
|
||||
|
||||
if TYPE_CHECKING:
|
||||
@ -88,12 +87,6 @@ def _base(
|
||||
)
|
||||
|
||||
|
||||
def _units(answer: Answer) -> int | None:
|
||||
if answer is None:
|
||||
return None
|
||||
return max(0, int(answer))
|
||||
|
||||
|
||||
def _check_registered(
|
||||
answers: Mapping[str, Answer], registry: tuple[Earner, ...]
|
||||
) -> None:
|
||||
@ -113,31 +106,17 @@ def _term(
|
||||
) -> Term:
|
||||
"""``item``'s term on ``day``; no answer at all is logged and earns nothing.
|
||||
|
||||
Progress pays only a no (``0``/``False``): a yes pays in full as ever and
|
||||
``None`` ("could not check") earns nothing, row or no row. The review is
|
||||
the exception (:func:`~earned_time._share.review_term`): from
|
||||
``REVIEW_PROGRESS_FROM`` only a yes pays, and only by its row; before it
|
||||
progress is ignored (0.23.0).
|
||||
The pay itself is :func:`~earned_time.term_for`, shared with every consumer.
|
||||
"""
|
||||
if item.name not in answers:
|
||||
_logger.warning(
|
||||
"No answer for the %s earner; it earns nothing today", item.label
|
||||
)
|
||||
units = _units(answers.get(item.name))
|
||||
if isinstance(item, ReviewEarner):
|
||||
if day >= REVIEW_PROGRESS_FROM:
|
||||
return review_term(item, units, day, progress)
|
||||
progress = None
|
||||
no = units is not None and units < 1
|
||||
share = (progress or {}).get(item.name) if no else None
|
||||
if share is not None:
|
||||
return share_term(item, units, day, share)
|
||||
count = units or 0
|
||||
return Term(
|
||||
earner=item,
|
||||
answer=units,
|
||||
gaming_minutes=item.gaming_for(count),
|
||||
shutdown_minutes=item.shutdown_for(count, day),
|
||||
return term_for(
|
||||
item,
|
||||
day,
|
||||
answer=answers.get(item.name),
|
||||
progress=(progress or {}).get(item.name),
|
||||
)
|
||||
|
||||
|
||||
|
||||
@ -11,11 +11,11 @@ from __future__ import annotations
|
||||
import logging
|
||||
from typing import TYPE_CHECKING, Final
|
||||
|
||||
from earned_time._ladder import shutdown_minutes_for
|
||||
from earned_time._ladder import REVIEW_PROGRESS_FROM, shutdown_minutes_for
|
||||
from earned_time._resolution import Term
|
||||
from earned_time._review import ReviewEarner
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from collections.abc import Mapping
|
||||
from datetime import date
|
||||
|
||||
from earned_time._policy import Earner
|
||||
@ -61,11 +61,8 @@ def share_term(item: Earner, units: int | None, day: date, share: Progress) -> T
|
||||
)
|
||||
|
||||
|
||||
def review_term(
|
||||
item: Earner,
|
||||
units: int | None,
|
||||
day: date,
|
||||
progress: Mapping[str, Progress] | None,
|
||||
def _review_term(
|
||||
item: Earner, units: int | None, day: date, progress: Progress | None
|
||||
) -> Term:
|
||||
"""The review's term from ``REVIEW_PROGRESS_FROM``: a credited review needs a row.
|
||||
|
||||
@ -75,7 +72,7 @@ def review_term(
|
||||
logged). A no and ``None`` pay 0 whatever a row says, since the guard's
|
||||
accepted submission, not the row, is the evidence a review happened.
|
||||
"""
|
||||
share = (progress or {}).get(item.name) if units else None
|
||||
share = progress if units else None
|
||||
if units and share is None:
|
||||
_logger.warning(
|
||||
"%s credited with no progress row on %s; it pays nothing",
|
||||
@ -85,3 +82,49 @@ def review_term(
|
||||
if share is None:
|
||||
return Term(item, units, 0, 0)
|
||||
return share_term(item, units, day, share)
|
||||
|
||||
|
||||
def term_for(
|
||||
earner: Earner,
|
||||
day: date,
|
||||
*,
|
||||
answer: int | bool | None,
|
||||
progress: Progress | None = None,
|
||||
) -> Term:
|
||||
"""What ``earner`` pays on ``day``: the one derivation, for every consumer.
|
||||
|
||||
:func:`~earned_time.resolve` builds each of its terms here, so a consumer
|
||||
pricing one earner (the screen-locker's live pass) cannot disagree with it:
|
||||
consumers never re-derive a share. Read ``shutdown_minutes`` and
|
||||
``gaming_minutes`` off the result; ``Term.progress`` is the row it was
|
||||
paid from.
|
||||
|
||||
Args:
|
||||
earner: The earner (its ladder rung on ``day`` is the full pay).
|
||||
day: The day priced.
|
||||
answer: The consumer's answer: a unit count (``True``/``False`` are
|
||||
1/0), or ``None`` for "could not check", which earns nothing.
|
||||
progress: The earner's verified signed row for ``day``
|
||||
(:func:`~earned_time.read_progress`), or ``None`` for no row.
|
||||
|
||||
Returns:
|
||||
The term. A yes pays full as ever. A no pays ``full * done // target``
|
||||
of ``progress``, floored, never above full, and nothing without a row.
|
||||
The review is the exception: from ``REVIEW_PROGRESS_FROM`` only a yes
|
||||
pays, only by its row, and a yes with no row pays 0; before it the row
|
||||
is ignored (0.23.0).
|
||||
"""
|
||||
units = None if answer is None else max(0, int(answer))
|
||||
if isinstance(earner, ReviewEarner):
|
||||
if day >= REVIEW_PROGRESS_FROM:
|
||||
return _review_term(earner, units, day, progress)
|
||||
progress = None
|
||||
if progress is not None and units is not None and units < 1:
|
||||
return share_term(earner, units, day, progress)
|
||||
count = units or 0
|
||||
return Term(
|
||||
earner=earner,
|
||||
answer=units,
|
||||
gaming_minutes=earner.gaming_for(count),
|
||||
shutdown_minutes=earner.shutdown_for(count, day),
|
||||
)
|
||||
|
||||
142
earned_time/earned_time/tests/test_term_for.py
Normal file
142
earned_time/earned_time/tests/test_term_for.py
Normal file
@ -0,0 +1,142 @@
|
||||
# Copyright (c) 2026 Krzysztof Rudnicki
|
||||
"""``term_for``: the one place an earner's pay for a day is derived.
|
||||
|
||||
``resolve`` builds its terms through it, so a consumer pricing one earner (the
|
||||
screen-locker's live pass) can never disagree with ``resolve``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import date
|
||||
from itertools import product
|
||||
from typing import Any
|
||||
|
||||
import pytest
|
||||
|
||||
from earned_time import (
|
||||
LEETCODE,
|
||||
REVIEW,
|
||||
REVIEW_PROGRESS_FROM,
|
||||
WORKOUT,
|
||||
Earner,
|
||||
Progress,
|
||||
Term,
|
||||
earners_for,
|
||||
resolve,
|
||||
shutdown_minutes_for,
|
||||
term_for,
|
||||
)
|
||||
|
||||
DAYS = (
|
||||
date(2026, 10, 5),
|
||||
date(2026, 10, 16),
|
||||
date(2026, 11, 22),
|
||||
REVIEW_PROGRESS_FROM.replace(day=REVIEW_PROGRESS_FROM.day - 1),
|
||||
REVIEW_PROGRESS_FROM,
|
||||
REVIEW_PROGRESS_FROM.replace(day=REVIEW_PROGRESS_FROM.day + 1),
|
||||
date(2027, 1, 1),
|
||||
)
|
||||
ANSWERS: tuple[int | bool | None, ...] = (True, False, None, 0, 1, 2)
|
||||
FACTS: tuple[Progress | None, ...] = (
|
||||
None,
|
||||
Progress(0, 3),
|
||||
Progress(1, 3),
|
||||
Progress(2, 3),
|
||||
Progress(3, 3),
|
||||
Progress(1, 1),
|
||||
Progress(7, 2),
|
||||
)
|
||||
LADDER = date(2026, 11, 22)
|
||||
|
||||
|
||||
def test_the_signature_is_keyword_clear() -> None:
|
||||
loose: Any = term_for
|
||||
with pytest.raises(TypeError):
|
||||
loose(LEETCODE, LADDER, 1)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("day", DAYS)
|
||||
def test_term_for_equals_the_term_resolve_builds(day: date) -> None:
|
||||
for item, answer, fact in product(earners_for(day), ANSWERS, FACTS):
|
||||
others = {e.name: 0 for e in earners_for(day)}
|
||||
asked = resolve(
|
||||
{**others, item.name: answer},
|
||||
day,
|
||||
progress=None if fact is None else {item.name: fact},
|
||||
).term(item.name)
|
||||
got = term_for(item, day, answer=answer, progress=fact)
|
||||
assert got == asked, (item.name, day, answer, fact)
|
||||
assert isinstance(got, Term)
|
||||
|
||||
|
||||
def test_a_generic_earner_pays_a_share_of_the_ladder_rung() -> None:
|
||||
full = shutdown_minutes_for(LEETCODE, LADDER)
|
||||
assert full == 60
|
||||
row = Progress(1, 3)
|
||||
assert term_for(LEETCODE, LADDER, answer=False, progress=row).shutdown_minutes == 20
|
||||
assert term_for(LEETCODE, LADDER, answer=False, progress=row).gaming_minutes == 20
|
||||
assert term_for(LEETCODE, LADDER, answer=False).shutdown_minutes == 0
|
||||
|
||||
|
||||
def test_a_yes_pays_full_whatever_the_row_says() -> None:
|
||||
low = term_for(LEETCODE, LADDER, answer=True, progress=Progress(1, 3))
|
||||
assert low.shutdown_minutes == shutdown_minutes_for(LEETCODE, LADDER)
|
||||
assert low.progress is None
|
||||
|
||||
|
||||
def test_a_row_never_pays_above_full() -> None:
|
||||
term = term_for(LEETCODE, LADDER, answer=False, progress=Progress(9, 3))
|
||||
assert term.shutdown_minutes == shutdown_minutes_for(LEETCODE, LADDER)
|
||||
|
||||
|
||||
def test_none_earns_nothing_even_with_a_full_row() -> None:
|
||||
assert term_for(LEETCODE, LADDER, answer=None, progress=Progress(3, 3)) == Term(
|
||||
LEETCODE, None, 0, 0
|
||||
)
|
||||
|
||||
|
||||
def test_the_review_follows_its_dated_rule() -> None:
|
||||
row = Progress(1, 3)
|
||||
before = REVIEW_PROGRESS_FROM.replace(day=REVIEW_PROGRESS_FROM.day - 1)
|
||||
assert term_for(REVIEW, before, answer=True, progress=row).shutdown_minutes == 20
|
||||
assert term_for(REVIEW, before, answer=False, progress=row).shutdown_minutes == 0
|
||||
on = REVIEW_PROGRESS_FROM
|
||||
assert term_for(REVIEW, on, answer=True, progress=row).shutdown_minutes == 6
|
||||
assert term_for(REVIEW, on, answer=True).shutdown_minutes == 0
|
||||
assert term_for(REVIEW, on, answer=False, progress=row).shutdown_minutes == 0
|
||||
|
||||
|
||||
def test_a_counted_earner_pays_per_unit() -> None:
|
||||
day = LADDER
|
||||
one = term_for(WORKOUT, day, answer=1).shutdown_minutes
|
||||
assert term_for(WORKOUT, day, answer=True).shutdown_minutes == one
|
||||
assert term_for(WORKOUT, day, answer=0).shutdown_minutes == 0
|
||||
|
||||
|
||||
def _expected(
|
||||
item: Earner, day: date, answer: int | None, fact: Progress | None
|
||||
) -> int:
|
||||
"""The shutdown minutes by the written rules, not by the library's code."""
|
||||
if answer is None:
|
||||
return 0
|
||||
full = shutdown_minutes_for(item, day)
|
||||
yes = answer is True or answer >= 1
|
||||
if item is REVIEW and day >= REVIEW_PROGRESS_FROM:
|
||||
if not yes or fact is None:
|
||||
return 0
|
||||
return full * min(fact.done, fact.target) // fact.target
|
||||
if yes or (item is REVIEW) or fact is None:
|
||||
return item.shutdown_for(max(0, int(answer)), day)
|
||||
return full * min(fact.done, fact.target) // fact.target
|
||||
|
||||
|
||||
@pytest.mark.parametrize("day", DAYS)
|
||||
def test_the_minutes_follow_the_written_rules(day: date) -> None:
|
||||
for item, answer, fact in product(earners_for(day), ANSWERS, FACTS):
|
||||
got = term_for(item, day, answer=answer, progress=fact)
|
||||
assert got.shutdown_minutes == _expected(item, day, answer, fact), (
|
||||
item.name,
|
||||
day,
|
||||
answer,
|
||||
fact,
|
||||
)
|
||||
Loading…
Reference in New Issue
Block a user