Add inline comments and docstring

ringcentral/core/__init__.py

@@ -9,6 +9,22 @@ def is_third():
 
 
 def urlencode(s):
+    """
+        Encodes the given dictionary `s` into a URL-encoded string.
+
+        Parameters:
+            s (dict): A dictionary containing the key-value pairs to be encoded.
+
+        Returns:
+            str: A URL-encoded string representing the input dictionary.
+
+        Raises:
+            Exception: If neither `urllib.urlencode` nor `urllib.parse.urlencode` is available.
+
+        Note:
+            This function checks for the presence of `urllib.urlencode` and `urllib.parse.urlencode`
+            to ensure compatibility across Python 2 and Python 3.
+    """
     if hasattr(urllib, 'urlencode'):
         return urllib.urlencode(s)
     elif hasattr(urllib, 'parse'):
@@ -18,10 +34,32 @@ def urlencode(s):
 
 
 def iterator(thing):
+    """
+    Returns an iterator over key-value pairs of `thing`.
+
+    If `thing` has an `iteritems` method, it is used; otherwise, `thing.items()` is iterated over.
+
+    Parameters:
+        thing: An iterable object.
+
+    Returns:
+        iterator: An iterator over the key-value pairs of `thing`.
+    """
     return thing.iteritems() if hasattr(thing, 'iteritems') else iter(thing.items())
 
 
 def base64encode(s):
+    """
+    Encodes the input string `s` into base64 format.
+
+    Parameters:
+        s (str): The string to be encoded.
+
+    Returns:
+        str: The base64 encoded string.
+
+    """
+    # Use Python 3 compatible base64 encoding if detected, otherwise use default encoding
     if is_third():
         return str(base64.b64encode(bytes(s, 'utf8')), 'utf8')
     else:
@@ -36,6 +74,15 @@ def tostr(s):
 
 
 def clean_decrypted(s):
+    """
+    Cleans the decrypted string `s` by removing specific control characters.
+
+    Parameters:
+        s (str): The decrypted string to be cleaned.
+
+    Returns:
+        str: The cleaned decrypted string.
+    """
     if is_third():
         return re.sub(r"[\u0001-\u0010]", '', s).strip()
     else:

ringcentral/deprecated_pubnub_subscription/events.py

@@ -1,5 +1,18 @@
 
 class Events:
+    """
+    Class representing different types of events that can occur.
+
+    Attributes:
+        connectionError (str): Represents an event indicating a connection error.
+        notification (str): Represents an event for receiving notifications.
+        subscribeSuccess (str): Represents a successful subscription event.
+        subscribeError (str): Represents an error event during subscription.
+        renewSuccess (str): Represents a successful renewal event.
+        renewError (str): Represents an error event during renewal.
+        removeSuccess (str): Represents a successful removal event.
+        removeError (str): Represents an error event during removal.
+    """
     connectionError = 'connectionError'
     notification = 'notification'
     subscribeSuccess = 'subscribeSuccess'

ringcentral/deprecated_pubnub_subscription/subscription.py

@@ -34,24 +34,52 @@ def __init__(self, platform):
         }
         self._pubnub = None
 
+    # Retrieve the PubNub instance associated with this object.
     def pubnub(self):
         return self._pubnub
 
     def register(self, events=None):
+        """
+            Register for events. If the connection is alive, renews the registration; otherwise, subscribes.
+
+            Args:
+                events (list, optional): List of events to register for.
+
+            Returns:
+                obj: Result of renewal or subscription.
+        """
         if self.alive():
             return self.renew(events=events)
         else:
             return self.subscribe(events=events)
 
     def add_events(self, events):
+        """
+        Add additional events to be filtered.
+
+        Args:
+            events (list): List of events to add.
+        """
         self._event_filters += events
         pass
 
     def set_events(self, events):
         self._event_filters = events
 
     def subscribe(self, events=None):
+        """
+        Subscribe to events using the defined event filters.
 
+        Args:
+            events (list, optional): List of events to subscribe to.
+
+        Raises:
+            Exception: If events are undefined.
+            Exception: If there's an error during subscription Unsubscribe PUBNUB and trigger subscribeError event.
+
+        Returns:
+            obj: Response object from the subscription request.
+        """
         if events:
             self.set_events(events)
 
@@ -78,7 +106,20 @@ def subscribe(self, events=None):
             raise
 
     def renew(self, events=None):
+        """
+            Renew the subscription with the current or specified events.
+
+            Args:
+                events (list, optional): List of events to renew the subscription with.
 
+            Raises:
+                Exception: If the subscription is not alive.
+                Exception: If events are undefined.
+                Exception: If there's an error during renewal Unsubscribe PUBNUB and trigger renewError event.
+
+            Returns:
+                obj: Response object from the renewal request.
+        """
         if events:
             self.set_events(events)
 
@@ -106,6 +147,16 @@ def renew(self, events=None):
             raise
 
     def remove(self):
+        """
+            Remove the subscription.
+
+            Raises:
+                Exception: If the subscription is not alive.
+                Exception: If there's an error during removal Unsubscribe PUBNUB and trigger removeError event.
+
+            Returns:
+                obj: Response object from the removal request.
+        """
         if not self.alive():
             raise Exception('Subscription is not alive')
 
@@ -181,6 +232,20 @@ def _notify(self, message):
         self.trigger(Events.notification, message)
 
     def _decrypt(self, message):
+        """
+        Decrypt the message if encryption is enabled in the subscription.
+
+        Args:
+            message (str): Encrypted message.
+
+        Raises:
+            ValueError: If the subscription is not alive.
+            ImportError: If Crypto.Cipher or required modules are not available.
+            Exception: If there's an error during decryption.
+
+        Returns:
+            dict: Decrypted message.
+        """
         if not self.alive():
             raise Exception('Subscription is not alive')
 

ringcentral/http/client.py

@@ -14,6 +14,18 @@ def __init__(self):
         pass
 
     def send(self, request):
+        """
+            Send the HTTP request and handle the response.
+
+            Args:
+                request (obj): The HTTP request object.
+
+            Returns:
+                obj: The HTTP response object.
+
+            Raises:
+                ApiException: If an error occurs during the request or response handling.
+        """
         response = None
 
         try:
@@ -51,14 +63,19 @@ def load_response(self, request):
 
     def create_request(self, method='', url='', query_params=None, body=None, headers=None):
         """
-        :param method:
-        :param url:
-        :param query_params:
-        :param body:
-        :param headers:
-        :return:requests.Request
-        """
+            Create an HTTP request object.
+
+            Args:
+                method (str): The HTTP method (e.g., GET, POST).
+                url (str): The URL for the request.
+                query_params (dict, optional): Dictionary containing query parameters.
+                body (dict, optional): Request body data.
+                headers (dict, optional): Request headers.
 
+            Returns:
+                requests.Request: The HTTP request object.
+
+            """
         if query_params:
             if type(query_params) is dict:
                 query = ""
@@ -75,7 +92,7 @@ def create_request(self, method='', url='', query_params=None, body=None, header
                 url = url + ('&' if url.find('?') > 0 else '?') + query
 
         content_type = None
-        
+
         if headers is None:
             headers = {}
 

ringcentral/platform/events.py

@@ -1,5 +1,16 @@
 
 class Events:
+    """
+    Events class representing various event types.
+
+    Attributes:
+        refreshSuccess (str): Represents a successful refresh event.
+        refreshError (str): Represents an error during refresh.
+        loginSuccess (str): Represents a successful login event.
+        loginError (str): Represents an error during login.
+        logoutSuccess (str): Represents a successful logout event.
+        logoutError (str): Represents an error during logout.
+    """
     refreshSuccess = 'refreshSuccess'
     refreshError = 'refreshError'
     loginSuccess = 'loginSuccess'