Plugin Author Guide#

Plugins are the extensibility seam of ExLab-Wizard. They transform files inside a freshly rendered run directory; the core application does not know about spreadsheet formats, document templates, or lab-specific naming rules. This guide is the authoring contract for plugin developers and mirrors design spec section 06 (Plugin System).

What plugins do#

A plugin is a Python package directory under the configured plugin root. Each plugin defines a single class that subclasses exlab_wizard.plugins.Plugin. The class is the unit of registration, lifecycle, and isolation: one class instance is constructed per creation session, inside a worker subprocess. The worker has the rendered destination directory as its working directory and runs in a sanitised environment with resource limits. Plugins write only to files inside the rendered destination tree; they may not touch README.md, the .exlab-wizard/ cache, or .exlab-answers.yml.

Where plugins fit in the pipeline#

Plugins execute in the controller’s PLUGIN_PASS state, immediately after Copier rendering completes and strictly before ReadmeGenerator writes the README:

Creation Controller
        |
        v
Copier (in-process, unsafe=False, no _tasks)
        |
        v
Plugin Host (resolves candidates, validates variables, dispatches workers)
        |
        v
Plugin Worker (one subprocess per plugin per session)
        |
        v
ReadmeGenerator + CacheWriter (post-plugin, non-pluggable)

Topics

Where to look in the codebase#

  • exlab_wizard/plugins/base.py – the Plugin abstract base class, the FileChange dataclass, and the PluginError / PluginInputRequired exception hierarchy.

  • exlab_wizard/plugins/host.py – the host that scans the registry, spawns workers, marshals IPC, and applies isolation limits.

  • exlab_wizard/plugins/_worker.py – the worker entry point that imports the plugin package, runs the lifecycle, and writes the result envelope back over stdout.

  • exlab_wizard/plugins/registry.py – the registry built at app startup from manifest.yml files.

  • exlab_wizard/plugins/logger.py – the structured-log shim that forwards plugin log records over stderr.