Consolidated warnings control

Details:

* Before this change, Python warnings were controlled by the PYTHONWARNINGS
  env var, and the deprecation messages in pywbemcli were controlled by
  the `--deprecation-warnings` / `--no-deprecation-warnings` general options.

  This change consolidates the warnings control such that the deprecation
  messages were changed to be issued as Python warnings, and these options
  were remamed to `--warn` / `--no-warn` and control the display of all
  Python warnings. If `--warn` is used, all Python warnings are shown once.
  If `--no-warn` is used (default), the `PYTHONWARNINGS` environment variable
  determines which warnings are shown. If that variable is not set, no
  warnings are shown.

Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>

docs/changes.rst

@@ -21,6 +21,10 @@ Released: not yet
   "profile centralinsts" added a command group and removed 2 commands
   from the server command group. (See issue #612)
 
+* The `--deprecation-warnings` / `--no-deprecation-warnings` general option
+  has been remamed to `--warn` / `--no-warn`, and it now controls the
+  display of all Python warnings.
+
 **Deprecations:**
 
 **Bug fixes:**
@@ -72,6 +76,13 @@ Released: not yet
   function, and appended to the property name in square brackets.
   (See issue #727)
 
+* Consolidated the warnings control, such that the deprecation messages were
+  changed to be issued as Python warnings, and the `--warn` / `--no-warn`
+  general options now control the display of all Python warnings. If `--warn`
+  is used, all Python warnings are shown once. If `--no-warn` is used (default),
+  the `PYTHONWARNINGS` environment variable determines which warnings are shown.
+  If that variable is not set, no warnings are shown. (See issue #723)
+
 **Cleanup**
 
 * Remove unused NocaseList from __common.py

docs/introduction.rst

@@ -226,7 +226,8 @@ Python warnings of type ``DeprecationWarning`` (see the Python
 
 Since Python 2.7, ``DeprecationWarning`` messages are suppressed by default.
 They can be shown for example by invoking pywbemcli with the environment
-variable: ``PYTHONWARNINGS=default``
+variable: ``PYTHONWARNINGS=default``, or by using the
+ref:`--warn general option`.
 
 It is recommended that users of the pywbemtools package run their test code with
 ``DeprecationWarning`` messages being shown, so they become aware of any use of

docs/pywbemcli/cmdshelp.rst

@@ -114,8 +114,10 @@ Help text for ``pywbemcli``:
                                       [all|paths|summary], default: all. Default: EnvVar PYWBEMCLI_LOG, or all.
 
       -v, --verbose / --no-verbose    Display extra information about the processing.
-      --deprecation-warnings / --no-deprecation-warnings
-                                      Enable deprecation warnings. Default: EnvVar PYWBEMCLI_DEPRECATION_WARNINGS, or true.
+      --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.
+
       -C, --connections-file FILE PATH
                                       Path name of the connections file to be used. Default: EnvVar
                                       PYWBEMCLI_CONNECTIONS_FILE, or ".pywbemcli_connections.yaml" in the user's home

docs/pywbemcli/generaloptions.rst

@@ -198,8 +198,7 @@ Other miscellaneous general options
 The :ref:`--verbose general option` displays extra information about the
 pywbemcli internal processing.
 
-The :ref:`--deprecation-warnings general option` controls the display of
-deprecation warnings.
+The :ref:`--warn general option` controls the display of warnings.
 
 The :ref:`--version general option` displays pywbemcli version
 information and the :ref:`--help general option` provides top level help
@@ -661,21 +660,23 @@ commands in the :ref:`connection command group`.
 In the interactive mode, this option may not be modified after the command
 line is processed.
 
-
 .. index:: triple: --pdb; general options; pdb
 
-.. _`--deprecation-warnings general option`:
+.. _`--warn general option`:
 
-``--deprecation-warnings`` general option
-"""""""""""""""""""""""""""""""""""""""""
+``--warn`` general option
+"""""""""""""""""""""""""
 
-The ``--deprecation-warnings``/``--no-deprecation-warnings`` general option is
-a boolean option that controls the display of deprecation warnings on the
-standard error stream.
+The ``--warn``/``--no-warn`` general option is a boolean option that controls
+the display of all Python warnings.
 
-By default, the display of deprecation warnings is enabled.
+If ``--warn`` is used, all Python warnings are shown once. If ``--no-warn`` is
+used (default), the ``PYTHONWARNINGS`` environment variable determines which
+warnings are shown. If that variable is not set, no warnings are shown. See
+`PYTHONWARNINGS <https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS>`_
+for details.
 
-.. index:: triple: --deprecation-warnings; --no-deprecation-warnings; general options; deprecation warnings
+.. index:: triple: --warn; --no-warn; general options; warnings
 
 .. _`--pdb general option`:
 
@@ -741,7 +742,6 @@ PYWBEMCLI_STATS_ENABLED            ``--timestats``
 PYWBEMCLI_MOCK_SERVER (1)          ``--mock-server``
 PYWBEMCLI_LOG                      ``--log``
 PYWBEMCLI_PDB                      ``--pdb``
-PYWBEMCLI_DEPRECATION_WARNINGS     ``--deprecation-warnings``
 PYWBEMCLI_CONNECTIONS_FILE         ``--connections-file``
 =================================  =============================
 

minimum-constraints.txt

@@ -97,6 +97,7 @@ prompt-toolkit==2.0.1; python_version >= '3.4'
 PyYAML==5.1
 pydicti==1.1.3
 yamlloader==0.5.5
+mock==3.0.0
 
 # Virtualenv
 virtualenv==14.0.0; python_version < '3.5'
@@ -107,7 +108,6 @@ virtualenv==20.0.0; python_version >= '3.8'  # requires six<2,>=1.12.0
 
 # Indirect dependencies from pywbem
 M2Crypto==0.31.0
-mock==2.0.0
 ordereddict==1.1
 ply==3.10
 typing==3.6.1; python_version < '3.5'  # from M2Crypto

pywbemtools/pywbemcli/_cmd_connection.py

@@ -667,7 +667,7 @@ def cmd_connection_select(context, name, options):
                          context.log,
                          context.verbose,
                          context.pdb,
-                         context.deprecation_warnings,
+                         context.warn,
                          context.connections_repo)
 
     # Update the root context making this context the basis for future

pywbemtools/pywbemcli/_context_obj.py

@@ -44,7 +44,7 @@ class ContextObj(object):  # pylint: disable=useless-object-inheritance
     # pylint: disable=unused-argument
     def __init__(self, pywbem_server, output_format, use_pull,
                  pull_max_cnt, timestats, log, verbose, pdb,
-                 deprecation_warnings, connections_repo):
+                 warn, connections_repo):
 
         self._pywbem_server = pywbem_server
         self._output_format = output_format
@@ -54,7 +54,7 @@ def __init__(self, pywbem_server, output_format, use_pull,
         self._log = log
         self._verbose = verbose
         self._pdb = pdb
-        self._deprecation_warnings = deprecation_warnings
+        self._warn = warn
         self._connections_repo = connections_repo
 
         self._spinner_enabled = None  # Deferred init in getter
@@ -117,11 +117,11 @@ def pdb(self):
         return self._pdb
 
     @property
-    def deprecation_warnings(self):
+    def warn(self):
         """
-        bool: Indicates whether to enable deprecation warnings.
+        bool: Indicates whether to enable Python warnings.
         """
-        return self._deprecation_warnings
+        return self._warn
 
     @property
     def connections_repo(self):

pywbemtools/pywbemcli/_pywbem_server.py

@@ -117,7 +117,6 @@ class PywbemServer(object):
     log_envvar = 'PYWBEMCLI_LOG'
     # The following exports are not part of the pywbem_server container
     pdb_envvar = 'PYWBEMCLI_PDB'
-    deprecation_warnings_envvar = 'PYWBEMCLI_DEPRECATION_WARNINGS'
     termwidth_envvar = 'PYWBEMCLI_TERMWIDTH'
     connections_file_envvar = 'PYWBEMCLI_CONNECTIONS_FILE'
 

pywbemtools/pywbemcli/_utils.py

@@ -20,7 +20,6 @@
 from __future__ import print_function, absolute_import
 
 import six
-import click
 
 
 __all__ = []
@@ -70,10 +69,9 @@ def _eq_name(name1, name2):
     return name1.lower() == name2.lower()
 
 
-def deprecation_warning(msg, ctx_obj):
+def formatwarning(message, category, filename, lineno, line=None):
+    # pylint: disable=unused-argument
     """
-    Display a deprecation warning on stderr, unless disabled via
-    ctx_obj.deprecation_warnings.
+    Replacement for warnings.formatwarning() that is patched in.
     """
-    if ctx_obj.deprecation_warnings:
-        click.echo(msg, err=True)
+    return "{}: {}\n".format(category.__name__, message)

pywbemtools/pywbemcli/pywbemcli.py

@@ -24,6 +24,8 @@
 import sys
 import traceback
 from copy import deepcopy
+import warnings
+from mock import patch
 import click
 import click_repl
 from prompt_toolkit.history import FileHistory
@@ -44,7 +46,8 @@
 from ._connection_repository import ConnectionRepository, \
     CONNECTIONS_FILENAME, DEFAULT_CONNECTIONS_FILE
 from ._click_extensions import PywbemcliTopGroup
-from ._utils import deprecation_warning
+from ._utils import formatwarning
+
 
 __all__ = ['cli']
 
@@ -251,12 +254,12 @@ def validate_connections_file(connections_repo):
 @click.option('-v', '--verbose/--no-verbose',
               default=None,
               help=u'Display extra information about the processing.')
-@click.option('--deprecation-warnings/--no-deprecation-warnings', is_flag=True,
-              default=True,
-              envvar=PywbemServer.deprecation_warnings_envvar,
-              help=u'Enable deprecation warnings. '
-              'Default: EnvVar {ev}, or true.'.
-              format(ev=PywbemServer.deprecation_warnings_envvar))
+@click.option('--warn/--no-warn', is_flag=True,
+              default=False,
+              help=u'Warnings control: True enables display of all Python '
+              u'warnings; False leaves warning control to the PYHONWARNINGS '
+              u'env var, which by default displays no warnings. '
+              u'Default: False.')
 @click.option('-C', '--connections-file', metavar='FILE PATH',
               envvar=PywbemServer.connections_file_envvar,
               # Keep help text in sync with connections file definitions in
@@ -281,10 +284,11 @@ def validate_connections_file(connections_repo):
     help=u'Show the version of this command and the pywbem package.')
 @add_options(help_option)
 @click.pass_context
+@patch('warnings.formatwarning', formatwarning)
 def cli(ctx, server, connection_name, default_namespace, user, password,
         timeout, verify, certfile, keyfile, ca_certs, output_format, use_pull,
         pull_max_cnt, mock_server, verbose=None, connections_file=None,
-        timestats=None, log=None, pdb=None, deprecation_warnings=None):
+        timestats=None, log=None, pdb=None, warn=None):
     """
     Pywbemcli is a command line WBEM client that uses the DMTF CIM-XML protocol
     to communicate with WBEM servers. Pywbemcli can:
@@ -424,6 +428,11 @@ def create_server_instance(connection_name):
     # options with any defaults applied for non None options.
     # Produces new variables resolved... so that later tests can confirm that
     # original variables were None or not None
+
+    if warn:
+        warnings.simplefilter('once')
+    # else: Leave warning control to the PYTHONWARNINGS env var.
+
     pywbem_server = None
     resolved_default_namespace = default_namespace or DEFAULT_NAMESPACE
     resolved_timestats = timestats or DEFAULT_TIMESTATS
@@ -636,8 +645,8 @@ def create_server_instance(connection_name):
             connections_repo = ctx.obj.connections_repo
         if pdb is None:
             pdb = ctx.obj.pdb
-        if deprecation_warnings is None:
-            deprecation_warnings = ctx.obj.deprecation_warnings
+        if warn is None:
+            warn = ctx.obj.warn
 
     # Create a command context for each command: An interactive command has
     # its own command context as a child of the command context for the
@@ -649,7 +658,7 @@ def create_server_instance(connection_name):
                          resolved_pull_max_cnt or DEFAULT_MAXPULLCNT,
                          resolved_timestats,
                          log, verbose, pdb,
-                         deprecation_warnings,
+                         warn,
                          connections_repo)
     if verbose and os.getenv('PYWBEMCLI_DIAGNOSTICS'):
         print('CONTEXT_OBJ {!r}'.format(ctx.obj))
@@ -659,10 +668,11 @@ def create_server_instance(connection_name):
 
     _python_nm = sys.version_info[0:2]
     if _python_nm in ((2, 7), (3, 4)):
-        deprecation_warning(
-            "Deprecation: Pywbemcli support for Python {}.{} is deprecated "
-            "and will be removed in a future version".
-            format(_python_nm[0], _python_nm[1]), ctx.obj)
+        warnings.warn(
+            "Pywbemcli support for Python {}.{} is deprecated and will be "
+            "removed in a future version".
+            format(_python_nm[0], _python_nm[1]),
+            DeprecationWarning)
 
     # Invoke command if one exists.
     if ctx.invoked_subcommand is None:

requirements.txt

@@ -39,3 +39,4 @@ PyYAML>=5.1; python_version > '3.4'
 
 yamlloader>=0.5.5
 packaging>=17.0
+mock>=3.0.0

tests/unit/test_context_obj.py

@@ -47,7 +47,7 @@ def simple_test(self):
         log = 'all'
         verbose = True
         pdb = False
-        deprecation_warnings = False
+        warn = False
         connections_repo = None
 
         ctxobj = ContextObj(
@@ -59,7 +59,7 @@ def simple_test(self):
             log=log,
             verbose=verbose,
             pdb=pdb,
-            deprecation_warnings=deprecation_warnings,
+            warn=warn,
             connections_repo=connections_repo)
 
         self.assertEqual(ctxobj.pywbem_server, svr)

tests/unit/test_general_options.py

@@ -97,7 +97,7 @@
     "-C, --connections-file FILE PATH Path name of the connections file",
     CONNECTIONS_FILENAME,
     "-v, --verbose / --no-verbose Display extra information about the",
-    "--deprecation-warnings / --no-deprecation-warnings",
+    "--warn / --no-warn",
     "--pdb    Pause execution in the built-in pdb debugger",
     "--version   Show the version of this command and the",
     """Commands:
@@ -313,8 +313,8 @@ class       Command group for CIM classes.
       'test': 'innows'},
      None, OK],  # Only tests that the option is accepted
 
-    ['Verify --no-deprecation-warnings general option.',
-     {'general': ['-s', 'http://blah', '--no-deprecation-warnings'],
+    ['Verify --no-warn general option.',
+     {'general': ['-s', 'http://blah', '--no-warn'],
       'cmdgrp': 'connection',
       'args': ['show']},
      {'stdout': [''],
@@ -323,8 +323,8 @@ class       Command group for CIM classes.
      None, OK],  # Only tests that the option is accepted
 
 
-    ['Verify --deprecation-warnings general option.',
-     {'general': ['-s', 'http://blah', '--deprecation-warnings'],
+    ['Verify --warn general option.',
+     {'general': ['-s', 'http://blah', '--warn'],
       'cmdgrp': 'connection',
       'args': ['show']},
      {'stdout': [''],

tools/click_help_capture.py

@@ -133,7 +133,7 @@ def get_subcmd_group_names(script_cmd, script_name, cmd):
 
     returns list of command groups/commands
     """
-    command = '{} --no-deprecation-warnings {} --help'.format(script_cmd, cmd)
+    command = '{} --no-warn {} --help'.format(script_cmd, cmd)
     # Disable python warnings for script call.
     if sys.platform != 'win32':
         command = 'export PYTHONWARNINGS="" && {}'.format(command)