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
addArgsmethod 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
runmethod 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.
.. literalinclude:: ../../pygcam/etc/pluginTemplate.py :language: python
.. automodule:: pygcam.subcommand :members: