Fixes #594: Simplify output and implement TEXT output group

docs/changes.rst

@@ -28,6 +28,13 @@ Released: not yet
   archive, and added install tests for various installation methods including
   this one. (see issues #590, #591).
 
+* Enhance output formats to allow an additional format group TEXT with
+  a single format ``text``. This format outputs the command result as a
+  text string to the console and is use for simple commands like
+  ``server interop`` that only output one piece of data. (see issue #594)
+
+**Cleanup**
+
 **Known issues:**
 
 * See `list of open issues`_.

docs/pywbemcli/cmdshelp.rst

@@ -106,8 +106,8 @@ Help text for ``pywbemcli``:
 
       -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. FORMAT is either a table format:
-                                      [table|plain|simple|grid|psql|rst|html] or CIM object format: [mof|xml|repr|txt].
+                                      own default format. 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

docs/pywbemcli/generaloptions.rst

@@ -185,9 +185,9 @@ Controlling output formats
 Pywbemcli supports multiple output formats for command results by using the
 :ref:`--output-format general option`.
 
-The output formats fall into three groups (table formats, CIM object formats,
-and a tree format); however, not all formats are supported or applicable for all
-commands. For more details, see :ref:`Output formats`.
+The output formats fall into several groups (table formats, CIM object formats,
+text formats, and a tree format); however, not all formats are supported or
+applicable for all commands. For more details, see :ref:`Output formats`.
 
 
 .. _`Other miscellaneous general options`:
@@ -838,7 +838,7 @@ Pywbemcli supports multiple output formats to present command results. The outpu
 format can be selected with the ``--output-format``/``-o`` option. The allowed
 output formats are different for the various command groups and commands.
 
-The output formats fall into three groups:
+The output formats fall into several groups:
 
 * **Table formats** - The :ref:`Table formats` format the result as a table
   with rows and columns. Many of the result types allow table formatted
@@ -858,15 +858,19 @@ The output formats fall into three groups:
   commands that return CIM objects support these output formats.
 
 * **ASCII tree format** - The :ref:`ASCII tree format` formats the result
-  as a tree, using ASCII characters to represent the tree. The only command
-  supporting the ASCII tree format is ``class tree``, and it supports only
-  that one output format.  The tree format is not supported by any other
-  command today.
+  as a tree, using ASCII characters to represent the tree to show the
+  hierarchial relationship between CIM classes. The only command supporting the
+  ASCII tree format is ``class tree``, and it supports only that one output
+  format.  The tree format is not supported by any other command today.
+
+* **TEXT format** - The :ref:`Text formats` is used for commands that output
+  small quantites of text (ex. the interop namespace name) and that could be
+  used as part of a command line redirection.
 
 When an unsupported output format is specified for a command response, it is
-rejected with an exception.  For example, the command
-``class enumerate`` only supports the CIM object formats and will generate an
-exception if the command ``pywbemcli -o table class enumerate`` is entered.
+rejected with an exception.  For example, the command ``class enumerate`` only
+supports the :ref:`CIM object formats` and will generate an exception if the
+command ``pywbemcli -o table class enumerate`` is entered.
 
 .. index:: single: output formats
 
@@ -927,15 +931,15 @@ table = table|plain|simple|grid|psql|rst|html
 +----------+---------------+----------+----------------+--------------------------------------------+
 |          |  get          | 'mof'    | table          |                                            |
 +----------+---------------+----------+----------------+--------------------------------------------+
-|server    |  brand        | 'simple' | table          |                                            |
+|server    |  brand        | 'text'   | text           | Alternate is table format                  |
 +----------+---------------+----------+----------------+--------------------------------------------+
 |          |centralinsts   | 'simple' | table          |                                            |
 +----------+---------------+----------+----------------+--------------------------------------------+
 |          |  info         | 'simple' | table          |                                            |
 +----------+---------------+----------+----------------+--------------------------------------------+
-|          |  interop      | 'simple' | table          |                                            |
+|          |  interop      | 'text'   | text           | Alternate is table format                  |
 +----------+---------------+----------+----------------+--------------------------------------------+
-|          |  namespaces   | 'simple' | table          |                                            |
+|          |  namespaces   | 'simple' | table          | Alternate is text format                   |
 +----------+---------------+----------+----------------+--------------------------------------------+
 |          |  profiles     | 'simple' | table          |                                            |
 +----------+---------------+----------+----------------+--------------------------------------------+
@@ -1196,6 +1200,31 @@ This shows a very simple mock repository with 4 classes where CIM_Foo is the
 top level in the hierarchy, CIM_Foo_sub and CIM_Foo_sub2 are its subclasses, and
 CIM_Foo_sub_sub is the subclass of CIM_Foo_sub.
 
+.. index:: pair: output formats; text formats
+
+.. _`Text formats`:
+
+Text formats
+""""""""""""
+
+The TEXT format group outputs the data returned from the command as text
+to the console without any formatting except for formatting lists and
+comma separated strings.  It is useful for use with data that might be
+redirected to other commands or output that is simple enough that a single
+line of output is sufficient.
+
+.. code-block:: text
+
+    $ pywbemcli --mock-server tests/unit/testmock/wbemserver_mock.py -o table server namespaces
+    Server Namespaces:
+    Namespace Name
+    ----------------
+    interop
+
+    $ pywbemcli --mock-server tests/unit/testmock/wbemserver_mock.py -o text server namespaces
+    interop
+
+
 
 .. _`Pywbemcli defined logging`:
 

pywbemtools/pywbemcli/_cmd_class.py

@@ -30,7 +30,7 @@
 from .pywbemcli import cli
 from ._common import display_cim_objects, filter_namelist, \
     resolve_propertylist, CMD_OPTS_TXT, GENERAL_OPTS_TXT, SUBCMD_HELP_TXT, \
-    TABLE_FORMATS, format_table, process_invokemethod, \
+    output_format_is_table, format_table, process_invokemethod, \
     raise_pywbem_error_exception, warning_msg, validate_output_format
 from ._common_options import add_options, propertylist_option, \
     names_only_option, include_classorigin_class_option, namespace_option,  \
@@ -586,7 +586,8 @@ def get_format_group(context, options):
 
         # This accounts for the fact that the results of a summary can be
         # either table or simply a string output
-        if context.output_format and context.output_format in TABLE_FORMATS:
+        if context.output_format and \
+                output_format_is_table(context.output_format):
             return ['TABLE']
 
         # Temporary hack. We need another format group, i.e. txt or str
@@ -801,7 +802,7 @@ def cmd_class_find(context, classname_glob, options):
             rows.extend(ns_rows)
 
         context.spinner_stop()
-        if context.output_format in TABLE_FORMATS:
+        if output_format_is_table(context.output_format):
             headers = ['Namespace', 'Classname']
             click.echo(
                 format_table(rows, headers,

pywbemtools/pywbemcli/_cmd_server.py

@@ -30,7 +30,8 @@
 
 from .pywbemcli import cli
 from ._common import format_table, raise_pywbem_error_exception, \
-    validate_output_format, CMD_OPTS_TXT, GENERAL_OPTS_TXT, SUBCMD_HELP_TXT
+    validate_output_format, display_text, output_format_is_table, \
+    CMD_OPTS_TXT, GENERAL_OPTS_TXT, SUBCMD_HELP_TXT, DEFAULT_TABLE_FORMAT
 from ._common_options import add_options, help_option
 from ._click_extensions import PywbemcliGroup, PywbemcliCommand
 
@@ -226,19 +227,23 @@ def cmd_server_namespaces(context, options):
     """
     Display namespaces in the current WBEM server
     """
-    output_format = validate_output_format(context.output_format, 'TABLE')
+    output_format = validate_output_format(
+        context.output_format,
+        ['TABLE', 'TEXT'], default_format=DEFAULT_TABLE_FORMAT)
 
     try:
         namespaces = context.wbem_server.namespaces
         namespaces.sort()
         context.spinner_stop()
+        if output_format_is_table(output_format):
+            # create list for each row
+            rows = [[ns] for ns in namespaces]
 
-        # create list for each row
-        rows = [[ns] for ns in namespaces]
-
-        click.echo(format_table(rows, ['Namespace Name'],
-                                title='Server Namespaces:',
-                                table_format=output_format))
+            click.echo(format_table(rows, ['Namespace Name'],
+                                    title='Server Namespaces:',
+                                    table_format=output_format))
+        else:
+            display_text(", ".join(namespaces))
 
     except Error as er:
         raise click.ClickException('{}: {}'.format(er.__class__.__name__, er))
@@ -248,17 +253,15 @@ def cmd_server_interop(context):
     """
     Display interop namespace in the current WBEM server
     """
-    output_format = validate_output_format(context.output_format, 'TABLE')
+
+    output_format = validate_output_format(context.output_format, 'TEXT')
 
     try:
         interop_ns = context.wbem_server.interop_ns
         context.spinner_stop()
 
-        rows = [[interop_ns]]
+        display_text(interop_ns, output_format)
 
-        click.echo(format_table(rows, ['Namespace Name'],
-                                title='Server Interop Namespace:',
-                                table_format=output_format))
     except Error as er:
         raise_pywbem_error_exception(er)
 
@@ -267,16 +270,14 @@ def cmd_server_brand(context):
     """
     Display product and version info of the current WBEM server
     """
-    output_format = validate_output_format(context.output_format, 'TABLE')
+    output_format = validate_output_format(context.output_format, 'TEXT')
 
     try:
         brand = context.wbem_server.brand
         context.spinner_stop()
 
-        rows = [[brand]]
-        click.echo(format_table(rows, ['WBEM server brand'],
-                                title='Server brand:',
-                                table_format=output_format))
+        display_text(brand, output_format)
+
     except Error as er:
         raise_pywbem_error_exception(er)