Breaking: add verbose(), controlled with verbose

in `setup()` and make `debug()` controlled with `debug` in setup.

This will allow writing apps that have more granular level
of verbosity:
* quiet (warning-fatal)
* normal (info-fatal),
* verbose (verbose-fatal),
* debug (debug-fatal = all).

Author: gdubicki

cli_ui/__init__.py

@@ -23,6 +23,7 @@
 # Global variable to store configuration
 
 CONFIG = {
+    "debug": os.environ.get("DEBUG"),
     "verbose": os.environ.get("VERBOSE"),
     "quiet": False,
     "color": "auto",
@@ -54,6 +55,7 @@
 
 def setup(
     *,
+    debug: bool = False,
     verbose: bool = False,
     quiet: bool = False,
     color: str = "auto",
@@ -62,7 +64,8 @@ def setup(
 ) -> None:
     """Configure behavior of message functions.
 
-    :param verbose: Whether :func:`debug` messages should get printed
+    :param debug: Whether :func:`debug` messages should get printed
+    :param verbose: Whether :func:`verbose` messages should get printed
     :param quiet: Hide every message except :func:`warning`, :func:`error`, and
                   :func:`fatal`
     :param color: Choices: 'auto', 'always', or 'never'. Whether to color output.
@@ -361,12 +364,21 @@ def info_progress(prefix: str, value: float, max_value: float) -> None:
         write_and_flush(sys.stdout, to_write)
 
 
+def verbose(*tokens: Token, **kwargs: Any) -> None:
+    """Print a verbose message.
+
+    Messages are shown only when ``CONFIG["verbose"]`` is true"""
+    if not CONFIG["verbose"]:
+        return
+    message(*tokens, **kwargs)
+
+
 def debug(*tokens: Token, **kwargs: Any) -> None:
     """Print a debug message.
 
-    Messages are shown only when ``CONFIG["verbose"]`` is true
+    Messages are shown only when ``CONFIG["debug"]`` is true
     """
-    if not CONFIG["verbose"] or CONFIG["record"]:
+    if not CONFIG["debug"] or CONFIG["record"]:
         return
     message(*tokens, **kwargs)
 

docs/index.rst

@@ -42,7 +42,7 @@ Configuration
 
   >>> cli_ui.debug("this will not be printed")
   <nothing>
-  >>> cli_ui.setup(verbose=True)
+  >>> cli_ui.setup(debug=True)
   >>> cli_ui.debug("this will be printed")
   this will be printed
 
@@ -161,6 +161,13 @@ Functions below take the same arguments as the :func:`info` function
       >>> cli_ui.info_3("Message")
       * Message
 
+.. autofunction:: verbose
+
+    ::
+
+      >>> cli_ui.verbose("Message")
+      <nothing>
+
 .. autofunction:: debug
 
     ::