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.pluginTemplate.py, which contains the code shown here.)

from pygcam.subcommand import SubcommandABC
from pygcam.log import getLogger

_logger = getLogger(__name__)
VERSION = "0.0"

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

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

    def addArgs(self):
       '''Process 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''')

        parser.add_argument('-V', '--version', action='version',
                            version='%(prog)s ' + VERSION)

        # return the parser to facilitate automatic documentation generation
        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.
        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)

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
  • 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.
  • subparsers – an object returned by argparse’s parser.add_subparsers()
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