steam-backlog-enforcer/steam_backlog_enforcer/_gaming_days.py
Krzysztof kuhy Rudnicki 9586128163 Carry unspent Fri-Sun gaming time to the rest of the Fri-Mon block
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-10-02 21:07:49 +02:00

148 lines
4.6 KiB
Python

"""Gaming-day arithmetic: which day *now* is, and what it inherits.
A gaming "day" runs 06:00-05:59 local, so late-night sessions count against
the day they started in.
**Free-day carry-over.** Friday to Monday is one block. Whatever a Friday,
Saturday or Sunday leaves unspent is split evenly, with no strings attached,
across the days still left in that block:
Fri leftover -> Sat, Sun, Mon (a third each)
Sat leftover -> Sun, Mon (half each)
Sun leftover -> Mon
Monday's leftover, and any Tuesday-Thursday leftover, is dropped. A day's
leftover is measured against its whole budget *including* what it inherited,
so time carried into Saturday and not played moves on to Sunday and Monday
rather than being lost.
The ledger lives on ``PlaytimeState`` -- root-owned and immutable -- and never
in ``playtime_history.json``: that file is user-writable, and a stored budget
read from it would let anyone grant themselves unlimited time.
Everything here is pure: it works on primitives handed to it, so it imports
nothing from the playtime modules and cannot close an import cycle.
"""
from __future__ import annotations
from datetime import date, timedelta
from typing import TYPE_CHECKING, Final
if TYPE_CHECKING:
from datetime import datetime
from steam_backlog_enforcer._playtime_state import PlaytimeState
# The gaming day starts here, local time. 05:59 belongs to the previous day.
_DAY_BOUNDARY_HOURS: Final = 6
# Weekday (Monday == 0) whose leftover is passed on -> how many later days of
# the Friday-Monday block share it.
_SHARES: Final = {4: 3, 5: 2, 6: 1}
def gaming_day_key(now: datetime) -> str:
"""Return the ``YYYY-MM-DD`` gaming day containing *now*.
The boundary is 06:00 local, so 02:00 on the 5th belongs to the 4th.
Args:
now: Timezone-aware local timestamp.
Returns:
The gaming day key.
"""
return (now - timedelta(hours=_DAY_BOUNDARY_HOURS)).date().isoformat()
def pass_on(
carry: dict[str, float],
*,
outgoing_day: str,
budget: float,
spent: float,
new_day: str,
) -> dict[str, float]:
"""Return the carry ledger as it stands once *new_day* begins.
Shares owed to days before *new_day* are dropped, which both bounds the
ledger and means a day the daemon never saw simply forfeits its share.
Args:
carry: Day key to seconds owed, as held by the outgoing day.
outgoing_day: The gaming day that just ended; ``""`` if none.
budget: The outgoing day's budget, carry included.
spent: Seconds billed during the outgoing day.
new_day: The gaming day now starting.
Returns:
The ledger for *new_day*, the outgoing day's leftover added.
"""
owed = {day: seconds for day, seconds in carry.items() if day >= new_day}
if not outgoing_day:
return owed
ended = date.fromisoformat(outgoing_day)
shares = _SHARES.get(ended.weekday(), 0)
leftover = max(0.0, budget - spent)
for offset in range(1, shares + 1):
target = (ended + timedelta(days=offset)).isoformat()
if target >= new_day:
owed[target] = owed.get(target, 0.0) + leftover / shares
return owed
def carry_due(
carry: dict[str, float],
*,
stored_day: str,
budget: float,
spent: float,
today: str,
) -> float:
"""Return the seconds carried into *today*.
The stored record may still describe yesterday -- the first tick after
06:00 resolves the budget before rolling the state over -- so the ledger is
projected forward exactly as ``roll_over`` will do it.
Args:
carry: The stored ledger.
stored_day: The gaming day the stored record covers.
budget: That day's budget, carry included.
spent: Seconds billed during that day.
today: The current gaming day.
Returns:
Seconds inherited by *today*, or 0.
"""
owed = (
carry
if stored_day == today
else pass_on(
carry, outgoing_day=stored_day, budget=budget, spent=spent, new_day=today
)
)
return owed.get(today, 0.0)
def carry_into(stored: PlaytimeState | None, now: datetime) -> float:
"""Return the seconds carried into the gaming day containing *now*.
Args:
stored: The persisted production state, or ``None`` if unreadable.
now: Local timestamp for this tick.
Returns:
The carry owed to today; 0 when no state is recorded.
"""
if stored is None:
return 0.0
return carry_due(
stored.carry,
stored_day=stored.day_key,
budget=stored.budget_seconds,
spent=stored.seconds,
today=gaming_day_key(now),
)