Mercurial > piecrust2

annotate docs/api/01_plugins.md @ 1188:a7c43131d871

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bake: Fix file write flushing problem with Python 3.8+ Writing the cache files fails in Python 3.8 because it looks like flushing behaviour has changed. We need to explicitly flush. And even then, in very rare occurrences, it looks like it can still run into racing conditions, so we do a very hacky and ugly "retry" loop when fetching cached data :(
author Ludovic Chabant <ludovic@chabant.com>
date Tue, 15 Jun 2021 22:36:23 -0700
parents 61d53d2163d6
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
503
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1 ---
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 title: Plugins
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 ---
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
4
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5 To create a PieCrust plugin, you need to do a few things:
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
6
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7 * Create a correct `setuptools` package.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8 * Implement a sub-class of `PieCrustPlugin`.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
9 * Write a couple lines of boilerplate code.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
11
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
12 ## Packaging plugins
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
14 PieCrust plugins are expected to be available on [Pypi][] for better integration
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
15 with `chef` commands. For instance, the `chef plugins list -a` will list all
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
16 PieCrust plugins from Pypi.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
17
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
18 A PieCrust plugin package must:
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
19
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
20 * Be named `PieCrust-FooBar`, where `FooBar` is the name of the plugin.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
21 * Have a module named `piecrust_foobar`, which is basically the lower-case
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
22 version of the package name, with an underscore instead of a dash.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
23
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
24 You can refer to the [`setuptools` documentation][st] for more information.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
25
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
27 ## The plugin class
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
28
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
29 A PieCrust plugin is an instance of a class that derives from `PieCrustPlugin`.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
30 The only required thing you need to override is the name of the plugin:
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
31
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
32 from piecrust.plugins.base import PieCrustPlugin
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
34 class FooBarPlugin(PieCrustPlugin):
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
35 name = 'FooBar'
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
36
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
37 The plugin class has a whole bunch of functions returning whatever your plugin
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
38 may want to extend: formatters, template engines, `chef` commands, sources, etc.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
39 Each one of those returns an array of instances or classes, depending on the
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
40 situation.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
41
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
42 Check the `piecrust.plugins.builtin.BuiltInPlugin` to see how all PieCrust
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
43 functionality is implemented.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
44
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
45
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
46 ## Boilerplate code
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
47
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
48 Now we have a plugin class, and a Pypi package that PieCrust can find if needed.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
49 All we need is a way to tell PieCrust how to find your plugin class in that
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
50 package.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
51
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
52 In the required `piecrust_foobar` module, you need to define a
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
53 `__piecrust_plugin__` global variable that points to your plugin class:
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
54
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
55 __piecrust_plugin__ = FooBarPlugin
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
56
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
57 That's what PieCrust will use to instantiate your plugin.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
58
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
59
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
60 ## Loading the plugin
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
61
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
62 Now you can add your plugin to a PieCrust website by adding this to the website
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
63 configuration:
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
64
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
65 site:
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
66 plugins: foobar
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
67
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
68 PieCrust will prepend `piecrust_` to each specified plugin name and attempt to
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
69 load that as a module (`import piecrust_foobar`). If this succeeds, it will look
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
70 for a `__piecrust_plugin__` in that module, and expect its value to be a class
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
71 that inherits from `PieCrustPlugin`. If everything's OK, it will instantiate
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
72 that class and query it for various services and components when necessary.
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
73
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
74
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
75 [pypi]: https://pypi.python.org/pypi
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
76 [st]: http://pythonhosted.org/setuptools/
61d53d2163d6 docs: Start a proper "code/API" section.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
77