From 02302bbd9363facb59c4df2c1f4013087702cfa6 Mon Sep 17 00:00:00 2001
From: Scott Gasch <scott@gasch.org>
Date: Tue, 31 May 2022 15:36:40 -0700
Subject: Improve docstrings for sphinx.

---
 exec_utils.py | 81 +++++++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 65 insertions(+), 16 deletions(-)

(limited to 'exec_utils.py')

diff --git a/exec_utils.py b/exec_utils.py
index ae406ef..7f23ecd 100644
--- a/exec_utils.py
+++ b/exec_utils.py
@@ -19,11 +19,23 @@ logger = logging.getLogger(__file__)
 def cmd_showing_output(
     command: str,
 ) -> int:
-    """Kick off a child process.  Capture and print all output that it
-    produces on stdout and stderr.  Wait for the subprocess to exit
-    and return the exit value as the return code of this function.
+    """Kick off a child process.  Capture and emit all output that it
+    produces on stdout and stderr in a character by character manner
+    so that we don't have to wait on newlines.  This was done to
+    capture the output of a subprocess that created dots to show
+    incremental progress on a task and render it correctly.
 
+    Args:
+        command: the command to execute
+
+    Returns:
+        the exit status of the subprocess once the subprocess has
+        exited
+
+    Side effects:
+        prints all output of the child process (stdout or stderr)
     """
+
     line_enders = set([b'\n', b'\r'])
     sel = selectors.DefaultSelector()
     with subprocess.Popen(
@@ -48,12 +60,10 @@ def cmd_showing_output(
                         sel.close()
                         done = True
                 if key.fileobj is p.stdout:
-                    # sys.stdout.buffer.write(char)
                     os.write(sys.stdout.fileno(), char)
                     if char in line_enders:
                         sys.stdout.flush()
                 else:
-                    # sys.stderr.buffer.write(char)
                     os.write(sys.stderr.fileno(), char)
                     if char in line_enders:
                         sys.stderr.flush()
@@ -61,36 +71,53 @@ def cmd_showing_output(
         return p.returncode
 
 
-def cmd_with_timeout(command: str, timeout_seconds: Optional[float]) -> int:
-    """Run a command but do not let it run for more than timeout seconds.
-    Doesn't capture or rebroadcast command output.  Function returns
-    the exit value of the command or raises a TimeoutExpired exception
-    if the deadline is exceeded.
+def cmd_with_timeout(command: str, timeout_seconds: Optional[float] = None) -> int:
+    """Run a command but do not let it run for more than timeout_seconds.
+    This code doesn't capture or rebroadcast the command's output.  It
+    returns the exit value of the command or raises a TimeoutExpired
+    exception if the deadline is exceeded.
+
+    Args:
+        command: the command to run
+        timeout_seconds: the max number of seconds to allow the subprocess
+            to execute or None to indicate no timeout
+
+    Returns:
+        the exit status of the subprocess once the subprocess has
+        exited
 
     >>> cmd_with_timeout('/bin/echo foo', 10.0)
     0
 
-    >>> cmd_with_timeout('/bin/sleep 2', 0.1)
+    >>> cmd_with_timeout('/bin/sleep 2', 0.01)
     Traceback (most recent call last):
     ...
-    subprocess.TimeoutExpired: Command '['/bin/bash', '-c', '/bin/sleep 2']' timed out after 0.1 seconds
+    subprocess.TimeoutExpired: Command '['/bin/bash', '-c', '/bin/sleep 2']' timed out after 0.01 seconds
 
     """
     return subprocess.check_call(["/bin/bash", "-c", command], timeout=timeout_seconds)
 
 
 def cmd(command: str, timeout_seconds: Optional[float] = None) -> str:
-    """Run a command and capture its output to stdout (only) in a string.
-    Return that string as this function's output.  Raises
+    """Run a command and capture its output to stdout (only) into a string
+    buffer.  Return that string as this function's output.  Raises
     subprocess.CalledProcessError or TimeoutExpired on error.
 
+    Args:
+        command: the command to run
+        timeout_seconds: the max number of seconds to allow the subprocess
+            to execute or None to indicate no timeout
+
+    Returns:
+        The captured output of the subprocess' stdout as a string buffer
+
     >>> cmd('/bin/echo foo')[:-1]
     'foo'
 
-    >>> cmd('/bin/sleep 2', 0.1)
+    >>> cmd('/bin/sleep 2', 0.01)
     Traceback (most recent call last):
     ...
-    subprocess.TimeoutExpired: Command '/bin/sleep 2' timed out after 0.1 seconds
+    subprocess.TimeoutExpired: Command '/bin/sleep 2' timed out after 0.01 seconds
 
     """
     ret = subprocess.run(
@@ -107,6 +134,15 @@ def run_silently(command: str, timeout_seconds: Optional[float] = None) -> None:
     """Run a command silently but raise subprocess.CalledProcessError if
     it fails.
 
+    Args:
+        command: the command to run
+        timeout_seconds: the max number of seconds to allow the subprocess
+            to execute or None to indicate no timeout
+
+    Returns:
+        No return value; error conditions (including non-zero child process
+        exits) produce exceptions.
+
     >>> run_silently("/usr/bin/true")
 
     >>> run_silently("/usr/bin/false")
@@ -127,6 +163,19 @@ def run_silently(command: str, timeout_seconds: Optional[float] = None) -> None:
 
 
 def cmd_in_background(command: str, *, silent: bool = False) -> subprocess.Popen:
+    """Spawns a child process in the background and registers an exit
+    handler to make sure we kill it if the parent process (us) is
+    terminated.
+
+    Args:
+        command: the command to run
+        silent: do not allow any output from the child process to be displayed
+            in the parent process' window
+
+    Returns:
+        the :class:`Popen` object that can be used to communicate
+            with the background process.
+    """
     args = shlex.split(command)
     if silent:
         subproc = subprocess.Popen(
-- 
cgit v1.3