X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=input_utils.py;fp=input_utils.py;h=0b32eea6f55c5d2fe01466bda0d21ae04c7b13f3;hb=02302bbd9363facb59c4df2c1f4013087702cfa6;hp=d958db23691f910acd84b9f2ee33473ff4bee96a;hpb=f3dbc7dc19ba5703f8f5aa9bf8af3c491b3510f6;p=python_utils.git

diff --git a/input_utils.py b/input_utils.py
index d958db2..0b32eea 100644
--- a/input_utils.py
+++ b/input_utils.py
@@ -23,7 +23,23 @@ def single_keystroke_response(
     default_response: str = None,
     timeout_seconds: int = None,
 ) -> Optional[str]:  # None if timeout w/o keystroke
-    """Get a single keystroke response to a prompt."""
+    """Get a single keystroke response to a prompt and returns it.
+
+    Args:
+        valid_responses: a list of strings that are considered to be
+            valid keystrokes to be accepted.  If None, we accept
+            anything.
+        prompt: the prompt to print before watching keystrokes.  If
+            None, skip this.
+        default_response: the response to return if the timeout
+            expires.  If None, skip this.
+        timeout_seconds: number of seconds to wait before timing out
+            and returning the default_response.  If None, wait forever.
+
+    Returns:
+        The keystroke the user pressed.  If the user pressed a special
+        keystroke like ^C or ^Z, we raise a KeyboardInterrupt exception.
+    """
 
     def _handle_timeout(signum, frame) -> None:
         raise exceptions.TimeoutError()
@@ -67,8 +83,18 @@ def single_keystroke_response(
 
 
 def yn_response(prompt: str = None, *, timeout_seconds=None) -> Optional[str]:
-    """Get a Y/N response to a prompt."""
-
+    """Get a Y/N response to a prompt.
+
+    Args:
+        prompt: the user prompt or None to skip this
+        timeout_seconds: the number of seconds to wait for a response or
+            None to wait forever.
+
+    Returns:
+        A lower case 'y' or 'n'.  Or None if the timeout expires with
+        no input from the user.  Or raises a KeyboardInterrupt if the
+        user pressed a special key such as ^C or ^Z.
+    """
     yn = single_keystroke_response(
         ["y", "n", "Y", "N"], prompt=prompt, timeout_seconds=timeout_seconds
     )
@@ -86,6 +112,9 @@ def press_any_key(
 
 
 def up_down_enter() -> Optional[str]:
+    """Respond to UP, DOWN or ENTER events for simple menus without
+    the need for curses."""
+
     os_special_keystrokes = [3, 26]  # ^C, ^Z
     while True:
         key = readchar.readkey()