pygcam.subcommand

Gcamtool can be extended using plug-ins, i.e., python modules that are loaded on demand into gcamtool. The subcommand module provides the interface for subcommand plug-ins.

Each plug-in is implemented as a Python module in a file named {subcommand}_plugin.py, where {subcommand} matches the name of the sub-command specified in the __init__ method, described below.

The plug-in module must provides a class that is a subclass of the abstract base class SubcommandABC, and must define define three methods: __init__, addArgs, and run.

• The __init__ method should define keyword arguments that provide the text used when the help option is specified by the user.
• The addArgs method should define command-line arguments specific to the sub-command, and return the parser instance, which allows Sphinx to generate command-line documentation (i.e., these web pages.)
• The run method implements the desired plug-in functionality.

The plug-in file must also identify the plug-in class, either by defining the variable PluginClass and assigning to it the class that implements the sub-command, or by simply naming the class Plugin, obviating the need to assign to the PluginClass variable.

Plugins can be stored in any directory or directories that are on the “plugin path” set using the config file parameter GCAM.PluginPath. For example, you might create a file foo_plugin.py in the directory ~/plugins. You would then set GCAM.PluginPath = %(Home)s/plugins in the ~/.pygcam.cfg configuration file.

Plugins are loaded by gt on demand, i.e., when the plugin is referenced on the gt command-line, or implicitly when all steps are run. They are also loaded when the help (--help or -h) options are specified, so that the plugins appear in the generated documentation.

The following template can be used to create new sub-commands. See also pygcam/etc/pluginTemplate.py, which contains the code shown here.

#
# N.B. Avoid loading anything but SubcommandABC at the top level so that
# '-h / --help' runs as quickly as possible. Import needed files in the
# run() method instead.
#
from pygcam.subcommand import SubcommandABC

class MyNewCommand(SubcommandABC):
    def __init__(self, subparsers):
        kwargs = {'help' : '''Short help text for main driver''',
                  'description' : '''Longer description for sub-command'''}

        # The first argument is the name of the new sub-command
        super(MyNewCommand, self).__init__('subCmdName', subparsers, kwargs)

    def addArgs(self):
        '''
        Process the command-line arguments for this sub-command
        '''
        parser = self.parser

        parser.add_argument('-n', '--number', type=int, default=0,
                            help='''A number to demonstrate a command line arg.
                            Replace as needed with your own plugin's args.''')

        return parser

    def run(self, args, tool):
        '''
        Implement the sub-command here. "args" is an `argparse.Namespace` instance
        holding the parsed command-line arguments, and "tool" is a reference to
        the running GcamTool instance.
        '''
        # from pygcam.log import getLogger
        # _logger = getLogger(__name__)

        pass

# An alternative to naming the class 'Plugin' is to assign the class to PluginClass
PluginClass = MyNewCommand

API

class pygcam.subcommand.SubcommandABC(name, subparsers, kwargs, group=None, label=None, guiSuppress=False)

Abstract base class for sub-commands. Defines the protocol expected by gt for defining sub-commands. Plugin files should be named '*_plugin.py' and must define a subclass of SubcommandABC. To allow the class to be identified, it can be named Plugin or the global variable PluginClass can identify the class.

Parameters:

• name – (str) the name of the sub-command
• subparsers – an object returned by argparse’s parser.add_subparsers()
• kwargs – (dict) keywords to pass to the the call to argparse’s subparsers.add_parser(name, **kwargs), e.g., to pass help or documentation strings.
• group – (str) the name of the GUI group to assign this plug-in to.
• label – (str) the label to use on the GUI to reference this plug-in. Defaults to the sub-command name, capitalized.
• guiSuppress – (bool) if True, do not display this sub-command in the GUI.

addArgs(parser)

Add command-line arguments to the given parser. (This is an abstract method that must be implemented in the subclass.)

Parameters:parser – the sub-parser associated with this sub-command. Returns:the populated parser

run(args, tool)

Perform the function intended by the SubcommandABC subclass. This function is invoked by gt on the SubcommandABC instance whose name matches the given sub-command. (This is an abstract method that must be implemented in the subclass.)

Parameters:

• args – the argument dictionary
• tool – the GcamTool instance for the main command

Returns:

nothing