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 13, 2021 · 714bfc1 · 714bfc1
1 parent 50dd089
commit 714bfc1
Show file tree

Hide file tree

Showing 12 changed files with 1,474 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,226 @@
+
+.. _`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. The default and allowed output formats are
+                                      command specific. The default output_format is None so that each command selects its
+                                      own default format. Use "" to set default in interactive mode. FORMAT is: table
+                                      formats: [table|plain|simple|grid|psql|rst|html]; CIM object formats:
+                                      [mof|xml|repr|txt]]; TEXT formats: [text].
+
+      -l, --log COMP[=DEST[:DETAIL]],...
+                                      Enable logging of the WBEM operations, defined by a list of log configuration strings
+                                      with: COMP: [api|http|all]; DEST: [file|stderr|off], default: file; DETAIL:
+                                      [all|paths|summary], default: all.  Use "" to set default in interactive modeDefault:
+                                      EnvVar PYWBEMCLI_LOG, or all.
+
+      -v, --verbose / --no-verbose    Display extra information about the processing.
+      --pdb                           Pause execution in the built-in pdb debugger just before executing the command within
+                                      pywbemcli. Ignored in interactive mode, but can be specified on each interactive
+                                      command. Default: EnvVar PYWBEMCLI_PDB, or false.
+
+      --warn / --no-warn              Warnings control: True enables display of all Python warnings; False leaves warning
+                                      control to the PYHONWARNINGS env var, which by default displays no warnings. Default:
+                                      False.
+
+      --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.
+
+      -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: Certificate file.
+
+      -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.
+
+      -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: Certificate file.
+
+      -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.
+
diff --git a/docs/pywbemlistener/index.rst b/docs/pywbemlistener/index.rst
@@ -0,0 +1,50 @@
+.. Copyright 2021 Inova Development Inc.
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..    http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _`Pywbemlistener command`:
+
+Pywbemlistener command
+======================
+
+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 maxdepth attribute overrides the maxdepth attribute of the
+.. mastertoc if used.
+.. The numbered attribute intentionally is not set, because the numbering
+.. on sub-TOCs is created automatically when set on the top-level TOC.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Table of Contents in this Section:
+
+   cmdshelp.rst
+
+.. # TODO: Write these sections:
+   cmdlineinterface.rst
+   generaloptions.rst
+   features.rst
+   commands.rst
diff --git a/minimum-constraints.txt b/minimum-constraints.txt
@@ -20,7 +20,9 @@
 
 # Direct dependencies for install (must be consistent with requirements.txt)
 
-pywbem==1.2.0
+
+# TODO: Enable pywbem 1.3.0 once released, before releasing pywbemtools
+# pywbem==1.3.0
 # When using the GitHub master branch of pywbem, simply comment out the line
 # above, since links are not allowed in constraint files - the minimum will be
 # ensured by requirements.txt then.
@@ -44,6 +46,7 @@ PyYAML==5.3.1; python_version >= '3.5'
 yamlloader==0.5.5
 mock==3.0.0
 toposort==1.6
+psutil==5.5.0
 
 # Virtualenv
 virtualenv==14.0.0; python_version < '3.5'