flux.cli.plugin module

class flux.cli.plugin.CLIPlugin(prog, prefix='ex', version=None)

Bases: ABC

Base class for a CLI submission plugin

A plugin should derive from this class and implement one or more base methods (described below)

command-line subcommand for which the plugin is active, e.g. "submit", "run", "alloc", "batch", "bulksubmit"

Type: str

prefix

By default, --ex- is added as a prefix to ensure plugin-provided options are namespaced. The prefix may be overridden with a site or project name.

Type: str

add_option(name, **kwargs)

Allow plugin to register options in its dictionary

Parameters: name (str) -- Long option string being added (must begin with --).

Other keyword arguments, except dest= are passed along to ArgumentParser.add_argument unchanged. When dest= is not given it is derived from the full prefixed CLI flag name (e.g. --site-my-option = site_my_option) so that the kwarg name matches what callers see in --help output. An explicit dest= is used as-is and no backward-compatibility alias is constructed. As a convenience, within plugin callbacks accesses to args.my_option are automatically proxied for plugins to args.<prefix>_my_option.

Plugins use: >>> self.add_option("--longopt", action="store_true", help="Help.")

to add new options to its options list. If the option should only be active for certain subcommands, then the option should be added conditionally based on self.prog.

The options list is queried by the command (self.prog), which loads the registered options with argparse.

help(option)

Print a help message for this plugin and option option

By default, prints the plugin's docstring to stdout. Plugins may override this behavior by overriding this method.

modify_jobspec(args, jobspec)

Allow plugin to modify jobspec

This function is called after arguments have been parsed and jobspec has mostly been initialized.

Parameters

args (Namespace) -- Namespace result from Argparse.ArgumentParser.parse_args().
jobspec (flux.job.Jobspec) -- instantiated jobspec object. This plugin can modify this object directly to enact changes in the current programs generated jobspec.

preinit(args): After parsing options, before jobspec is initialized

validate(jobspec)

Allow a plugin to validate jobspec

This callback may be used by the cli itself or a job validator to validate the final jobspec.

On an invalid jobspec, this callback should raise ValueError with a useful error message.

Parameters: jobspec (flux.job.Jobspec) -- jobspec object to validate.

class flux.cli.plugin.CLIPluginOption(name, prefix, **kwargs)

Bases: object

Wrap Argparse's add_argument method with a class

property dest

class flux.cli.plugin.CLIPluginRegistry(prog)

Bases: object

Flux CLI plugin registry helper class

default_plugins = ['shape']

modify_jobspec(args, jobspec): Call all plugin modify_jobspec callbacks

plugin_namespace = 'flux.cli.plugins'

preinit(args): Call all plugin preinit callbacks

print_help(name)

Print docstring for plugin associated with option name and exit

Raises: ValueError -- No help found for name

print_plugins(): Print all of the plugins loaded by _load_plugins.

validate(jobspec): Call any plugin validate callback

class flux.cli.plugin.PluginArgsProxy(args, alias)

Bases: object

Per-plugin proxy for the args namespace passed to plugin callbacks.

Translates attribute access using an unprefixed dest name (e.g. my_option) to the current prefixed dest (e.g. site_my_option), so that existing plugin callback code continues to work after the dest was changed to include the prefix.

Attributes not in the alias map (i.e. from builtin options such as conf and env) pass through to the underlying namespace unchanged.