Rosendale CLIBasic Plugin

The CLIBasic Plugin for Cement provides a number of simple features that most cli applications might utilize. The following features are included:

• get-config command displays namespace config dictionaries
• list-plugins command displays all enabled plugins
• list-hooks command (hidden) helpful for development
• list-hidden-commands command (hidden) shows all hidden commands
• -L global option toggles log level [debug, info, warn, error, fatal]

The clibasic plugin is Open Source and distributed under The MIT License. Please see the LICENSE file included with The Rosendale Project.

Installation

Stable versions of the rosendale.clibasic plugin are available via PyPi and can be installed by easy_install, pip, or similar:

$ easy_install rosendale.clibasic

You will want to add ‘rosendale.clibasic’ to your applications ‘setup.py’ under the section ‘install_requires’.

Configuration

The clibasic plugin can be enabled by adding a plugin config under your applications ‘plugin_config_dir’ (set via your applications primary config file). I.e:

/etc/helloworld/plugins.d/clibasic.conf

[clibasic]
plugin_enabled = true
provider = rosendale

This plugin does not honor any other configuration options than that.

Usage Within Your Application

To demonstrate usage we have created a fresh ‘helloworld’ application via the paster cement-app helper. We’ve then enabled the rosendale plugin by creating the file ‘~/.helloworld/etc/plugins.d/clibasic.conf’ with the config listed above.

$ helloworld --help
loading clibasic plugin
Usage:   helloworld [COMMAND] --(OPTIONS)

Commands:
    get-config, get-started, list-plugins, cmd1

Help?  try '[COMMAND]-help' OR '[NAMESPACE] --help'

Options:
    --version          show program's version number and exit
    -h, --help         show this help message and exit
    -R, --root-option  Example root option
    --json             render output as json (CLI-API)
    --debug            toggle debug output
    --quiet            disable console logging
    -L LEVEL           log level [debug, info, warn, error, fatal]

You can see the additional commands ‘get-config’, and ‘list-plugins’ as well as the option ‘-L LEVEL’. There are also a few hidden command called ‘list-hidden-commands’, and ‘list-hooks’.

The ‘list-plugins’ command does just that, it lists any plugins that are enabled and loaded in your application:

$ helloworld list-plugins
loading clibasic plugin

plugin              ver       description
==================  ========  ================================================
clibasic            0.1.1     Basic CLI Commands for Cement Applications

The ‘list-hooks’ command is helpful for development to display what hooks are available for the developer to tie into:

$ helloworld list-hooks
loading clibasic plugin

validate_config_hook
post_bootstrap_hook
post_options_hook
post_plugins_hook
options_hook
pre_plugins_hook

The ‘list-hidden-commands’ command lists any commands that are hidden and do not show up under ‘–help’ output.

$ helloworld list-hidden-commands
loading clibasic plugin

list-hidden-commands
list-hidden-commands-json
default
error-json
get-config-help-json
get-config-json
cmd1-help-json
list-hooks
cmd1-json
error
default-json
list-plugins-json
list-hooks-json
get-started-json

The ‘get-config’ command displays the applications ‘root’ config by default. Alternatively, you can pass a ‘namespace’ to display just that namespace’s configuration:

$ helloworld get-config
loading clibasic plugin

Namespace: root

config['config_source'] => defaults/Users/wdierkes/.helloworld.conf
config['merge_root_options'] => True
config['config_files'] => /etc/helloworld/helloworld.conf/Users/wdierkes/.helloworld/etc/helloworld.conf/Users/wdierkes/.helloworld.conf
config['enabled_plugins'] => rosendale.plugin.clibasic
config['debug'] => False
config['show_plugin_load'] => True
config['output_engine'] => genshi
config['app_name'] => helloworld
config['app_egg_name'] => helloworld
config['app_module'] => helloworld
config['datadir'] => /Users/wdierkes/helloworld/data
config['tmpdir'] => /Users/wdierkes/helloworld/tmp
config['log_file'] => /Users/wdierkes/helloworld/log/helloworld.log
config['plugin_config_dir'] => /Users/wdierkes/.helloworld/etc/plugins.d
config['log_to_console'] => True
config['log_level'] => warn
config['clibasic'] => config_sourcemerge_root_optionsenable_pluginprovider


$ helloworld get-config clibasic
loading clibasic plugin

Namespace: clibasic

config['config_source'] => defaults/Users/wdierkes/.helloworld.conf/Users/wdierkes/.helloworld.conf/Users/wdierkes/.helloworld/etc/plugins.d/clibasic.conf
config['merge_root_options'] => True
config['enable_plugin'] => True
config['provider'] => rosendale

The following example show how to use the -L option to toggle log level. The first time the command is run no log output displays at console because the log_level is set to ‘warn’ in the config file. The second time run, by passing the ‘-L info’ option we toggle the log_level to INFO:

$ helloworld cmd1
loading clibasic plugin

In helloworld.controllers.root.cmd1()

    * one
    * two
    * three


$ helloworld cmd1 -L info
loading clibasic plugin
INFO: Running cmd1 command

In helloworld.controllers.root.cmd1()

    * one
    * two
    * three