Adds warning filtering to stderr (#387)

* Adds a new context manager that prints QIIME2Warnings to stderr instead of to the log

* Chaining context managers cleanly

* QIIME2Warning -> RachisWarning, don't show if --quiet

* Switching to RachisWarning

* RachisWarning visibility test

* merge conflicts

* move import

---------

Co-authored-by: Colin Wood <woodcolin38@gmail.com>

Author: Macabe222

q2cli/commands.py

@@ -405,13 +405,16 @@ def __call__(self, **kwargs):
         """Called when user hits return, **kwargs are Dict[click_names, Obj]"""
         import os
         import click
+        from contextlib import nullcontext
 
         import qiime2.util
         from qiime2.core.cache import Cache
         from qiime2.sdk import ResultCollection
 
-        from q2cli.util import (output_in_cache, _get_cache_path_and_key,
-                                get_default_recycle_pool)
+        from q2cli.util import (
+            output_in_cache, _get_cache_path_and_key, get_default_recycle_pool,
+            capture_rachis_warnings
+        )
         from q2cli.core.artifact_cache_global import (
             get_used_artifact_cache, unset_used_artifact_cache)
 
@@ -547,7 +550,10 @@ def __call__(self, **kwargs):
 
         cleanup_logfile = False
         try:
-            with qiime2.util.redirected_stdio(stdout=log, stderr=log):
+            with (
+                capture_rachis_warnings() if not quiet else nullcontext(),
+                qiime2.util.redirected_stdio(stdout=log, stderr=log)
+            ):
                 if parallel:
                     from qiime2.sdk.parallel_config import \
                         (load_config_from_file, ParallelConfig)
@@ -557,7 +563,7 @@ def __call__(self, **kwargs):
                         parallel_config = ParallelConfig()
                     else:
                         config, mapping = \
-                              load_config_from_file(parallel_config_fp)
+                            load_config_from_file(parallel_config_fp)
                         parallel_config = ParallelConfig(config, mapping)
 
                     with parallel_config:

q2cli/tests/test_cli.py

@@ -6,14 +6,16 @@
 # The full license is in the file LICENSE, distributed with this software.
 # ----------------------------------------------------------------------------
 
+import click
+import contextlib
+import errno
 import os.path
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
 import unittest
-import contextlib
 import unittest.mock
-import tempfile
-import shutil
-import click
-import errno
 
 from click.testing import CliRunner
 from qiime2.core.cache import get_cache
@@ -484,6 +486,36 @@ def test_get_citations(self):
         self.assertEqual(result.exit_code, 0)
         self.assertEqual(result.output, EXPECTED_CITATIONS)
 
+    def test_rachis_warning_is_always_visible(self):
+        '''
+        Tests that the `RachisWarning` warning type gets passed to the standard
+        error stream even when --verbose is not set. Also ensures that such
+        errors are still visible with --verbose, and not visible with --quiet.
+        '''
+        with tempfile.TemporaryDirectory() as tempdir:
+            base_command = [
+                'qiime', 'dummy-plugin', 'raises-rachis-warning', '--o-output',
+                Path(tempdir) / 'output.qza'
+            ]
+
+            # no verbose, no quiet
+            output = subprocess.run(
+                base_command, capture_output=True, text=True
+            )
+            self.assertIn('This is an important warning', output.stderr)
+
+            # verbose
+            output = subprocess.run(
+                base_command + ['--verbose'], capture_output=True, text=True
+            )
+            self.assertIn('This is an important warning', output.stderr)
+
+            # quiet
+            output = subprocess.run(
+                base_command + ['--quiet'], capture_output=True, text=True
+            )
+            self.assertNotIn('This is an important warning', output.stderr)
+
 
 class TestMigrated(unittest.TestCase):
     def setUp(self):

q2cli/util.py

@@ -6,6 +6,8 @@
 # The full license is in the file LICENSE, distributed with this software.
 # ----------------------------------------------------------------------------
 
+import contextlib
+
 
 class OutOfDisk(Exception):
     pass
@@ -531,3 +533,45 @@ def get_default_recycle_pool(plugin_action):
 
     return f'recycle_{plugin_action}_' \
            f'{sha1(plugin_action.encode("utf-8")).hexdigest()}'
+
+
+@contextlib.contextmanager
+def capture_rachis_warnings():
+    '''
+    Intercepts `RachisWarning` warnings and delays writing them to standard
+    error until the context is exited. This is useful if the standard error
+    stream is temporarily redirected at some point within this context manager.
+    '''
+    import sys
+    import warnings
+    from qiime2.core.exceptions import RachisWarning
+
+    captured_warnings = []
+
+    warnings_showwarning = warnings.showwarning
+
+    def _capture_showwarning(
+        message, category, filename, lineno, file=None, line=None
+    ):
+        if issubclass(category, RachisWarning):
+            captured_warnings.append((str(message), filename, lineno))
+        else:
+            warnings_showwarning(
+                message, category, filename, lineno, file, line
+            )
+
+    warnings.showwarning = _capture_showwarning
+
+    yield
+
+    if captured_warnings:
+        sys.stderr.write('\033[33m')  # yellow text
+        sys.stderr.write('\nRACHIS WARNING(S):\n\n')
+        for warning, file, line in captured_warnings:
+            sys.stderr.write(f'{warning}\n')
+            sys.stderr.write(f'[{file}: {line}]\n\n')
+
+        sys.stderr.write('\033[0m')  # reset text color
+        sys.stderr.flush()
+
+    warnings.showwarning = warnings_showwarning