Plugins

To create a PieCrust plugin, you need to do a few things:

• Create a correct setuptools package.
• Implement a sub-class of PieCrustPlugin.
• Write a couple lines of boilerplate code.

Packaging plugins

PieCrust plugins are expected to be available on Pypi for better integration with chef commands. For instance, the chef plugins list -a will list all PieCrust plugins from Pypi.

A PieCrust plugin package must:

• Be named PieCrust-FooBar, where FooBar is 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 PieCrustPlugin. 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 situation.

Check the piecrust.plugins.builtin.BuiltInPlugin to see how all PieCrust functionality is implemented.

Boilerplate code

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 for a __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.