fix(python-bindings): rename and improve TimeoutError and improve docstring (#180)

# Description

- Do not overrride Python's built-in TimeoutError Exception
- Created AGP custom exception from TimeoutError 
- General docstring fixes
- Nit fix to raise a narrower exception

Signed-off-by: brisacoder <[email protected]>

Author: brisacoder

data-plane/python-bindings/agp_bindings/__init__.py

@@ -35,14 +35,53 @@
 )
 
 
-class TimeoutError(RuntimeError):
+class AGPTimeoutError(TimeoutError):
     """
-    Custom exception class for timeout errors.
+    Exception raised for AGP timeout errors.
+
+    This exception is raised when an operation in an AGP session times out.
+    It encapsulates detailed information about the timeout event, including the
+    ID of the message that caused the timeout and the session identifier. An
+    optional underlying exception can also be provided to offer additional context.
+
+    Attributes:
+        message_id (int): The identifier associated with the message triggering the timeout.
+        session_id (int): The identifier of the session where the timeout occurred.
+        message (str): A brief description of the timeout error.
+        original_exception (Exception, optional): The underlying exception that caused the timeout, if any.
+
+    The string representation of the exception (via __str__) returns a full message that
+    includes the custom message, session ID, and message ID, as well as details of the
+    original exception (if present). This provides a richer context when the exception is logged
+    or printed.
     """
 
-    def __init__(self, message_id: int, session_id: int):
-        self.message = f"Timeout error: message={message_id} session={session_id}"
-        super().__init__(self.message)
+    def __init__(
+        self,
+        message_id: int,
+        session_id: int,
+        message: str = "AGP timeout error",
+        original_exception: Optional[Exception] = None,
+    ):
+
+        self.message_id = message_id
+        self.session_id = session_id
+        self.message = message
+        self.original_exception = original_exception
+        full_message = f"{message} for session {session_id} and message {message_id}"
+        if original_exception:
+            full_message = f"{full_message}. Caused by: {original_exception!r}"
+        super().__init__(full_message)
+
+    def __str__(self):
+        return self.args[0]
+
+    def __repr__(self):
+        return (
+            f"{self.__class__.__name__}(session_id={self.session_id!r}, "
+            f"message_id={self.message_id!r}, "
+            f"message={self.message!r}, original_exception={self.original_exception!r})"
+        )
 
 
 class Gateway:
@@ -170,16 +209,21 @@ async def create_ff_session(
         queue_size: int = 0,
     ) -> PySessionInfo:
         """
-        Create a new session.
+        Create a new Fire-and-Forget session.
+        This asynchronous function initializes a new session using the provided
+        configuration and creates an associated message queue with the specified size.
+        A session is created and stored along with its unbounded or bounded queue.
 
         Args:
-            session_config (PyFireAndForgetConfiguration): The session configuration.
-            queue_size (int): The size of the queue for the session.
-                              If 0, the queue will be unbounded.
-                              If a positive integer, the queue will be bounded to that size.
+            session_config (PyFireAndForgetConfiguration, optional): The configuration parameters for the session.
+                Defaults to an instance of PyFireAndForgetConfiguration.
+            queue_size (int, optional): The maximum size of the session's queue.
+                If 0, the queue is unbounded.
+                If a positive integer, the queue is bounded to that size.
+                Defaults to 0.
 
         Returns:
-            ID of the session
+            PySessionInfo: An object containing details about the created session.
         """
 
         session = await create_ff_session(self.svc, session_config)
@@ -192,16 +236,21 @@ async def create_rr_session(
         queue_size: int = 0,
     ) -> PySessionInfo:
         """
-        Create a new session.
+        Create a new Request-Response session.
+        This asynchronous function initializes a new session using the provided
+        configuration and creates an associated message queue with the specified size.
+        A session is created and stored along with its unbounded or bounded queue.
 
         Args:
-            session_config (PyRequestResponseConfiguration): The session configuration.
-            queue_size (int): The size of the queue for the session.
-                                If 0, the queue will be unbounded.
-                                If a positive integer, the queue will be bounded to that size.
+            session_config (PyRequestResponseConfiguration, optional): The configuration parameters for the session.
+                Defaults to an instance of PyRequestResponseConfiguration.
+            queue_size (int, optional): The maximum size of the session's queue.
+                If 0, the queue is unbounded.
+                If a positive integer, the queue is bounded to that size.
+                Defaults to 0.
 
         Returns:
-            ID of the session
+            PySessionInfo: An object containing details about the created session.
         """
 
         session = await create_rr_session(self.svc, session_config)
@@ -239,11 +288,14 @@ async def delete_session(self, session_id: int):
 
         Returns:
             None
+
+        Raises:
+            ValueError: If the session ID is not found.
         """
 
         # Check if the session ID is in the sessions map
         if session_id not in self.sessions:
-            raise Exception("session not found", session_id)
+            raise ValueError(f"session not found: {session_id}")
 
         # Remove the session from the map
         del self.sessions[session_id]
@@ -560,7 +612,7 @@ async def _receive_loop(self) -> None:
 
                     # figure out what exception to raise based on the reason
                     if reason == "timeout":
-                        err = TimeoutError(message_id, session_id)
+                        err = AGPTimeoutError(message_id, session_id)
                     else:
                         # we don't know the reason, just raise the original exception
                         raise e