Files
changedetection.io/changedetectionio/plugin_api.py
T
dgtlmoonandClaude Opus 5.5 712b3e2772 Plugins - select_fetch_backend and recheck_seconds_override hooks, with a fallback fetcher example plugin (#4652)
* Plugins - select_fetch_backend and recheck_seconds_override hooks, with a fallback fetcher example plugin

select_fetch_backend lets a plugin pick another fetcher for one check: before it, or as a single
immediate retry after the fetch failed (e.g. the site answered 403). The watch's settings are never
changed. recheck_seconds_override gives a plugin the last word on the recheck time, after system,
group and watch, used by the scheduler and the overdue count.

The fallback fetcher example registers a fetcher for a generic scraping API, retries blocked checks
through it, then keeps the watch under its control for a while with a minimum recheck time and a
note in the watch list. Plugin API 0.6.0, which also exports Non200ErrorCodeReceived.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Plugins - chain fallback fetchers by priority, plus a daily limit, stats page and recheck widget in the example

select_fetch_backend now collects every plugin's offer (a name, or {'backend', 'priority'}) and core
tries them lowest priority first, skipping fetchers already tried in this check (new 'tried' argument),
up to FETCH_FALLBACK_MAX_ATTEMPTS retries (default 3). The last error is shown when they all fail.

The fallback fetcher example:
- a Priority setting, and it doesn't offer itself when over its daily limit, so the next one goes
- 'Most successful calls in 24 hours', counted in its own {datastore}/<plugin>-state.json
- takes a watch over only once a fallback fetch through it worked
- the minimum recheck time uses core's TimeBetweenCheckForm widget, fixed read-only by
  EXAMPLE_FETCHER_HELLOWORLD_TIME_BETWEEN_RECHECK_MINIMUM_SECONDS when set
- a 'Fetch stats' page with a sidebar icon

Core: plugin_api exports TimeBetweenCheckForm and time_between_check_to_seconds (now also used by
Watch.threshold_seconds), and plugin settings tabs show each field's description.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 13:36:49 +01:00

122 lines
5.3 KiB
Python

"""The public API for changedetection.io plugins.
Plugins should import only from this module. Everything else in the changedetectionio package
is internal and may change between releases without notice; names exported here follow the
deprecation policy in PLUGIN_ROADMAP.md (deprecated names keep working, with a logged warning,
for at least two minor releases).
from changedetectionio.plugin_api import hookimpl
@hookimpl
def ui_edit_stats_extras(watch):
return "<p>Hello from my plugin</p>"
Register the module under the "changedetectionio" entry-point group in your package's
pyproject.toml so it's discovered at startup:
[project.entry-points.changedetectionio]
my_plugin = "my_package.plugin"
The available hooks and their arguments are documented on ChangeDetectionSpec in
changedetectionio/pluggy_interface.py.
Keep plugin modules cheap to import: they're loaded at startup in every instance, so import
heavy dependencies inside your hook functions instead of at the top of the module.
A plugin that raises is logged and counted, and the hook carries on with the other plugins,
so one broken plugin can't stop checks from running.
"""
import inspect
from typing import TYPE_CHECKING
import pluggy
# Defined here, not imported from pluggy_interface: that module loads the built-in plugins at import
# time, and they import hookimpl from here, so importing plugin_api first would be a circular import.
# pluggy_interface imports it from here instead. Must stay the same namespace as PLUGIN_NAMESPACE there.
hookimpl = pluggy.HookimplMarker("changedetectionio")
# Version of this public API, not of changedetection.io. Below 1.0 it can still change between
# minor versions; from 1.0 on, breaking changes mean a major version bump.
PLUGIN_API_VERSION = "0.6.0"
async def await_me_maybe(value):
"""Return `value`, awaiting it first if it's awaitable.
Hook implementations may be plain functions or `async def` coroutines, so core code that
calls an async-capable hook passes each result through this helper.
"""
if inspect.isawaitable(value):
return await value
return value
async def gather_hook_results(results):
"""Await every awaitable in a list of hook results, in order, and drop the None results."""
resolved = []
for result in results or []:
result = await await_me_maybe(result)
if result is not None:
resolved.append(result)
return resolved
# Exported lazily (see __getattr__ below) so importing plugin_api stays cheap: these pull in the
# fetchers, lxml etc, and pluggy_interface imports would otherwise go circular.
# difference_detection_processor - base class of a processor plugin's perform_site_check
# get_resolved_processor_config - (config, source) for a watch's processor, tag override wins
# html_to_text - HTML to plain text, the same conversion the built-in processors use
# Fetcher - base class of a register_content_fetcher fetcher
# load_plugin_settings - (datastore_path, plugin_id) -> the dict saved from your plugin_settings_tab
# Non200ErrorCodeReceived - what a fetcher raises when the site answers with an error status (.status_code)
# TimeBetweenCheckForm - the weeks/days/hours/minutes/seconds recheck time widget, for FormField() in a
# plugin_settings_tab form (render_kw={'class': 'time-check-widget'} styles it)
# time_between_check_to_seconds - that widget's saved dict as seconds
if TYPE_CHECKING:
# Never runs, only tells linters/IDEs/type checkers what the lazy exports below are
from changedetectionio.content_fetchers.base import Fetcher
from changedetectionio.content_fetchers.exceptions import Non200ErrorCodeReceived
from changedetectionio.forms import TimeBetweenCheckForm
from changedetectionio.model.Watch import time_between_check_to_seconds
from changedetectionio.html_tools import html_to_text
from changedetectionio.pluggy_interface import load_plugin_settings
from changedetectionio.processors import get_resolved_processor_config
from changedetectionio.processors.base import difference_detection_processor
_LAZY_EXPORTS = {
'Fetcher': 'changedetectionio.content_fetchers.base',
'load_plugin_settings': 'changedetectionio.pluggy_interface',
'Non200ErrorCodeReceived': 'changedetectionio.content_fetchers.exceptions',
'TimeBetweenCheckForm': 'changedetectionio.forms',
'time_between_check_to_seconds': 'changedetectionio.model.Watch',
'difference_detection_processor': 'changedetectionio.processors.base',
'get_resolved_processor_config': 'changedetectionio.processors',
'html_to_text': 'changedetectionio.html_tools',
}
def __getattr__(name):
if name in _LAZY_EXPORTS:
import importlib
value = getattr(importlib.import_module(_LAZY_EXPORTS[name]), name)
globals()[name] = value
return value
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
__all__ = [
'Fetcher',
'Non200ErrorCodeReceived',
'PLUGIN_API_VERSION',
'TimeBetweenCheckForm',
'await_me_maybe',
'difference_detection_processor',
'gather_hook_results',
'get_resolved_processor_config',
'hookimpl',
'html_to_text',
'load_plugin_settings',
'time_between_check_to_seconds',
]