This example will cover creating an extension with a single command, found in a new section at the root of the CLI. The full command will be:
$ pulp-admin example demo --name Jay --show-date
The first step is to create the method the framework will invoke when loading the extension. This method should create the necessary objects to populate the CLI with the extension’s additions.
For this demo, the context is held in a global variable so it can be accessed when the command is run.
CONTEXT = None def initialize(context): global CONTEXT CONTEXT = context
There are two ways to add a new section to either the root of the CLI directly
or to another section. One approach is to manually instantiate the
pulp.client.extensions.extensions.PulpCliSection class, optionally
subclassing it to add any needed enhancements. The instantiated object is then
added to the CLI using the
add_section call or to a parent section with
The other approach is to use the
create_section helper method found in
the CLI instance itself or the
create_subsection call in
PulpCliSection instances. The demo will use the latter approach.
create_section call takes the name of the section (i.e. the text that
will be used on the command line directly) and a description for help text
PulpCliSection instance is returned from the call so it can
be further manipulated. The CLI instance is retrieved from the client context.
ex_section = context.cli.create_section('example', 'Example section')
At this point, if this extension was installed, the new section would appear in the usage. Installation is covered later in this document.
$ pulp-admin Usage: pulp-admin [SUB_SECTION, ..] COMMAND Available Sections: auth - manage users, roles and permissions bindings - search consumer bindings event - subscribe to event notifications example - Example section orphan - find and remove orphaned content units puppet - manage Puppet-related content and features repo - list repositories and manage repo groups rpm - manage RPM-related content and features server - display info about the server tasks - list and cancel server-side tasks
Commands associate the user request with the method that will handle it. Commands are added to
sections using a similar approach as with sections. The command can be manually
instantiated from the
class and added to a section with the
Alternatively, a helper method named
create_command can be used to do both
the instantiation and add it to a section. This call accepts three parameters.
The first is the name of the command which is used to invoke it from the command
line. The second is the description, displayed when viewing the usage of the
command. The third is a reference to the method to run when the command is
The following snippet creates our demo command and ties it to the
demo_command = ex_section.create_command('demo', 'Demo command', run_demo)
run_demo must be defined as a method, otherwise the extension
will fail to load. We’ll expand on this in the next section, but a simple
implementation is as follows.
def run_demo(**kwargs): CONTEXT.prompt.write('Hello World')
Options and Flags¶
While some commands can simply be executed as is, many will need to accept
user input. These are referred to as options and flags. Both can be created
by running the appropriate
create_* method on the command instance.
For the demo, we’ll add an option that accepts the user’s name and a flag that toggles whether or not the date is printed.
demo_command.create_option('--name', 'Name of the user', required=True) demo_command.create_flag('--show-date', 'If specified, the date will be displayed')
The above snippet configures the
--name option as required. The client
framework will enforce that, displaying the usage text to the user in the event it
is not specified.
$ pulp-admin example demo Command: demo Description: Demo command Available Arguments: --name - (required) Name of the user --show-date - If specified, the date will be displayed The following options are required but were not specified: --name
The client framework will capture the input and make it available to the command’s
execution method in its
kwargs argument. The name of the option/flag is used
as the key and the user input is the value (or
True in the case of a flag).
Below is the
run_demo method from above, enhanced to take advantage of our
newly added options and flags.
def run_demo(**kwargs): CONTEXT.prompt.write('Hello %s' % kwargs['name']) if kwargs['show-date']: CONTEXT.prompt.write(datetime.datetime.now())
$ pulp-admin example demo --name Jay Hello Jay $ pulp-admin example demo --name Jay --show-date Hello Jay 2013-02-07 14:54:14.587727
Instructions on packaging and installing extensions for production deployment can be found at Entry Points.
For simplicity, this demo will install the extension using the directory approach. More information can be found in the Directory Loading section of this guide.
Create an empty file in that directory named
Copy the file containing this demo code to that directory, naming it
pulp-admin script is run, the usage text will show the
example section created from this demo.
import datetime CONTEXT = None def initialize(context): global CONTEXT CONTEXT = context ex_section = context.cli.create_section('example', 'Example section') demo_command = ex_section.create_command('demo', 'Demo command', run_demo) demo_command.create_option('--name', 'Name of the user', required=True) demo_command.create_flag('--show-date', 'If specified, the date will be displayed') def run_demo(**kwargs): CONTEXT.prompt.write('Hello %s' % kwargs['name']) if kwargs['show-date']: CONTEXT.prompt.write(datetime.datetime.now())