To create a PieCrust plugin, you need to do a few things:
- Create a correct
- Implement a sub-class of
- Write a couple lines of boilerplate code.
PieCrust plugins are expected to be available on Pypi for better integration
chef commands. For instance, the
chef plugins list -a will list all
PieCrust plugins from Pypi.
A PieCrust plugin package must:
- Be named
FooBaris the name of the plugin.
- Have a module named
piecrust_foobar, which is basically the lower-case version of the package name, with an underscore instead of a dash.
You can refer to the
setuptools documentation for more information.
The plugin class
A PieCrust plugin is an instance of a class that derives from
The only required thing you need to override is the name of the plugin:
from piecrust.plugins.base import PieCrustPlugin class FooBarPlugin(PieCrustPlugin): name = 'FooBar'
The plugin class has a whole bunch of functions returning whatever your plugin
may want to extend: formatters, template engines,
chef commands, sources, etc.
Each one of those returns an array of instances or classes, depending on the
piecrust.plugins.builtin.BuiltInPlugin to see how all PieCrust
functionality is implemented.
Now we have a plugin class, and a Pypi package that PieCrust can find if needed. All we need is a way to tell PieCrust how to find your plugin class in that package.
In the required
piecrust_foobar module, you need to define a
__piecrust_plugin__ global variable that points to your plugin class:
__piecrust_plugin__ = FooBarPlugin
That’s what PieCrust will use to instantiate your plugin.
Loading the plugin
Now you can add your plugin to a PieCrust website by adding this to the website configuration:
site: plugins: foobar
PieCrust will prepend
piecrust_ to each specified plugin name and attempt to
load that as a module (
import piecrust_foobar). If this succeeds, it will look
__piecrust_plugin__ in that module, and expect its value to be a class
that inherits from
PieCrustPlugin. If everything’s OK, it will instantiate
that class and query it for various services and components when necessary.