Improve launching service plugins interactively from the command line

Some service plugins need section-wide top-level configuration settings.
Now, there are two options "--config" and "--options" to be able to
obtain all relevant bits of information from the command line.

Author: amotl

CHANGES.rst

@@ -12,6 +12,9 @@ in progress
 - Use STDERR as default log target
 - Stop including the "tests" folder into the sdist package
 - Add "mqttwarn-contrib" package to the list of "extra" dependencies
+- Improve launching service plugins interactively from the command line
+  Now, there are two options "--config" and "--options" to be able to
+  obtain all relevant bits of information from the command line.
 
 
 2021-06-18 0.25.0

HANDBOOK.md

@@ -638,9 +638,10 @@ targets  = {
     'speaker' : ['Living Room'],
     }
 
+# Command line test
+# mqttwarn --plugin=chromecast --options='{"message": "Hello world", "addrs": ["Living Room"]}'
 # echo 'Hello world' | mosquitto_pub -t 'chromecast/say' -l
 # echo '{"message": "Hello world", "addrs": ["Living Room"]}' | mosquitto_pub -t 'chromecast/say' -l
-# command line test;  mqttwarn --plugin=chromecast --data='{"message": "Hello world", "addrs": ["Living Room"]}'
 [chromecast/say]
 targets = chromecast:speaker
 

README.rst

@@ -162,15 +162,20 @@ We have you covered. To launch a plugin standalone, those commands will give
 you an idea how to pass relevant information on the command line using JSON::
 
     # Launch "log" service plugin
-    mqttwarn --plugin=log --data='{"message": "Hello world", "addrs": ["crit"]}'
+    mqttwarn --plugin=log --options='{"message": "Hello world", "addrs": ["crit"]}'
 
     # Launch "file" service plugin
-    mqttwarn --plugin=file --data='{"message": "Hello world\n", "addrs": ["/tmp/mqttwarn.err"]}'
+    mqttwarn --plugin=file --options='{"message": "Hello world\n", "addrs": ["/tmp/mqttwarn.err"]}'
 
     # Launch "pushover" service plugin
-    mqttwarn --plugin=pushover --data='{"title": "About", "message": "Hello world", "addrs": ["userkey", "token"], "priority": 6}'
+    mqttwarn --plugin=pushover --options='{"title": "About", "message": "Hello world", "addrs": ["userkey", "token"], "priority": 6}'
 
-The ``--config`` parameter can be used to optionally specify a configuration file.
+    # Launch "cloudflare_zone" service plugin from "mqttwarn-contrib", passing "--config" parameters via command line
+    mqttwarn --plugin=mqttwarn_contrib.services.cloudflare_zone --config='{"auth-email": "foo", "auth-key": "bar"}' --options='{"addrs": ["0815", "www.example.org", ""], "message": "192.168.0.1"}'
+
+
+Also, the ``--config-file`` parameter can be used to optionally specify the
+path to a configuration file.
 
 
 Running as system daemon

doc/backlog.rst

@@ -50,7 +50,7 @@ Goals for 0.21.0
 Goals for 1.0.0
 ***************
 - [o] Make mqttwarn completely unicode-safe
-- [o] Make "mqttwarn --plugin=log --data=" obtain JSON data from STDIN
+- [o] Make "mqttwarn --plugin=log --options=" obtain JSON data from STDIN
 - [o] Translate documentation into reStructuredText format,
       render it using Sphinx and optionally publish to readthedocs.org.
 - [o] Add support for Python 3

mqttwarn/commands.py

@@ -25,13 +25,27 @@ def run():
     Usage:
       {program} [make-config]
       {program} [make-samplefuncs]
-      {program} [--config=] [--plugin=] [--data=]
+      {program} [--config=] [--config-file=] [--plugin=] [--options=]
       {program} --version
       {program} (-h | --help)
 
-    Configuration file options:
-      make-config               Will dump configuration file content to STDOUT,
+    No options:
+      mqttwarn will start as a service.
+
+    Interactive options:
+      [--config=]               Use configuration settings from JSON string
+      [--config-file=]          Use configuration settings from JSON file
+      [--plugin=]               The plugin name to load. This can either be a
+                                full qualified Python package/module name or a
+                                path to a Python file.
+      [--options=]              Configuration options to propagate to the plugin
+                                entrypoint.
+
+    Bootstrapping options:
+      make-config               Dump configuration file blueprint to STDOUT,
                                 suitable for redirecting into a configuration file.
+      make-samplefuncs          Dump blueprint for custom functions file to STDOUT,
+                                suitable for redirecting into a `samplefuncs.py` file.
 
     Miscellaneous options:
       --version                 Show version information
@@ -61,24 +75,27 @@ def run():
         payload = get_resource_content('mqttwarn.examples', 'basic/samplefuncs.py')
         print(payload)
 
-    elif options['--plugin'] and options['--data']:
+    elif options['--plugin'] and options['--options']:
 
         # Decode arguments
-        plugin = options['--plugin']
-        data = json.loads(options['--data'])
+        arg_plugin = options['--plugin']
+        arg_options = json.loads(options['--options'])
+        arg_config = None
+        if "--config" in options and options['--config'] is not None:
+            arg_config = json.loads(options['--config'])
 
         # Launch service plugin in standalone mode
-        launch_plugin_standalone(plugin, data, configfile=options.get("--config"))
+        launch_plugin_standalone(arg_plugin, arg_options, configfile=options.get("--config-file"), config_more=arg_config)
 
 
     # Run mqttwarn in service mode when no command line arguments are given
     else:
         run_mqttwarn()
 
 
-def launch_plugin_standalone(plugin, data, configfile=None):
+def launch_plugin_standalone(plugin, options, configfile=None, config_more=None):
 
-    # Load configuration file
+    # Optionally load configuration file
     does_not_exist = False
     scriptname = os.path.splitext(os.path.basename(sys.argv[0]))[0]
     try:
@@ -89,15 +106,21 @@ def launch_plugin_standalone(plugin, data, configfile=None):
         section = "config:{}".format(plugin)
         config.add_section(section)
 
+    # Optionally add additional config settings from command line.
+    if config_more is not None:
+        section = "config:{}".format(plugin)
+        for key, value in config_more.items():
+            config.set(section, key, value)
+
     # Setup logging
     setup_logging(config)
     if does_not_exist:
         logger.info('Configuration file "{}" does not exist, using default settings'.format(configfile))
 
-    logger.info('Running service plugin "{}" with data "{}"'.format(plugin, data))
+    logger.info('Running service plugin "{}" with options "{}"'.format(plugin, options))
 
     # Launch service plugin
-    run_plugin(config=config, name=plugin, data=data)
+    run_plugin(config=config, name=plugin, options=options)
 
 
 def run_mqttwarn():

mqttwarn/core.py

@@ -713,7 +713,7 @@ def bootstrap(config=None, scriptname=None):
         SCRIPTNAME = scriptname
 
 
-def run_plugin(config=None, name=None, data=None):
+def run_plugin(config=None, name=None, options=None):
     """
     Run service plugins directly without the
     dispatching and transformation machinery.
@@ -723,9 +723,9 @@ def run_plugin(config=None, name=None, data=None):
     the innards of mqttwarn interact so it might also please
     newcomers as a "learning the guts of mqttwarn" example.
 
-    :param config: The configuration object
-    :param name:   The name of the service plugin, e.g. "log" or "file"
-    :param data:   The data to be converged into an appropriate item Struct object instance
+    :param config:   The configuration object
+    :param name:     The name of the service plugin, e.g. "log" or "file"
+    :param options:  The data to be converged into an appropriate item Struct object instance
     """
 
     # Bootstrap mqttwarn core
@@ -741,7 +741,7 @@ def run_plugin(config=None, name=None, data=None):
     srv = make_service(mqttc=None, name=service_logger_name)
 
     # Build a mimikry item instance for feeding to the service plugin
-    item = Struct(**data)
+    item = Struct(**options)
     # TODO: Read configuration optionally from data.
     item.config = config.config('config:' + name)
     item.service = srv