comicbox.online_estimate

source module comicbox.online_estimate

Estimate the API-request count and wall-clock for a batch online-tag run.

A batch caller (Codex) shows this to an operator before a “Tag Online” run and mirrors it in a live countdown. Keeping the model here — next to the search flow it describes and the rate limits it divides by — means the numbers move with comicbox’s behavior instead of drifting in a downstream copy.

The model is deliberately simple. Per comic, each source costs a characteristic number of API requests:

  • Metron is a fixed two-step search (series_list + issues_list) — one or two requests — that match mode does not change (see v4.0.5).
  • Comic Vine’s fuzzy volume→issue path does more verification the tighter the match mode, so its request count scales with mode.

Under first-match-wins a comic stops at the first source that answers, so the run is billed the costliest single selected source; merging all sources (first_wins=False) queries every source per comic, so their per-comic costs are summed.

Wall-clock is that request total over the slowest enabled source’s sustained throughput: Metron’s per-minute cap binds a bounded run directly, while Comic Vine’s hourly cap is the real ceiling for any run longer than a few minutes, so it is spread over the minute (see rate_limits). first-match- wins means a comic isn’t done until the binding source answers, so the slowest source sets the pace.

Classes

  • RunEstimate — The projected cost of a batch online-tag run.

Functions

  • requests_per_comic — Return the API requests one comic costs against source under mode.

  • estimate_run — Project the request count and wall-clock seconds for a batch online-tag run.

source class RunEstimate()

The projected cost of a batch online-tag run.

Attributes

  • requests : int — Total API requests the run is expected to make.

  • seconds : float — Projected wall-clock duration in seconds.

source requests_per_comic(source: str, mode: str) → int

Return the API requests one comic costs against source under mode.

source estimate_run(comics: int, mode: str, sources: Sequence[str], *, merge_all_sources: bool = False) → RunEstimate

Project the request count and wall-clock seconds for a batch online-tag run.

comics is how many comics remain to look up, mode a :class:~comicbox.config.settings.MatchMode value ("auto" etc.), and sources the enabled source names in priority order. merge_all_sources mirrors first_wins=False: every source is queried per comic and their per-comic costs summed, instead of stopping at the first match.