archivebox.plugins.discovery

Module Contents

Classes

ConfigLookup
PluginSpecialConfig

Functions

iter_plugin_dirs	Return the exact plugin directories exposed by the shared catalog.
get_plugin_catalog
get_plugin_config_resolver
get_plugins	Get list of available plugins by discovering plugin directories.
get_plugin_name	Get the base plugin name without numeric prefix.
get_archive_result_aliases
get_archive_result_names	Return the canonical ArchiveResult name and its declared historic aliases.
plugin_card_is_interactive
get_plugin_output_extension_preference
get_plugin_default_output_path
get_snapshot_thumbnail_card_order	Return plugin-owned ArchiveResult names eligible for snapshot thumbnails.
get_snapshot_role_names	Return ArchiveResult names for a plugin-owned snapshot presentation role.
get_snapshot_role_result	Select the first successful result declared for a presentation role.
get_plugin_presentation_modules	Load optional plugin-owned presentation hooks declared in manifests.
get_plugin_presentation_module	Load one plugin’s optional presentation hooks module.
plugin_has_custom_full_response	Return whether a plugin renders its full template through a response hook.
get_extra_snapshot_output_cards	Collect additional cards from plugin-owned presentation hooks.
serve_plugin_replay_asset	Give plugin presentation hooks the first chance to serve replay assets.
render_plugin_full_response	Let plugin presentation hooks render a saved output’s full template.
get_enabled_plugins	Get the list of enabled plugins based on config and available hooks.
get_search_backends	Return plugins that declare both standalone search commands.
discover_plugin_configs	Discover all plugin config.json schemas.
get_plugin_special_config	Extract special config keys for a plugin following naming conventions.
get_plugin_template	Get a plugin template by plugin name and template type.
get_plugin_icon	Get the icon for a plugin from its icon.html template.

Data

BUILTIN_PLUGINS_DIR
USER_PLUGINS_DIR
DEFAULT_TEMPLATES

API

class archivebox.plugins.discovery.ConfigLookup

Bases: typing.Protocol

get(key: str, default: Any = None) → Any

items() → collections.abc.Iterable[tuple[str, Any]]

class archivebox.plugins.discovery.PluginSpecialConfig

Bases: typing.TypedDict

enabled: bool

None

timeout: int

None

binary: str

None

archivebox.plugins.discovery.BUILTIN_PLUGINS_DIR

‘resolve(…)’

archivebox.plugins.discovery.USER_PLUGINS_DIR

None

archivebox.plugins.discovery.iter_plugin_dirs() → list[pathlib.Path]

Return the exact plugin directories exposed by the shared catalog.

archivebox.plugins.discovery.get_plugin_catalog() → abx_dl.catalog.PluginCatalog

archivebox.plugins.discovery.get_plugin_config_resolver() → abx_dl.catalog.PluginConfigResolver

archivebox.plugins.discovery.get_plugins() → list[str]

Get list of available plugins by discovering plugin directories.

Returns plugin directory names for any plugin that exposes hooks, config.json, or a standardized templates/icon.html asset. This includes non-extractor plugins such as binary providers and shared base plugins.

archivebox.plugins.discovery.get_plugin_name(plugin: str) → str

Get the base plugin name without numeric prefix.

Examples: ‘10_title’ -> ‘title’ ‘26_readability’ -> ‘readability’ ‘50_parse_html_urls’ -> ‘parse_html_urls’

archivebox.plugins.discovery.get_archive_result_aliases() → dict[str, str]

archivebox.plugins.discovery.get_archive_result_names(plugin_name: str) → tuple[str, ...]

Return the canonical ArchiveResult name and its declared historic aliases.

archivebox.plugins.discovery.plugin_card_is_interactive(plugin_name: str) → bool

archivebox.plugins.discovery.get_plugin_output_extension_preference(plugin_name: str) → tuple[tuple[str, ...], ...] | None

archivebox.plugins.discovery.get_plugin_default_output_path(plugin_name: str) → str | None

archivebox.plugins.discovery.get_snapshot_thumbnail_card_order() → dict[str, int]

Return plugin-owned ArchiveResult names eligible for snapshot thumbnails.

archivebox.plugins.discovery.get_snapshot_role_names(role: str) → tuple[str, ...]

Return ArchiveResult names for a plugin-owned snapshot presentation role.

archivebox.plugins.discovery.get_snapshot_role_result(results, role: str)

Select the first successful result declared for a presentation role.

archivebox.plugins.discovery.get_plugin_presentation_modules() → tuple[types.ModuleType, ...]

Load optional plugin-owned presentation hooks declared in manifests.

archivebox.plugins.discovery.get_plugin_presentation_module(plugin_name: str) → types.ModuleType | None

Load one plugin’s optional presentation hooks module.

archivebox.plugins.discovery.plugin_has_custom_full_response(plugin_name: str) → bool

Return whether a plugin renders its full template through a response hook.

archivebox.plugins.discovery.get_extra_snapshot_output_cards(outputs: list[dict[str, Any]]) → list[dict[str, Any]]

Collect additional cards from plugin-owned presentation hooks.

archivebox.plugins.discovery.serve_plugin_replay_asset(path: str, config, response_class)

Give plugin presentation hooks the first chance to serve replay assets.

archivebox.plugins.discovery.render_plugin_full_response(path: str, output_url: str, **kwargs)

Let plugin presentation hooks render a saved output’s full template.

archivebox.plugins.discovery.get_enabled_plugins(config: archivebox.plugins.discovery.ConfigLookup | None = None, **config_kwargs: Any) → list[str]

Get the list of enabled plugins based on config and available hooks.

Filters plugins by USE_/SAVE_ flags. Only returns plugins that are enabled.

archivebox.plugins.discovery.get_search_backends()

Return plugins that declare both standalone search commands.

archivebox.plugins.discovery.discover_plugin_configs() → dict[str, dict[str, Any]]

Discover all plugin config.json schemas.

Each plugin can define a config.json file with JSONSchema defining its configuration options. This is intentionally cached because these schemas are plugin package metadata, not live user config; runtime values still come from env/db config at each callsite.

archivebox.plugins.discovery.get_plugin_special_config(plugin_name: str, config: archivebox.plugins.discovery.ConfigLookup, _visited: set[str] | None = None) → archivebox.plugins.discovery.PluginSpecialConfig

Extract special config keys for a plugin following naming conventions.

ArchiveBox recognizes 3 special config key patterns per plugin: - {PLUGIN}_ENABLED: Enable/disable toggle (default True) - {PLUGIN}_TIMEOUT: Plugin-specific timeout (fallback to TIMEOUT, default 300) - {PLUGIN}_BINARY: Primary binary path (default to plugin_name)

archivebox.plugins.discovery.DEFAULT_TEMPLATES

None

archivebox.plugins.discovery.get_plugin_template(plugin: str, template_name: str, fallback: bool = True) → str | None

Get a plugin template by plugin name and template type.

Args: plugin: Plugin name (e.g., ‘screenshot’, ‘15_singlefile’) template_name: A template slot such as ‘icon’, ‘card’, or ‘full’. fallback: If True, return default template if plugin template not found

archivebox.plugins.discovery.get_plugin_icon(plugin: str) → str

Get the icon for a plugin from its icon.html template.