update docs on plugins; fix tests

Author: dwhswenson

docs/plugins.rst

@@ -8,23 +8,33 @@ There are two possible ways to distribute plugins (file plugins and
 namespace plugins), but a given plugin script could be distributed either
 way. 
 
-Writing a plugin script
------------------------
-
-An OPS plugin is simply a Python module that follows a few rules.
-
-* It must define a variable ``CLI`` that is the main CLI function is
-  assigned to.
-* It must define a variable ``SECTION`` to determine where to show it in
-  help (what kind of command it is). Valid values are ``"Simulation"``,
-  ``"Analysis"``, ``"Miscellaneous"``, or ``"Workflow"``. If ``SECTION`` is
-  defined but doesn't have one of these values, it won't show in
-  ``openpathsampling --help``, but might still be usable. If your command
-  doesn't show in the help, carefully check your spelling of the ``SECTION``
-  variable.
-* The main CLI function must be decorated as a ``click.command``.
-* (If distributed as a file plugin) It must be possible to ``exec`` it in an
-  empty namespace (mainly, this can mean no relative imports).
+Writing a command plugin
+------------------------
+
+To write an OPS command plugin, you simply need to create an instance of
+:class:`paths_cli.OPSCommandPlugin` and to install the module in a location
+where the CLI knows to look for it. The input parameters to
+``OPSCommandPlugin`` are:
+
+* ``command``: This is the main CLI function for the subcommand. It must be
+  decorated as a ``click.Command``.
+* ``section``: This is a string to determine where to show it in help (what
+  kind of command it is).  Valid values are ``"Simulation"``,
+  ``"Analysis"``, ``"Miscellaneous"``, or ``"Workflow"``. If ``section``
+  doesn't have one of these values, it won't show in ``openpathsampling
+  --help``, but might still be usable. If your command doesn't show in the
+  help, carefully check your spelling of the ``section`` variable.
+* ``requires_ops`` (optional, default ``(1, 0)``): Minimum allowed version
+  of OpenPathSampling. Note that this is currently informational only, and
+  has no effect on functionality.
+* ``requires_cli`` (optional, default ``(0, 3)``): Minimum allowed version
+  of the OpenPathSampling CLI.  Note that this is currently informational
+  only, and has no effect on functionality.
+
+
+If you distribute your plugin as a file-based plugin, be aware that it must
+be possible to ``exec`` it in an empty namespace (mainly, this can mean no
+relative imports).
 
 As a suggestion, I (DWHS) tend to structure my plugins as follows:
 
@@ -41,16 +51,15 @@ As a suggestion, I (DWHS) tend to structure my plugins as follows:
         ...
         return final_status, simulation
 
-    CLI = plugin
-    SECTION = "MySection"
+    PLUGIN = OPSCommandPlugin(command=plugin, section="MySection")
 
 The basic idea is that there's a ``plugin_main`` function that is based on
 pure OPS, using only inputs that OPS can immediately understand (no need to
 process the command line). This is easy to develop/test with OPS. Then
 there's a wrapper function whose sole purpose is to convert the command line
 parameters to something OPS can understand (using the ``get`` method). This
-wrapper is the ``CLI`` variable. Give it an allowed ``SECTION``, and the
-plugin is ready!
+wrapper is the ``command`` in you ``OPSCommandPlugin``. Also provide an
+allowed ``section``, and the plugin is ready!
 
 The result is that plugins are astonishingly easy to develop, once you have
 the scientific code implemented in a library. This structure also makes it

paths_cli/param_core.py

@@ -269,7 +269,7 @@ class OPSStorageLoadSingle(AbstractLoader):
         parameter. Each should be a callable taking a storage and the string
         input from the CLI, and should return the desired object or None if
         it cannot be found.
-    none_strategies : List[Callable[:class:`openpathsampling.Storage, Any]]
+    none_strategies : List[Callable[:class:`openpathsampling.Storage`, Any]]
         The strategies to be used when the CLI does not provide a value for
         this parameter. Each should be a callable taking a storage, and
         returning the desired object or None if it cannot be found.

paths_cli/plugin_management.py

@@ -47,14 +47,14 @@ class OPSPlugin(Plugin):
     Really just to rename ``requires_lib`` to ``requires_ops``.
     """
     def __init__(self, requires_ops, requires_cli):
-        super(OPSPlugin, self).__init__(requires_ops, requires_cli)
+        super().__init__(requires_ops, requires_cli)
 
     @property
     def requires_ops(self):
         return self.requires_lib
 
 
-class OPSCommandPlugin(Plugin):
+class OPSCommandPlugin(OPSPlugin):
     """Plugin for subcommands to the OPS CLI
 
     Parameters

paths_cli/tests/test_plugin_management.py

@@ -10,6 +10,12 @@
 # need to check that CLI is assigned to correct type
 import click
 
+def test_ops_plugin():
+    plugin = OPSPlugin(requires_ops=(1,2), requires_cli=(0,4))
+    assert plugin.requires_ops == (1, 2)
+    assert plugin.requires_cli == (0, 4)
+    assert plugin.requires_lib == (1, 2)
+
 class PluginLoaderTest(object):
     def setup(self):
         self.expected_section = {'pathsampling': "Simulation",