Plugin lifecycle

Plugin[ConfigT] binds a typed PluginConfig to a PluginContext. See api for generated signatures, attributes, defaults, and return types. The implementation at this documentation baseline defines the lifecycle below.

Construction and execution¶

Plugin.from_context(ctx) accepts a PluginContext[ConfigT] and returns a plugin bound to it. Plugin.run(*, ctx=None) optionally replaces that context and returns the final PluginContext[ConfigT]. It calls only hooks implemented by the plugin, in this order:

Hook	Context field updated by an Ok result
on_validate	None
on_prepare	None
on_upgrade	system
on_build	system
on_transform	system
on_translate	target_system
on_export	None
on_cleanup	None

Hooks take no explicit context argument; use self.config, self.system, and the bound context as appropriate. Return Ok(value) for success or Err(error) for a hook failure. The first Err raises PluginError and stops execution, so cleanup is not a guaranteed failure handler. Arbitrary exceptions raised inside hooks propagate as well. See getting started for an executable class-plugin example.

Function transforms¶

A function transform accepts a System and a typed configuration, returning Result[System, str]. @expose_plugin publishes configuration metadata for discovery. A function transform is registered in the r2x.transforms entry-point group.

The CLI owns installed-package discovery and execution; core owns the lifecycle and metadata contracts.

For the procedure and checked examples, use create function plugins.