Merge pull request #209 from dvonthenen/fix-readme-fill-out-pydocs

Updates to README, examples, and More PyDocs

Author: davidvonthenen

README.md

@@ -4,6 +4,9 @@
 
 import logging, verboselogs
 
+"""
+constants for microphone
+"""
 LOGGING = logging.WARNING
 CHANNELS = 1
 RATE = 16000

deepgram/audio/microphone/constants.py

@@ -2,17 +2,14 @@
 # Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 # SPDX-License-Identifier: MIT
 
-
+# exceptions for microphone
 class DeepgramMicrophoneError(Exception):
     """
     Exception raised for known errors related to Microphone library.
 
     Attributes:
         message (str): The error message describing the exception.
-        status (str): The HTTP status associated with the API error.
-        original_error (str - json): The original error that was raised.
     """
-
     def __init__(self, message: str):
         super().__init__(message)
         self.name = "DeepgramMicrophoneError"

deepgram/audio/microphone/errors.py

@@ -11,7 +11,6 @@
 from .errors import DeepgramMicrophoneError
 from .constants import LOGGING, CHANNELS, RATE, CHUNK
 
-
 class Microphone:
     """
     This implements a microphone for local audio input. This uses PyAudio under the hood.
@@ -25,6 +24,7 @@ def __init__(
         chunk=CHUNK,
         channels=CHANNELS,
     ):
+        # dynamic import of pyaudio as not to force the requirements on the SDK (and users)
         import pyaudio
 
         self.logger = logging.getLogger(__name__)
@@ -40,6 +40,9 @@ def __init__(
         self.stream = None
 
     def is_active(self):
+        """
+        returns True if the stream is active, False otherwise
+        """
         self.logger.debug("Microphone.is_active ENTER")
         if self.stream is None:
             self.logger.error("stream is None")
@@ -52,6 +55,9 @@ def is_active(self):
         return
 
     def start(self):
+        """
+        starts the microphone stream
+        """
         self.logger.debug("Microphone.start ENTER")
 
         if self.stream is not None:
@@ -76,14 +82,17 @@ def start(self):
         self.lock = threading.Lock()
 
         self.stream.start_stream()
-        self.thread = threading.Thread(target=self.processing)
+        self.thread = threading.Thread(target=self._processing)
         self.thread.start()
 
         self.logger.notice("start succeeded")
         self.logger.debug("Microphone.start LEAVE")
 
-    def processing(self):
-        self.logger.debug("Microphone.processing ENTER")
+    def _processing(self):
+        """
+        the main processing loop for the microphone
+        """
+        self.logger.debug("Microphone._processing ENTER")
 
         try:
             while True:
@@ -106,15 +115,18 @@ def processing(self):
                     self.logger.verbose("regular threaded callback")
                     self.push_callback(data)
 
-            self.logger.notice("processing exiting...")
-            self.logger.debug("Microphone.processing LEAVE")
+            self.logger.notice("_processing exiting...")
+            self.logger.debug("Microphone._processing LEAVE")
 
         except Exception as e:
             self.logger.error("Error while sending: %s", str(e))
-            self.logger.debug("Microphone.processing LEAVE")
+            self.logger.debug("Microphone._processing LEAVE")
             raise
 
     def finish(self):
+        """
+        Stops the microphone stream
+        """
         self.logger.debug("Microphone.finish ENTER")
 
         self.lock.acquire()
@@ -125,7 +137,7 @@ def finish(self):
         if self.thread is not None:
             self.thread.join()
             self.thread = None
-        self.logger.notice("processing/send thread joined")
+        self.logger.notice("_processing/send thread joined")
 
         if self.stream is not None:
             self.stream.stop_stream()

deepgram/audio/microphone/microphone.py

@@ -39,8 +39,12 @@ class DeepgramClient:
 
     Methods:
         listen: Returns a ListenClient instance for interacting with Deepgram's transcription services.
-        manage: Returns a ManageClient instance for managing Deepgram resources.
-        onprem: Returns an OnPremClient instance for interacting with Deepgram's on-premises API.
+
+        manage: (Preferred) Returns a Threaded ManageClient instance for managing Deepgram resources.
+        onprem: (Preferred) Returns an Threaded OnPremClient instance for interacting with Deepgram's on-premises API.
+
+        asyncmanage: Returns an (Async) ManageClient instance for managing Deepgram resources.
+        asynconprem: Returns an (Async) OnPremClient instance for interacting with Deepgram's on-premises API.
     """
 
     def __init__(

deepgram/client.py

@@ -21,11 +21,6 @@ class AbstractAsyncRestClient:
         url (Dict[str, str]): The base URL for the RESTful API, including any path segments.
         headers (Optional[Dict[str, Any]]): Optional HTTP headers to include in requests.
 
-    Attributes:
-        url (Dict[str, str]): The base URL for the RESTful API.
-        client (httpx.AsyncClient): An asynchronous HTTP client for making requests.
-        headers (Optional[Dict[str, Any]]): Optional HTTP headers to include in requests.
-
     Exceptions:
         DeepgramApiError: Raised for known API errors.
         DeepgramUnknownApiError: Raised for unknown API errors.

deepgram/clients/abstract_async_client.py

@@ -20,11 +20,8 @@ class AbstractSyncRestClient:
     Args:
         url (Dict[str, str]): The base URL for the RESTful API, including any path segments.
         headers (Optional[Dict[str, Any]]): Optional HTTP headers to include in requests.
-
-    Attributes:
-        url (Dict[str, str]): The base URL for the RESTful API.
-        client (httpx.AsyncClient): An asynchronous HTTP client for making requests.
-        headers (Optional[Dict[str, Any]]): Optional HTTP headers to include in requests.
+        params (Optional[Dict[str, Any]]): Optional query parameters to include in requests.
+        timeout (Optional[httpx.Timeout]): Optional timeout configuration for requests.
 
     Exceptions:
         DeepgramApiError: Raised for known API errors.

deepgram/clients/abstract_sync_client.py

@@ -9,9 +9,7 @@ class DeepgramError(Exception):
 
     Attributes:
         message (str): The error message describing the exception.
-        status (str): The HTTP status associated with the API error.
     """
-
     def __init__(self, message: str):
         super().__init__(message)
         self.name = "DeepgramError"
@@ -28,7 +26,6 @@ class DeepgramModuleError(Exception):
     Attributes:
         message (str): The error message describing the exception.
     """
-
     def __init__(self, message: str):
         super().__init__(message)
         self.name = "DeepgramModuleError"
@@ -43,7 +40,6 @@ class DeepgramApiError(Exception):
         status (str): The HTTP status associated with the API error.
         original_error (str - json): The original error that was raised.
     """
-
     def __init__(self, message: str, status: str, original_error=None):
         super().__init__(message)
         self.name = "DeepgramApiError"
@@ -63,7 +59,6 @@ class DeepgramUnknownApiError(Exception):
         message (str): The error message describing the exception.
         status (str): The HTTP status associated with the API error.
     """
-
     def __init__(self, message: str, status: str):
         super().__init__(message, status)
         self.name = "DeepgramUnknownApiError"

deepgram/clients/errors.py

@@ -17,6 +17,25 @@
 
 
 class ListenClient:
+    """
+    Represents a client for interacting with the Deepgram API.
+
+    This class provides a client for making requests to the Deepgram API with various configuration options.
+
+    Attributes:
+        api_key (str): The Deepgram API key used for authentication.
+        config_options (DeepgramClientOptions): An optional configuration object specifying client options.
+
+    Raises:
+        DeepgramApiKeyError: If the API key is missing or invalid.
+
+    Methods:
+        live: (Preferred) Returns a Threaded LiveClient instance for interacting with Deepgram's transcription services.
+        prerecorded: (Preferred) Returns an Threaded PreRecordedClient instance for interacting with Deepgram's prerecorded transcription services.
+
+        asynclive: Returns an (Async) LiveClient instance for interacting with Deepgram's transcription services.
+        asyncprerecorded: Returns an (Async) PreRecordedClient instance for interacting with Deepgram's prerecorded transcription services.
+    """
     def __init__(self, config: DeepgramClientOptions):
         self.logger = logging.getLogger(__name__)
         self.logger.addHandler(logging.StreamHandler())

deepgram/clients/listen.py

@@ -7,28 +7,26 @@
 from .v1.options import LiveOptions as LiveOptionsLatest
 
 """
-The client.py points to the current supported version in the SDK.
+The vX/client.py points to the current supported version in the SDK.
 Older versions are supported in the SDK for backwards compatibility.
 """
 
-
 class LiveOptions(LiveOptionsLatest):
+    """
+    pass through for LiveOptions based on API version
+    """
     pass
 
-
 class LiveClient(LiveClientLatest):
     """
     Please see LiveClientLatest for details
     """
-
     def __init__(self, config):
         super().__init__(config)
 
-
 class AsyncLiveClient(AsyncLiveClientLatest):
     """
     Please see LiveClientLatest for details
     """
-
     def __init__(self, config):
         super().__init__(config)