Plugins

Lightweight plugin registry for domain-specific extensions.

class updatesupport.plugins.PluginMetadata(package=None, homepage=None, domain=None, tags=(), min_updatesupport_version=None)

Bases: object

Optional package metadata for plugin discovery and documentation.

Parameters:

• package (str | None)

• homepage (str | None)

• domain (str | None)

• tags (tuple[str, ...])

• min_updatesupport_version (str | None)

package: str | None = None

homepage: str | None = None

domain: str | None = None

tags: tuple[str, ...] = ()

min_updatesupport_version: str | None = None

as_dict()

Return JSON-friendly plugin metadata.

Return type:

dict[str, Any]

class updatesupport.plugins.UpdateSupportPlugin(name, version=None, description='', metrics=<factory>, q_presets=<factory>, report_profiles=<factory>, compilers=<factory>, metadata=<factory>)

Bases: object

Domain extension descriptor.

Plugins can expose metric factories, Q preset factories, report profiles, and compilers without adding domain-specific vocabulary to the core package. The values are intentionally generic callables so plugins can evolve their own public APIs while core provides discovery and namespacing.

Parameters:

• name (str)

• version (str | None)

• description (str)

• metrics (Mapping[str, Callable[[...], Any]])

• q_presets (Mapping[str, Callable[[...], Any]])

• report_profiles (Mapping[str, Callable[[...], Any]])

• compilers (Mapping[str, Callable[[...], Any]])

• metadata (PluginMetadata)

name: str

version: str | None = None

description: str = ''

metrics: Mapping[str, Callable[[...], Any]]

q_presets: Mapping[str, Callable[[...], Any]]

report_profiles: Mapping[str, Callable[[...], Any]]

compilers: Mapping[str, Callable[[...], Any]]

metadata: PluginMetadata

as_dict()

Return a JSON-friendly summary of the exposed plugin surfaces.

Return type:

dict[str, Any]

class updatesupport.plugins.PluginValidationIssue(severity, code, message, surface=None, key=None)

Bases: object

Validation issue for an updatesupport plugin descriptor.

Parameters:

• severity (str)

• code (str)

• message (str)

• surface (str | None)

• key (str | None)

severity: str

code: str

message: str

surface: str | None = None

key: str | None = None

as_dict()

Return a JSON-friendly issue payload.

Return type:

dict[str, str | None]

class updatesupport.plugins.PluginValidationReport(plugin_name, issues=())

Bases: object

Validation report for a plugin descriptor.

Parameters:

• plugin_name (str)

• issues (tuple[PluginValidationIssue, ...])

plugin_name: str

issues: tuple[PluginValidationIssue, ...] = ()

property errors: tuple[PluginValidationIssue, ...]

property warnings: tuple[PluginValidationIssue, ...]

property ok: bool

as_dict()

Return a JSON-friendly validation report.

Return type:

dict[str, Any]

raise_for_errors()

Raise ValueError if validation found blocking errors.

Return type:

None

class updatesupport.plugins.PluginRegistry

Bases: object

Mutable registry for explicit and entry-point-discovered plugins.

register(plugin, *, replace=False, validate=True)

Parameters:

• plugin (UpdateSupportPlugin)

• replace (bool)

• validate (bool)

Return type:

UpdateSupportPlugin

unregister(name)

Parameters:

name (str)

Return type:

None

get(name)

Parameters:

name (str)

Return type:

UpdateSupportPlugin

list()

Return type:

tuple[UpdateSupportPlugin, …]

discover(*, group='updatesupport.plugins', replace=False, validate=True)

Parameters:

• group (str)

• replace (bool)

• validate (bool)

Return type:

tuple[UpdateSupportPlugin, …]

updatesupport.plugins.register_plugin(plugin, *, replace=False, validate=True)

Register a plugin explicitly.

Parameters:

• plugin (UpdateSupportPlugin)

• replace (bool)

• validate (bool)

Return type:

UpdateSupportPlugin

updatesupport.plugins.unregister_plugin(name)

Remove a plugin from the process-local registry if present.

Parameters:

name (str)

Return type:

None

updatesupport.plugins.get_plugin(name)

Return a registered plugin by name.

Parameters:

name (str)

Return type:

UpdateSupportPlugin

updatesupport.plugins.list_plugins()

Return registered plugins sorted by name.

Return type:

tuple[UpdateSupportPlugin, …]

updatesupport.plugins.discover_plugins(*, group='updatesupport.plugins', replace=False, validate=True)

Discover plugins declared through Python package entry points.

Parameters:

• group (str)

• replace (bool)

• validate (bool)

Return type:

tuple[UpdateSupportPlugin, …]

updatesupport.plugins.validate_plugin(plugin)

Validate a plugin descriptor without mutating the registry.

Parameters:

plugin (UpdateSupportPlugin)

Return type:

PluginValidationReport

updatesupport.plugins.assert_valid_plugin(plugin)

Validate a plugin descriptor and raise on blocking errors.

Parameters:

plugin (UpdateSupportPlugin)

Return type:

PluginValidationReport

updatesupport.plugins.plugin_metric(plugin_name, metric_name)

Return a metric factory from a registered plugin.

Parameters:

• plugin_name (str)

• metric_name (str)

Return type:

Callable[[…], Any]

updatesupport.plugins.plugin_q_preset(plugin_name, preset_name)

Return a Q preset factory from a registered plugin.

Parameters:

• plugin_name (str)

• preset_name (str)

Return type:

Callable[[…], Any]

updatesupport.plugins.plugin_report_profile(plugin_name, profile_name)

Return a report-profile callable from a registered plugin.

Parameters:

• plugin_name (str)

• profile_name (str)

Return type:

Callable[[…], Any]

updatesupport.plugins.plugin_compiler(plugin_name, compiler_name)

Return a compiler callable from a registered plugin.

Parameters:

• plugin_name (str)

• compiler_name (str)

Return type:

Callable[[…], Any]