Add pooch cache manager verbosity control

src/geovista/cache.py

@@ -24,6 +24,7 @@
     "fetch_coastlines",
     "natural_earth_1",
     "natural_earth_hypsometric",
+    "pooch_mute",
     "reload_registry",
 ]
 
@@ -68,8 +69,10 @@
     (files(__package__) / "registry.txt").open("r", encoding="utf-8", errors="strict")
 )
 
-if os.environ.get("GEOVISTA_POOCH_MUTE"):
-    pooch.utils.get_logger().setLevel("WARNING")
+#: Verbosity status of the pooch cache manager logger.
+GEOVISTA_POOCH_MUTE: bool = (
+    os.environ.get("GEOVISTA_POOCH_MUTE", "false").lower() == "true"
+)
 
 
 def _fetch_texture(fname: str, location: bool | None = False) -> TextureLike:
@@ -244,6 +247,29 @@ def natural_earth_hypsometric(location: bool | None = False) -> TextureLike:
     return _fetch_texture("HYP_50M_SR_W.jpg", location=location)
 
 
+def pooch_mute(silent: bool = True) -> None:
+    """Control the pooch cache manager logger verbosity.
+
+    Updates the status variable :data:`GEOVISTA_POOCH_MUTE`.
+
+    Parameters
+    ----------
+    silent : bool, optional
+        Whether to silence or activate the pooch cache manager logger messages to the
+        console.
+
+    Notes
+    -----
+    .. versionadded:: 0.5.0
+
+    """
+    global GEOVISTA_POOCH_MUTE
+
+    level = "WARNING" if silent else "NOTSET"
+    pooch.utils.get_logger().setLevel(level)
+    GEOVISTA_POOCH_MUTE = silent
+
+
 def reload_registry(fname: str | None = None) -> None:
     """Refresh the registry of the :data:`CACHE`.
 
@@ -263,3 +289,7 @@ def reload_registry(fname: str | None = None) -> None:
             "r", encoding="utf-8", errors="strict"
         )
     CACHE.load_registry(fname)
+
+
+# configure the pooch cache manager logger verbosity
+pooch_mute(GEOVISTA_POOCH_MUTE)

src/geovista/cli.py

@@ -14,13 +14,12 @@
 
 import click
 from click_default_group import DefaultGroup
-import pooch
 import pyvista as pv
 
 from . import examples as scripts
 from . import logger
 from ._version import version as __version__
-from .cache import CACHE
+from .cache import CACHE, GEOVISTA_POOCH_MUTE, pooch_mute
 from .config import resources
 from .geoplotter import GeoPlotter
 from .report import Report
@@ -41,8 +40,6 @@
     submodule.name for submodule in pkgutil.iter_modules(scripts.__path__)
 ]
 
-pooch_logger = pooch.get_logger()
-
 
 def _download_group(
     fnames: list[str],
@@ -79,7 +76,8 @@ def _download_group(
     n_fnames: int = len(fnames)
     width: int = len(str(n_fnames))
 
-    pooch_logger.setLevel("ERROR")
+    status = GEOVISTA_POOCH_MUTE
+    pooch_mute(True)
 
     click.echo(f"Downloading {n_fnames} {name}registered asset{_plural(n_fnames)}:")
     for i, fname in enumerate(fnames):
@@ -94,7 +92,7 @@ def _download_group(
         click.secho(f"{CACHE.abspath}", fg=fg_colour)
         click.echo("👍 All done!")
 
-    pooch_logger.setLevel("INFO")
+    pooch_mute(status)
 
 
 def _plural(quantity: int) -> str:

tests/cache/__init__.py

@@ -0,0 +1 @@
+"""Unit-tests for :mod:`geovista.cache`."""

tests/cache/test_pooch_mute.py

@@ -0,0 +1,32 @@
+"""Unit-tests for :func:`geovista.cache.pooch_mute`."""
+from __future__ import annotations
+
+from pooch import get_logger
+
+from geovista.cache import pooch_mute
+
+
+def test():
+    """Test all behaviours as one atomic test."""
+    logger = get_logger()
+
+    # default silent kwarg
+    pooch_mute()
+    assert logger.getEffectiveLevel() == 30
+    from geovista.cache import GEOVISTA_POOCH_MUTE
+
+    assert GEOVISTA_POOCH_MUTE is True
+
+    # explicit verbose
+    pooch_mute(silent=False)
+    assert logger.getEffectiveLevel() == 0
+    from geovista.cache import GEOVISTA_POOCH_MUTE
+
+    assert GEOVISTA_POOCH_MUTE is False
+
+    # explicit silence
+    pooch_mute(silent=True)
+    assert logger.getEffectiveLevel() == 30
+    from geovista.cache import GEOVISTA_POOCH_MUTE
+
+    assert GEOVISTA_POOCH_MUTE is True