Added pywbemlistener command

Details: * Added a new 'pywbemlistener' command that manages WBEM indication listeners. (see issue #430) * Removed Python 3.4 on Windows from GitHub Actions tests, because this environment does not have the Microsoft Visual C++ 10.0 compiler needed for building the 'psutils' package. Signed-off-by: Andreas Maier <[email protected]>
pywbem · May 16, 2021 · b0a95f5 · b0a95f5
1 parent a1f0e2f
commit b0a95f5
Show file tree

Hide file tree

Showing 13 changed files with 1,910 additions and 9 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -60,6 +60,16 @@ jobs:
                 \"os\": \"macos-latest\", \
                 \"python-version\": \"3.4\", \
                 \"package_level\": \"latest\" \
+              }, \
+              { \
+                \"os\": \"windows-latest\", \
+                \"python-version\": \"3.4\", \
+                \"package_level\": \"minimum\" \
+              }, \
+              { \
+                \"os\": \"windows-latest\", \
+                \"python-version\": \"3.4\", \
+                \"package_level\": \"latest\" \
               } \
             ], \
             \"include\": [ \
@@ -113,12 +123,12 @@ jobs:
               }, \
               { \
                 \"os\": \"windows-latest\", \
-                \"python-version\": \"3.4\", \
+                \"python-version\": \"3.5\", \
                 \"package_level\": \"minimum\" \
               }, \
               { \
                 \"os\": \"windows-latest\", \
-                \"python-version\": \"3.4\", \
+                \"python-version\": \"3.5\", \
                 \"package_level\": \"latest\" \
               } \
             ] \

diff --git a/Makefile b/Makefile
@@ -144,6 +144,7 @@ package_name := pywbemtools
 # Names of the commands in the package. The command names are used in
 # certain directory names.
 command1 := pywbemcli
+command2 := pywbemlistener
 
 # Determine if coverage details report generated
 # The variable can be passed in as either an environment variable or
@@ -207,6 +208,7 @@ doc_opts := -v -d $(doc_build_dir)/doctrees -c $(doc_conf_dir) -D latex_elements
 # File names of automatically generated utility help message text output
 doc_utility_help_files := \
     $(doc_conf_dir)/$(command1)/cmdshelp.rst \
+    $(doc_conf_dir)/$(command2)/cmdshelp.rst \
 
 # Dependents for Sphinx documentation build
 doc_dependent_files := \
@@ -450,6 +452,7 @@ install: install_$(pymn).done
 install_$(pymn).done: Makefile install_basic_$(pymn).done install_$(package_name)_$(pymn).done
 	-$(call RM_FUNC,$@)
 	$(PYTHON_CMD) -c "import $(package_name).$(command1)"
+	$(PYTHON_CMD) -c "import $(package_name).$(command2)"
 	echo "done" >$@
 
 # The following target is supposed to install any prerequisite OS-level packages
@@ -708,3 +711,12 @@ else
 	PYWBEMTOOLS_TERMWIDTH=$(pywbemtools_termwidth) $(PYTHON_CMD) -u tools/click_help_capture.py $(command1) >$@
 endif
 	@echo 'Done: Created help command info for cmds: $@'
+
+$(doc_conf_dir)/$(command2)/cmdshelp.rst: $(package_name)/$(command2)/$(command2).py install_$(pymn).done tools/click_help_capture.py $(doc_help_source_files)
+	@echo 'makefile: Creating $@ for documentation'
+ifeq ($(PLATFORM),Windows_native)
+	cmd /c "set PYWBEMTOOLS_TERMWIDTH=$(pywbemtools_termwidth) & $(PYTHON_CMD) -u tools/click_help_capture.py $(command2) >$@"
+else
+	PYWBEMTOOLS_TERMWIDTH=$(pywbemtools_termwidth) $(PYTHON_CMD) -u tools/click_help_capture.py $(command2) >$@
+endif
+	@echo 'Done: Created help command info for cmds: $@'
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,9 +1,11 @@
 
-Pywbemtools - A set of tools using pywbem
-*****************************************
+Pywbemtools - WBEM command line tools
+*************************************
 
-This package contains tools that provide a command line interface to interact
-with WBEM servers
+This package contains WBEM command line tools:
+
+* pywbemcli - a WBEM client CLI for interacting with WBEM servers
+* pywbemlistener - a tool that runs and manages WBEM listeners
 
 The pywbemtools github page is: `https://github.com/pywbem/pywbemtools <https://github.com/pywbem/pywbemtools>`_.
 
@@ -15,6 +17,7 @@ The pywbemtools github page is: `https://github.com/pywbem/pywbemtools <https://
 
    introduction.rst
    pywbemcli/index.rst
+   pywbemlistener/index.rst
    development.rst
    appendix.rst
    changes.rst

diff --git a/docs/pywbemlistener/cmdshelp.rst b/docs/pywbemlistener/cmdshelp.rst
@@ -0,0 +1,257 @@
+
+.. _`pywbemlistener Help Command Details`:
+
+pywbemlistener Help Command Details
+===================================
+
+
+This section shows the help text for each pywbemlistener command group and command.
+
+
+
+Help text for ``pywbemlistener``:
+
+
+::
+
+    Usage: pywbemlistener [GENERAL-OPTIONS] COMMAND [ARGS] [COMMAND-OPTIONS]
+
+      The pywbemlistener command can run and manage WBEM listeners.
+
+      Each listener is a process that executes the 'pywbemlistener run' command to receive WBEM indications sent from a
+      WBEM server.
+
+      A listener process can be started with the 'pywbemlistener start' command and stopped with the 'pywbemlistener stop'
+      command.
+
+      There is no central registration of the currently running listeners. Instead, the currently running processes
+      executing the 'pywbemlistener run' command are by definition the currently running listeners. Because of this, there
+      is no notion of a stopped listener nor does a listener have an operational status.
+
+      The general options shown below can also be specified on any of the commands, positioned right after the
+      'pywbemlistener' command name.
+
+      The width of help texts of this command can be set with the PYWBEMTOOLS_TERMWIDTH environment variable.
+
+      For more detailed documentation, see:
+
+          https://pywbemtools.readthedocs.io/en/stable/
+
+    General Options:
+      -o, --output-format FORMAT  Output format for the command result. FORMAT is one of the table formats:
+                                  [table|plain|simple|grid|psql|rst|html].
+
+      -l, --logdir DIR            Enable logging of the 'pywbemlistener run' command output to a file in a log directory.
+                                  The file will be named 'pywbemlistener_NAME.log' where NAME is the listener name. Default:
+                                  EnvVar PYWBEMLISTENER_LOGDIR, or no logging.
+
+      -v, --verbose               Verbosity level. Can be specified multiple times: -v: Display indication processing
+                                  settings; -vv: Display interactions between start and run commands.
+
+      --pdb                       Pause execution in the built-in pdb debugger just before executing the command within
+                                  pywbemlistener. Default: EnvVar PYWBEMLISTENER_PDB, or no debugger.
+
+      --warn                      Enable display of all Python warnings. Default: Leave warning control to the
+                                  PYTHONWARNINGS EnvVar, which by default displays no warnings.
+
+      --version                   Show the version of this command and the pywbem package.
+      -h, --help                  Show this help message.
+
+    Commands:
+      list   List the currently running named WBEM indication listeners.
+      run    Run as a named WBEM indication listener.
+      show   Show a named WBEM indication listener.
+      start  Start a named WBEM indication listener in the background.
+      stop   Stop a named WBEM indication listener.
+
+
+.. _`pywbemlistener list --help`:
+
+pywbemlistener list --help
+--------------------------
+
+
+
+Help text for ``pywbemlistener list`` (see :ref:`list command group`):
+
+
+::
+
+    Usage: pywbemlistener [GENERAL-OPTIONS] list [COMMAND-OPTIONS]
+
+      List the currently running named WBEM indication listeners.
+
+      This is done by listing the currently running `pywbemlistener run` commands.
+
+    Command Options:
+      -h, --help  Show this help message.
+
+
+.. _`pywbemlistener run --help`:
+
+pywbemlistener run --help
+-------------------------
+
+
+
+Help text for ``pywbemlistener run`` (see :ref:`run command group`):
+
+
+::
+
+    Usage: pywbemlistener [GENERAL-OPTIONS] run NAME [COMMAND-OPTIONS]
+
+      Run as a named WBEM indication listener.
+
+      Run this command as a named WBEM indication listener until it gets terminated, e.g. by a keyboard interrupt, break
+      signal (e.g. kill), or the `pywbemlistener stop` command.
+
+      A listener with that name must not be running, otherwise the command fails.
+
+      Examples:
+
+        pywbemlistener run lis1
+
+    Command Options:
+      --port PORT                  The port number the listener will open to receive indications. This can be any available
+                                   port. Default: 25989
+
+      --protocol PROTOCOL          The protocol used by the listener (http, https). Default: https
+      -c, --certfile FILE          Path name of a PEM file containing the certificate that will be presented as a server
+                                   certificate during SSL/TLS handshake. Required when using https. The file may in addition
+                                   contain the private key of the certificate. Default: EnvVar PYWBEMLISTENER_CERTFILE, or
+                                   no certificate file.
+
+      -k, --keyfile FILE           Path name of a PEM file containing the private key of the server certificate. Required
+                                   when using https and when the certificate file does not contain the private key. Default:
+                                   EnvVar PYWBEMLISTENER_KEYFILE, or no key file.
+
+      --indi-call MODULE.FUNCTION  Call a Python function for each received indication. Invoke with --help-call for details
+                                   on the function interface. Default: No function is called.
+
+      --indi-display               Display received indications on stdout. The format can be modified using the --indi-
+                                   format option. Default: Not displayed.
+
+      --indi-file FILE             Append received indications to a file. The format can be modified using the --indi-format
+                                   option. Default: Not appended.
+
+      --indi-format FORMAT         Sets the format to be used when displaying received indications. Invoke with --help-
+                                   format for details on the format specification. Default: "{dt} {h} {c} {p}".
+
+      --help-format                Show help message for the format specification used with the --indi-format option.
+      --help-call                  Show help message for calling a Python function for each received indication when using
+                                   the --indi-call option.
+
+      -h, --help                   Show this help message.
+
+
+.. _`pywbemlistener show --help`:
+
+pywbemlistener show --help
+--------------------------
+
+
+
+Help text for ``pywbemlistener show`` (see :ref:`show command group`):
+
+
+::
+
+    Usage: pywbemlistener [GENERAL-OPTIONS] show NAME [COMMAND-OPTIONS]
+
+      Show a named WBEM indication listener.
+
+      A listener with that name must be running, otherwise the command fails.
+
+      Examples:
+
+        pywbemlistener stop lis1
+
+    Command Options:
+      -h, --help  Show this help message.
+
+
+.. _`pywbemlistener start --help`:
+
+pywbemlistener start --help
+---------------------------
+
+
+
+Help text for ``pywbemlistener start`` (see :ref:`start command group`):
+
+
+::
+
+    Usage: pywbemlistener [GENERAL-OPTIONS] start NAME [COMMAND-OPTIONS]
+
+      Start a named WBEM indication listener in the background.
+
+      A listener with that name must not be running, otherwise the command fails.
+
+      A listener is identified by its hostname or IP address and a port number. It can be started with any free port.
+
+      Examples:
+
+        pywbemlistener start lis1
+
+    Command Options:
+      --port PORT                  The port number the listener will open to receive indications. This can be any available
+                                   port. Default: 25989
+
+      --protocol PROTOCOL          The protocol used by the listener (http, https). Default: https
+      -c, --certfile FILE          Path name of a PEM file containing the certificate that will be presented as a server
+                                   certificate during SSL/TLS handshake. Required when using https. The file may in addition
+                                   contain the private key of the certificate. Default: EnvVar PYWBEMLISTENER_CERTFILE, or
+                                   no certificate file.
+
+      -k, --keyfile FILE           Path name of a PEM file containing the private key of the server certificate. Required
+                                   when using https and when the certificate file does not contain the private key. Default:
+                                   EnvVar PYWBEMLISTENER_KEYFILE, or no key file.
+
+      --indi-call MODULE.FUNCTION  Call a Python function for each received indication. Invoke with --help-call for details
+                                   on the function interface. Default: No function is called.
+
+      --indi-display               Display received indications on stdout. The format can be modified using the --indi-
+                                   format option. Default: Not displayed.
+
+      --indi-file FILE             Append received indications to a file. The format can be modified using the --indi-format
+                                   option. Default: Not appended.
+
+      --indi-format FORMAT         Sets the format to be used when displaying received indications. Invoke with --help-
+                                   format for details on the format specification. Default: "{dt} {h} {c} {p}".
+
+      --help-format                Show help message for the format specification used with the --indi-format option.
+      --help-call                  Show help message for calling a Python function for each received indication when using
+                                   the --indi-call option.
+
+      -h, --help                   Show this help message.
+
+
+.. _`pywbemlistener stop --help`:
+
+pywbemlistener stop --help
+--------------------------
+
+
+
+Help text for ``pywbemlistener stop`` (see :ref:`stop command group`):
+
+
+::
+
+    Usage: pywbemlistener [GENERAL-OPTIONS] stop NAME [COMMAND-OPTIONS]
+
+      Stop a named WBEM indication listener.
+
+      The listener will shut down gracefully.
+
+      A listener with that name must be running, otherwise the command fails.
+
+      Examples:
+
+        pywbemlistener stop lis1
+
+    Command Options:
+      -h, --help  Show this help message.
+