Files
changedetection.io/changedetectionio/plugin_api.py
T
dgtlmoonandClaude Opus 5.5 e01f965353 Plugin hooks for changing the request and per-watch plugin settings (#4712)
Three new hooks (plugin API 0.7.0), so features like OAuth 2.0 client
credentials (#375), HMAC signing or rotating API keys can live in plugins
instead of core:

- fetch_request_alter: change headers, method and body just before the
  fetch; gets the check's proxy URL. Exceptions fail the check rather than
  sending the request without what the plugin meant to add.
- ui_edit_request_settings: a plugin's WTForms form nested into the edit
  page's Request tab under "Show advanced options", validated with the
  page, saved to {watch data dir}/{plugin_id}.json, never the watch itself.
- watch_settings_files: files "Clear history" keeps, beside the
  processors' {processor}.json.

plugin_api exports load_watch_plugin_settings / save_watch_plugin_settings.
Adds the request/api_key_header example plugin, which uses all three.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 14:22:08 +01:00

128 lines
5.8 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.7.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
# load_watch_plugin_settings - (watch, plugin_id) -> the dict saved from your ui_edit_request_settings form
# save_watch_plugin_settings - (watch, plugin_id, dict), e.g. to keep state for one watch (written atomically)
# 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, load_watch_plugin_settings, save_watch_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',
'load_watch_plugin_settings': 'changedetectionio.pluggy_interface',
'save_watch_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',
'load_watch_plugin_settings',
'save_watch_plugin_settings',
'time_between_check_to_seconds',
]