X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=google_assistant.py;h=6b480ef367d4fab5eda046bbbb77cface814b7e3;hb=02302bbd9363facb59c4df2c1f4013087702cfa6;hp=b767df75f4a56f4b4ec84be3abedd16b2e8a591b;hpb=532df2c5b57c7517dfb3dddd8c1358fbadf8baf3;p=python_utils.git

diff --git a/google_assistant.py b/google_assistant.py
index b767df7..6b480ef 100644
--- a/google_assistant.py
+++ b/google_assistant.py
@@ -4,7 +4,6 @@
 
 """A module to serve as a local client library around HTTP calls to
 the Google Assistant via a local gateway.
-
 """
 
 import logging
@@ -41,12 +40,20 @@ parser.add_argument(
 
 @dataclass
 class GoogleResponse:
-    """A response wrapper."""
+    """A Google response wrapper dataclass."""
 
     success: bool = False
+    """Did the request succeed (True) or fail (False)?"""
+
     response: str = ''
+    """The response as a text string, if available."""
+
     audio_url: str = ''
-    audio_transcription: Optional[str] = None  # None if not available.
+    """A URL that can be used to fetch the raw audio response."""
+
+    audio_transcription: Optional[str] = None
+    """A transcription of the audio response, if available.  Otherwise
+    None"""
 
     def __repr__(self):
         return f"""
@@ -62,10 +69,18 @@ def tell_google(cmd: str, *, recognize_speech=True) -> GoogleResponse:
 
 
 def ask_google(cmd: str, *, recognize_speech=True) -> GoogleResponse:
-    """Send a command string to Google via the google_assistant_bridge as the
-    user google_assistant_username and return the response.  If recognize_speech
-    is True, perform speech recognition on the audio response from Google so as
-    to translate it into text (best effort, YMMV).
+    """Send a command string to Google via the google_assistant_bridge as
+    the user google_assistant_username and return the response.  If
+    recognize_speech is True, perform speech recognition on the audio
+    response from Google so as to translate it into text (best effort,
+    YMMV).  e.g.::
+
+        >>> google_assistant.ask_google('What time is it?')
+        success: True
+        response: 9:27 PM.
+        audio_transcription: 9:27 p.m.
+        audio_url: http://kiosk.house:3000/server/audio?v=1653971233030
+
     """
     logging.debug("Asking google: '%s'", cmd)
     payload = {