Mercurial > piecrust2

annotate docs/api/02_components/01_commands.md @ 550:6f216c1ab6b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bake: Add a flag to know which record entries got collapsed from last run. This makes it possible to find entries for things that were actually baked during the current run, as opposed to skipped because they were "clean".
author Ludovic Chabant <ludovic@chabant.com>
date Tue, 04 Aug 2015 21:22:30 -0700
parents dce482f7c62d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
504
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1 ---
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 title: Chef Commands
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 ---
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
4
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5 To provide new `chef` commands, you need to override the `getCommands` method of
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
6 your plugin, and return command instances:
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8
513
dce482f7c62d docs: Use fenced code block syntax.
Ludovic Chabant <ludovic@chabant.com>
parents: 504
diff changeset
9 ```python
504
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10 class MyPlugin(PieCrustPlugin):
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
11 name = 'myplugin'
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
12
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13 def getCommands(self):
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
14 return [
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
15 MyNewCommand()]
513
dce482f7c62d docs: Use fenced code block syntax.
Ludovic Chabant <ludovic@chabant.com>
parents: 504
diff changeset
16 ```
504
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
17
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
18
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
19 To create a command class, inherit from the `ChefCommand` base class:
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
20
513
dce482f7c62d docs: Use fenced code block syntax.
Ludovic Chabant <ludovic@chabant.com>
parents: 504
diff changeset
21 ```python
504
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
22 from piecrust.commands.base import ChefCommand
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
23
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
24 class MyNewCommand(ChefCommand):
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
25 def __init__(self):
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26 super(MyNewCommand, self).__init__()
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
27 self.name = 'foobar'
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
28 self.description = "Does some foobar thing."
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
29
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
30 def setupParser(self, parser, app):
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
31 parser.add_argument('thing')
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
32
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33 def run(self, ctx):
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
34 print("Doing %s" % ctx.args.thing)
513
dce482f7c62d docs: Use fenced code block syntax.
Ludovic Chabant <ludovic@chabant.com>
parents: 504
diff changeset
35 ```
504
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
36
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
37
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
38 * The `name` will be used for command line invocation, _i.e._ your new command
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
39 will be invoked with `chef foobar`.
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
40 * The `description` will be used for help pages like `chef --help`.
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
41 * The `setupParser` method passes an `argparse.ArgumentParser` and a `PieCrust`
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
42 application. You're supposed to setup the syntax for your commend there.
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
43 * The `run` method is called when your command is executed. The `ctx` object
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
44 contains a couple useful things, among others:
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
45 * `args` is the namespace obtained from running `parse_args`. It has all the
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
46 values of the arguments for your command.
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
47 * `app` is the instance of the current `PieCrust` application.
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
48 * For the other things, check-out `piecrust.commands.base.CommandContext`.
20fcadaaf871 docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
49