Disclaimer: This documentation is provided for convenience and may contain errors. Always verify information against the official Kodi and provider documentation. Report issues.
Fastmail
Home / Files / catalog_check.py

resources/lib/catalog_check.py — stale-title tracker

Path /resources/lib/catalog_check.py Lines 51 Type stateful helper (small) ← imported by default.py (in _resolve_vod 404 handler) → calls Kodi profile dir IO; one threading.Lock

Role

Tracks which show titles have been marked stale because their episodes went away — written by default.py:_resolve_vod when Kodi tries to play an episode whose provider-side URL returns 404 (the show was removed from the provider's catalogue), so future attempts suppress the retry rather than re-firing the same 404.

The stale set is a playback safety net, not a sync primitive. The sync engine itself doesn't consult this module; it just refreshes the Kodi DB directly. The stale list is what the playback 404 handler writes into and what future resolve_vod calls can read from to short-circuit before another network round-trip.

Storage

STALE_FILE = /stale_titles.json · line 10

One JSON file on disk containing a single JSON array of strings (the stale titles), kept sorted (line 29) so diffs across runs are stable in git. Stored in the addon profile dir alongside library_sync_state.json and provider_map.json.

_lock · _stale_titles · lines 12, 13

Module-level threading.Lock protects the in-memory set. Module is imported by both the service and the plugin in separate interpreter threads, so the in-memory copy may differ between processes — but the on-disk copy is the shared truth and is reloaded on every import.

Functions

_load_stale() · line 16

Reads STALE_FILE into the module-level set. Called once at import time (line 34) — so importing catalog_check is what triggers the load, no explicit init call needed.

_save_stale() · line 26

Writes sorted(_stale_titles) back to disk. Sorted so git diffs don't churn. Silent on failure (best-effort persistence).

mark_stale(title) · line 37

Adds title to the set under the lock, calls _save_stale(), logs at DEBUG level so normal kodi.log noise is minimal. Called by default.py:_resolve_vod when an episode's HTTP fetch returns 404 (the underlying provider stream no longer exists or the show was withdrawn).

is_stale(title) -> bool · line 44

Membership test under the lock. Used by the playback resolver to decide whether to skip the HTTP fetch and immediately surface a "no longer available" notification instead.

get_stale_titles() -> set · line 49

Returns a copy of the set. Used by the troubleshooting page action to show the user what's been marked stale.

No expiry / no clear

There is no automatic expiry of stale entries and no public clear() function. Stale titles persist across restarts until the on-disk file is deleted. Practically this is fine — a stale title means the provider genuinely had no episodes; if the show later acquires a new season, the entry stays stale but the listing refreshes anyway via the library_sync path, so the UI updates automatically. The stale set is a hint, not an authority.