``opgee.subcommand``
================================

The ``opg`` script can be extended using plug-ins, i.e., python modules that
are loaded on demand into opg. 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 ``OPGEE.PluginPath``. For
example, you might create a file ``foo_plugin.py`` in the directory ``~/plugins``.
You would then set ``OPGEE.PluginPath = %(Home)s/plugins`` in the ``~/opgee.cfg``
configuration file.

Plugins are loaded by ``opg`` on demand, i.e., when the plugin is referenced
on the ``opg`` 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
``opgee/etc/pluginTemplate.py``, which contains the code shown here.

.. literalinclude:: ../../opgee/etc/pluginTemplate.py
   :language: python

API
---

.. automodule:: opgee.subcommand
   :members: