mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-22 19:52:27 +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
|
Before `REVIEW_PROGRESS_FROM` the review pays as in 0.23.0 (a yes pays 20, a no
|
||||||
0) and ignores every progress row.
|
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
|
## Not credits
|
||||||
|
|
||||||
A `progress` row has `amount` 0 and its own kind. `done_today`, `credit_units`,
|
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
|
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
|
[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.
|
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)
|
## 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=()) ->
|
- `progress_map(day, home, key_file, *, earners=None, gate_off=()) ->
|
||||||
dict[str, Progress]`, `read_progress(earner, ledger, key_file, day, *,
|
dict[str, Progress]`, `read_progress(earner, ledger, key_file, day, *,
|
||||||
gate_off=False) -> Progress | None`, `Progress(done, target)`,
|
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
|
## The workout ledger
|
||||||
|
|
||||||
|
|||||||
@ -122,6 +122,7 @@ from earned_time._review import (
|
|||||||
paid_reviews,
|
paid_reviews,
|
||||||
review_match,
|
review_match,
|
||||||
)
|
)
|
||||||
|
from earned_time._share import term_for
|
||||||
from earned_time._sick import SICK_SHUTDOWN_FLOOR_MINUTES, sick_shutdown_from
|
from earned_time._sick import SICK_SHUTDOWN_FLOOR_MINUTES, sick_shutdown_from
|
||||||
|
|
||||||
__all__ = [
|
__all__ = [
|
||||||
@ -204,6 +205,7 @@ __all__ = [
|
|||||||
"shutdown_ceiling_for",
|
"shutdown_ceiling_for",
|
||||||
"shutdown_minutes_for",
|
"shutdown_minutes_for",
|
||||||
"sick_shutdown_from",
|
"sick_shutdown_from",
|
||||||
|
"term_for",
|
||||||
"today_window",
|
"today_window",
|
||||||
"tutor_quota_for",
|
"tutor_quota_for",
|
||||||
"verified",
|
"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._floor import gaming_cut, is_penalised, shutdown_floor
|
||||||
from earned_time._gaming import gaming_enforced
|
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._leisure import base_minutes, ceiling_minutes, is_leisure
|
||||||
from earned_time._registry import all_earners, earners_for
|
from earned_time._registry import all_earners, earners_for
|
||||||
from earned_time._resolution import Base, Resolution, Term
|
from earned_time._resolution import Base, Resolution, Term
|
||||||
from earned_time._review import ReviewEarner
|
from earned_time._share import term_for
|
||||||
from earned_time._share import review_term, share_term
|
|
||||||
from earned_time._sick import sick_or
|
from earned_time._sick import sick_or
|
||||||
|
|
||||||
if TYPE_CHECKING:
|
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(
|
def _check_registered(
|
||||||
answers: Mapping[str, Answer], registry: tuple[Earner, ...]
|
answers: Mapping[str, Answer], registry: tuple[Earner, ...]
|
||||||
) -> None:
|
) -> None:
|
||||||
@ -113,31 +106,17 @@ def _term(
|
|||||||
) -> Term:
|
) -> Term:
|
||||||
"""``item``'s term on ``day``; no answer at all is logged and earns nothing.
|
"""``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
|
The pay itself is :func:`~earned_time.term_for`, shared with every consumer.
|
||||||
``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).
|
|
||||||
"""
|
"""
|
||||||
if item.name not in answers:
|
if item.name not in answers:
|
||||||
_logger.warning(
|
_logger.warning(
|
||||||
"No answer for the %s earner; it earns nothing today", item.label
|
"No answer for the %s earner; it earns nothing today", item.label
|
||||||
)
|
)
|
||||||
units = _units(answers.get(item.name))
|
return term_for(
|
||||||
if isinstance(item, ReviewEarner):
|
item,
|
||||||
if day >= REVIEW_PROGRESS_FROM:
|
day,
|
||||||
return review_term(item, units, day, progress)
|
answer=answers.get(item.name),
|
||||||
progress = None
|
progress=(progress or {}).get(item.name),
|
||||||
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),
|
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@ -11,11 +11,11 @@ from __future__ import annotations
|
|||||||
import logging
|
import logging
|
||||||
from typing import TYPE_CHECKING, Final
|
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._resolution import Term
|
||||||
|
from earned_time._review import ReviewEarner
|
||||||
|
|
||||||
if TYPE_CHECKING:
|
if TYPE_CHECKING:
|
||||||
from collections.abc import Mapping
|
|
||||||
from datetime import date
|
from datetime import date
|
||||||
|
|
||||||
from earned_time._policy import Earner
|
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(
|
def _review_term(
|
||||||
item: Earner,
|
item: Earner, units: int | None, day: date, progress: Progress | None
|
||||||
units: int | None,
|
|
||||||
day: date,
|
|
||||||
progress: Mapping[str, Progress] | None,
|
|
||||||
) -> Term:
|
) -> Term:
|
||||||
"""The review's term from ``REVIEW_PROGRESS_FROM``: a credited review needs a row.
|
"""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
|
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.
|
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:
|
if units and share is None:
|
||||||
_logger.warning(
|
_logger.warning(
|
||||||
"%s credited with no progress row on %s; it pays nothing",
|
"%s credited with no progress row on %s; it pays nothing",
|
||||||
@ -85,3 +82,49 @@ def review_term(
|
|||||||
if share is None:
|
if share is None:
|
||||||
return Term(item, units, 0, 0)
|
return Term(item, units, 0, 0)
|
||||||
return share_term(item, units, day, share)
|
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