From d4746c5acfed3fee5a0e55ae1aea644fa23b28c8 Mon Sep 17 00:00:00 2001
From: Greg Dubicki <grzegorz.dubicki@gmail.com>
Date: Fri, 4 Nov 2022 22:26:52 +0000
Subject: [PATCH] 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).
---
 cli_ui/__init__.py | 18 +++++++++++++++---
 docs/index.rst     |  9 ++++++++-
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/cli_ui/__init__.py b/cli_ui/__init__.py
index 8c517af..d695aed 100644
--- a/cli_ui/__init__.py
+++ b/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)
 
diff --git a/docs/index.rst b/docs/index.rst
index f3d29c5..7e4140d 100644
--- a/docs/index.rst
+++ b/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
 
     ::