Table of Contents
Watchlist and scheduler
Requires framework 0.9.0+, Queue, and any chosen optional providers. The watchlist capability is implemented by Watchlist(Service). Configure its Queue, Search, Thumbnail, Media handoff, and Notification selectors in Config → Plugins. Optional services can be None, so the plugin also works as a general manual watchlist. Install/enable providers before consumers. See suite setup.
The page at /plugins/watchlist/ lists category-filtered tiles, cached posters, available/expected episode progress and refresh errors. Add manual entries or use Anime Search's Add to watchlist action. Categories are plan-to-watch, watching, on-hold, finished, dropped. Each item can edit title, external ID, media type, relative media folder, season and expected episode count. Refresh, thumbnail and handoff actions queue work; removing an item deletes its control record and preserves media.
Methods
| Method | Behavior |
|---|---|
__init__(app=None) |
Initializes watchlist_entries in control SQLite with JSON data and a durable next-due timestamp. |
items() |
Reads newest entries first, including due, title, category, metadata, paths and recent error/status fields. Checks activation. |
get(item_id) |
Returns the matching item or None. |
add(title, external_id='', category='plan-to-watch', media_path='', expected=0, season=1, media_type='tv') |
Validates title/category/type/count/season and a relative media path, creates a random ID, stores the entry and returns its ID. Manual entries may omit external ID and media path. |
edit(item_id, ...) |
Validates the same editable fields and updates an existing item without losing refresh/handoff metadata. |
update(item_id, **changes) |
Internal/ trusted-plugin metadata update within a SQLite transaction; checks existence and category, records updated time. Use edit for user-submitted fields. |
delete(item_id) |
Deletes the control entry only. |
refresh(item_id, progress) |
Calls selected search info/episodes, records available and expected counts, requests a thumbnail through its selected provider, and sends watchlist.episodes when new availability increases. Progress is published to Queue. |
handoff(item_id) |
Calls selected handoff provider's submit(item) and saves the returned job ID. Requires a selected handoff implementation; that implementation verifies finished/completion conditions. |
process(payload, progress) |
Executes a queued refresh for payload.item_id; saves a bounded error if refresh fails. |
run_due() |
Scheduler iteration: when enabled, atomically advances one eligible watching item's due time and queues its refresh. Optional auto-handoff submits finished items with media paths and no previous handoff job. Returns the next polling interval. |
validate_settings(values) |
Rejects refresh intervals outside 60–604800 seconds before saving settings. |
workers.jobs processes one queued refresh with the common renewable-lease worker; workers.scheduler calls run_due. The scheduler defaults off. It does not rely on browser requests and survives app restarts through stored due timestamps. It does not download video or equate provider availability with downloaded completion. If a handoff job fails, use Queue's retry action or submit another explicit handoff.
Routes and permissions
GET / renders the list; GET /api/items returns metadata JSON. POST / dispatches add/edit/category/delete/refresh/thumbnail/handoff, requires content.write and CSRF, audits watchlist., flashes a result and redirects. Viewers can read but cannot mutate. Disabled routes return 404. index(), api_items(), mutate() and service() provide these request adapters; actual feature logic stays in the replaceable service.