steam-backlog-enforcer/steam_backlog_enforcer/_hltb_confidence.py

"""Cached HowLongToBeat confidence lookups.

Split out of :mod:`steam_backlog_enforcer.hltb` to keep both files
under the 250-line cap.
"""

from __future__ import annotations

import logging
import time

from steam_backlog_enforcer._hltb_cached import reporting_progress_cb
from steam_backlog_enforcer._hltb_failures import HLTBUnavailableError
from steam_backlog_enforcer._hltb_types import (
    HLTB_BASE_URL,
    ProgressCb,
    _HLTBExtras,
    load_hltb_cache,
    load_hltb_count_comp_cache,
    load_hltb_game_id_cache,
    load_hltb_leisure_100h_cache,
    load_hltb_polls_cache,
    load_hltb_rush_cache,
    restore_prior_hours,
    save_hltb_cache,
)
from steam_backlog_enforcer.hltb import (
    fetch_hltb_confidence,
    fetch_hltb_times,
    fetch_hltb_times_timed,
    games_per_second,
)

logger = logging.getLogger(__name__)


# ──────────────────────────────────────────────────────────────
# Confidence-only batch fetch (no leisure/DLC detail pages)
# ──────────────────────────────────────────────────────────────


def refresh_confidence(
    games: list[tuple[int, str]],
) -> tuple[dict[int, float], dict[int, int], dict[int, int]]:
    """Re-search ``games`` (cached or not) and save hours, polls and count_comp.

    Nothing is dropped from the cache first: a failed lookup writes nothing,
    so the old entry survives. Prior hours beat a clean miss, since a prior
    leisure/DLC estimate is trusted over "not found". When HLTB is unavailable
    the cache is returned unchanged and nothing is saved.

    Returns:
        The (hours, polls, count_comp) caches after the refresh.
    """
    cache = load_hltb_cache()
    polls = load_hltb_polls_cache()
    count_comp = load_hltb_count_comp_cache()
    prior_hours = {aid: cache[aid] for aid, _ in games if aid in cache}
    try:
        fetch_hltb_confidence(games, cache=cache, polls=polls, count_comp=count_comp)
    except HLTBUnavailableError:
        # Already logged and tallied by the batch; the cache is untouched.
        return cache, polls, count_comp
    restore_prior_hours(cache, prior_hours)
    save_hltb_cache(cache, polls, _HLTBExtras(count_comp=count_comp))
    return cache, polls, count_comp


def refetch_poll_counts(missing: list[tuple[int, str]]) -> dict[int, int]:
    """Re-search ``missing`` for poll counts and return the refreshed polls cache."""
    return refresh_confidence(missing)[1]


def fetch_hltb_confidence_cached(
    games: list[tuple[int, str]],
    progress_cb: ProgressCb | None = None,
) -> dict[int, float]:
    """Fetch HLTB search-level confidence data, using disk cache for known IDs."""
    cache = load_hltb_cache()
    polls = load_hltb_polls_cache()
    count_comp = load_hltb_count_comp_cache()
    uncached = [(app_id, name) for app_id, name in games if app_id not in cache]

    if uncached:
        logger.info(
            "Fetching HLTB confidence for %d uncached games (%d cached)...",
            len(uncached),
            len(games) - len(uncached),
        )
        t0 = time.monotonic()
        try:
            fetch_hltb_confidence(
                uncached,
                cache=cache,
                polls=polls,
                progress_cb=reporting_progress_cb(
                    "Fetching HLTB poll counts", len(uncached), progress_cb
                ),
                count_comp=count_comp,
            )
        except HLTBUnavailableError:
            # Already logged and tallied by the batch; the cache is untouched.
            return cache
        elapsed = time.monotonic() - t0

        save_hltb_cache(cache, polls, _HLTBExtras(count_comp=count_comp))

        found = sum(1 for aid, _ in uncached if cache.get(aid, -1) > 0)
        rate = len(uncached) / elapsed if elapsed > 0 else 0
        logger.info(
            "HLTB confidence fetch done: %d/%d found in %.1fs (%.0f games/s)",
            found,
            len(uncached),
            elapsed,
            rate,
        )
    else:
        logger.info("All %d games found in HLTB cache.", len(games))

    return cache


def _log_detail_plan(n_rush: int, n_id: int) -> None:
    """Log what a detail fetch is about to do."""
    if n_rush and n_id:
        logger.info(
            "Fetching HLTB detail for %d games missing rush/leisure data"
            " + %d games missing game ID...",
            n_rush,
            n_id,
        )
    elif n_rush:
        logger.info(
            "Fetching HLTB detail for %d games missing rush/leisure data...", n_rush
        )
    else:
        logger.info("Backfilling HLTB game ID for %d game(s)...", n_id)


def fetch_hltb_detail_missing(
    games: list[tuple[int, str]],
    progress_cb: ProgressCb | None = None,
) -> int:
    """Fetch HLTB detail (rush + leisure) for games that are missing it.

    Also backfills ``hltb_game_id`` for any game that already has rush/leisure
    data but whose HLTB game ID was never stored (e.g. from an old cache).
    Games with both rush data and a game_id are skipped entirely.  For the
    rest, ``fetch_hltb_times`` re-searches them and visits their detail pages
    (it never skips cached games).  Prior hours win over a clean miss; a failed
    lookup writes nothing, so its old entry survives untouched.

    Args:
        games: list of (app_id, name) tuples to check.
        progress_cb: optional progress callback.

    Returns:
        Number of games that now have rush-hour data after the fetch.
    """
    rush = load_hltb_rush_cache()
    game_id_cache = load_hltb_game_id_cache()
    missing_rush = [
        (app_id, name) for app_id, name in games if rush.get(app_id, -1) <= 0
    ]
    # Also re-search games that have rush data but no HLTB game ID yet so the
    # direct URL can be shown in stats output.
    missing_id_only = [
        (app_id, name)
        for app_id, name in games
        if rush.get(app_id, -1) > 0 and game_id_cache.get(app_id, 0) == 0
    ]
    missing = missing_rush + missing_id_only
    if not missing:
        return 0

    cache = load_hltb_cache()
    polls = load_hltb_polls_cache()
    extras = _HLTBExtras(
        count_comp=load_hltb_count_comp_cache(),
        rush=rush,
        leisure_100h=load_hltb_leisure_100h_cache(),
        hltb_game_id=game_id_cache,
    )

    prior_hours = {aid: cache[aid] for aid, _ in missing if aid in cache}

    _log_detail_plan(len(missing_rush), len(missing_id_only))
    report = reporting_progress_cb("Fetching HLTB details", len(missing), progress_cb)
    try:
        elapsed = fetch_hltb_times_timed(missing, cache, polls, report, extras)
    except HLTBUnavailableError:
        # Already logged and tallied by the batch; the cache is untouched.
        return 0

    restore_prior_hours(cache, prior_hours)

    save_hltb_cache(cache, polls, extras)

    fetched = sum(1 for app_id, _ in missing_rush if extras.rush.get(app_id, -1) > 0)
    logger.info(
        "HLTB detail fetch done: %d/%d got rush data in %.1fs (%.0f games/s)",
        fetched,
        len(missing_rush),
        elapsed,
        games_per_second(len(missing), elapsed),
    )
    return fetched


def get_hltb_submit_url(game_name: str) -> str | None:
    """Look up a game on HLTB and return its submit page URL.

    Args:
        game_name: Name of the game to search for.

    Returns:
        URL like ``https://howlongtobeat.com/submit/game/12345``,
        or ``None`` if the game wasn't found.
    """
    try:
        results = fetch_hltb_times([(0, game_name)])
    except HLTBUnavailableError:
        # Already logged and tallied by the batch; the cache is untouched.
        return None
    if results and results[0].hltb_game_id:
        return f"{HLTB_BASE_URL}/submit/game/{results[0].hltb_game_id}"
    return None