API update (#956)

Author: maddenp-cu

docs/sections/user_guide/api/index.rst

@@ -35,4 +35,5 @@ API
    ungrib
    upp
    upp_assets
+   utils
    ww3

docs/sections/user_guide/api/utils.rst

@@ -0,0 +1,5 @@
+``uwtools.api.utils``
+=====================
+
+.. automodule:: uwtools.api.utils
+   :members:

src/uwtools/api/driver.py

@@ -16,6 +16,7 @@
     DriverCycleLeadtimeBased,
     DriverTimeInvariant,
 )
+from uwtools.drivers.stager import FileStager
 
 
 def yaml_keys_to_classes() -> dict[str, type]:
@@ -46,5 +47,6 @@ def yaml_keys_to_classes() -> dict[str, type]:
     "DriverCycleBased",
     "DriverCycleLeadtimeBased",
     "DriverTimeInvariant",
+    "FileStager",
     "yaml_keys_to_classes",
 ]

src/uwtools/api/utils.py

@@ -0,0 +1,7 @@
+"""
+API access to utility functions.
+"""
+
+from uwtools.utils.processing import run_shell_cmd
+
+__all__ = ["run_shell_cmd"]

src/uwtools/drivers/stager.py

@@ -10,7 +10,7 @@
 
 class FileStager:
     """
-    A base class for tasks that stage files.
+    A mixin class providing tasks to stage files.
     """
 
     @collection

src/uwtools/utils/processing.py

@@ -16,28 +16,44 @@
 
 def run_shell_cmd(
     cmd: str | list[str],
+    callback: Callable[[Popen], None] | None = None,
     cwd: Path | str | None = None,
     env: dict[str, str] | None = None,
-    start_new_session: bool = False,
-    callback: Callable[[Popen], None] | None = None,
     executable: str | None = None,
     log_output: bool = False,
     quiet: bool = False,
+    start_new_session: bool = False,
     taskname: str | None = None,
 ) -> tuple[bool, str]:
     """
     Run a command in a shell.
 
     :param cmd: The command to run.
-    :param cwd: Change to this directory before running cmd.
-    :param env: Environment variables to set before running cmd.
+    :param callback: Called with the ``Popen`` process object.
+    :param cwd: Change to this directory before running the command.
+    :param env: Environment variables to set before running the command.
+    :param executable: Interpreter to run command in (e.g. "/bin/bash").
+    :param log_output: Log output from successful command? (Error output is always logged.)
+    :param quiet: Log ``INFO`` messages as ``DEBUG``.
     :param start_new_session: Run process in a new session?
-    :param callback: Optional callable, called with the Popen process object.
-    :param executable: Interpreter to use (e.g. "/bin/bash")
-    :param log_output: Log output from successful cmd? (Error output is always logged.)
-    :param quiet: Log INFO messages as DEBUG.
     :param taskname: Name of task executing this command, for logging.
-    :return: A result object providing combined stder/stdout output and success values.
+    :return: Success indication and combined ``stdout`` / ``stderr``.
+
+    The ``Callable`` specified by the ``callback`` argument will be called once with the ``Popen``
+    object as soon as it is available; i.e. it may be called while the command is running, and does
+    not wait for the command to complete.
+
+    Use ``executable`` to use a shell other than the ``subprocess.Popen`` default, ``/bin/sh``.
+
+    It is assumed that ``uwtools.api.loggin.use_uwtools_logger`` has previously been called to set
+    up logging if ``log_output`` is ``True``.
+
+    The ``start_new_session`` argument is connected directly to the argument of the same name when
+    ``subprocess.Popen`` is called. Among other potential use cases, it prevents the command from
+    receiving a ``SIGINT`` generated by a user Ctrl-C, useful when the command is running in a
+    thread and the main control thread should handle the interrupt.
+
+    If ``taskname`` is provided, log messages will be prefixed with ``[<taskname>]``.
     """
     pre = f"[{taskname}] " if taskname else ""
     logfunc = log.debug if quiet else log.info