docs: enhance Client class documentation

Author: merydian

ORStools/common/client.py

@@ -45,20 +45,27 @@
 
 
 class Client(QObject):
-    """Performs requests to the ORS API services."""
+    """Performs requests to the ORS API services.
+
+    This class handles HTTP communication with the openrouteservice API,
+    including authentication, retry logic for rate limiting, and progress
+    tracking.
+
+    Signals:
+        overQueryLimit: Emitted when rate limit is hit, passes delay in seconds
+        downloadProgress: Emitted during download, passes progress ratio (0-1)
+    """
 
     overQueryLimit = pyqtSignal(int)
     downloadProgress = pyqtSignal(int)
 
-
     def __init__(self, provider: Optional[dict] = None, agent: Optional[str] = None) -> None:
-        """
-        :param provider: A openrouteservice provider from config.yml
-        :type provider: dict
+        """Initialize the ORS API client.
 
-        :param retry_timeout: Timeout across multiple retryable requests, in
-            seconds.
-        :type retry_timeout: int
+        :param provider: Provider configuration containing base_url, key, timeout, and ENV_VARS
+        :type provider: dict
+        :param agent: User agent string for the HTTP requests
+        :type agent: str
         """
         QObject.__init__(self)
 
@@ -87,8 +94,20 @@ def _request(
         self,
         post_json: Optional[dict],
         blocking_request: QgsBlockingNetworkRequest,
-        request: QNetworkRequest
+        request: QNetworkRequest,
     ) -> str:
+        """Execute a blocking network request.
+
+        :param post_json: JSON payload for POST requests, None for GET requests
+        :type post_json: dict or None
+        :param blocking_request: QGIS blocking network request handler
+        :type blocking_request: QgsBlockingNetworkRequest
+        :param request: Network request with URL and headers
+        :type request: QNetworkRequest
+        :return: Network reply content
+        :rtype: QgsNetworkReplyContent
+        :raises: Various ApiError exceptions based on HTTP status codes
+        """
         if post_json is not None:
             result = blocking_request.post(request, json.dumps(post_json).encode())
         else:
@@ -108,19 +127,40 @@ def fetch_with_retry(
         post_json: Optional[dict] = None,
         max_retries: int = 100,
     ):
+        """Fetch data from the API with automatic retry on rate limit errors.
+
+        Implements exponential backoff with jitter for retries. The first retry
+        occurs after exactly 61 seconds, subsequent retries use exponential
+        backoff capped at 5 minutes.
+
+        :param url: API endpoint path (e.g., "/v2/directions/driving-car/geojson")
+        :type url: str
+        :param params: URL query parameters
+        :type params: dict
+        :param first_request_time: Timestamp of the first request attempt
+        :type first_request_time: datetime or None
+        :param post_json: JSON payload for POST requests
+        :type post_json: dict or None
+        :param max_retries: Maximum number of retry attempts
+        :type max_retries: int
+        :return: Parsed JSON response from the API
+        :rtype: dict
+        :raises exceptions.Timeout: When total retry time exceeds configured timeout
+        :raises exceptions.ApiError: On non-retryable API errors (4xx except 429)
+        """
         first_request_time = datetime.now()
 
         authed_url = self._generate_auth_url(url, params)
         self.url = self.base_url + authed_url
 
         request = QNetworkRequest(QUrl(self.url))
-        
+
         for header, value in self.headers.items():
             request.setRawHeader(header.encode(), value.encode())
 
         blocking_request = QgsBlockingNetworkRequest()
 
-        blocking_request.downloadProgress.connect(lambda r, t: self.downloadProgress.emit(r/t))
+        blocking_request.downloadProgress.connect(lambda r, t: self.downloadProgress.emit(r / t))
 
         logger.log(f"url: {self.url}\nParameters: {json.dumps(post_json, indent=2)}", 0)
 
@@ -131,7 +171,7 @@ def fetch_with_retry(
                 reply = self._request(post_json, blocking_request, request)
                 content = reply.content().data().decode()
                 break
-            
+
             except exceptions.OverQueryLimit as e:
                 if datetime.now() - first_request_time > timedelta(seconds=self.timeout):
                     raise exceptions.Timeout()
@@ -140,9 +180,9 @@ def fetch_with_retry(
 
                 delay_seconds = self.get_delay_seconds(i)
                 self.overQueryLimit.emit(delay_seconds)
-                
+
                 loop = QEventLoop()
-                QTimer.singleShot(delay_seconds * 1000, loop.quit)  # milliseconds
+                QTimer.singleShot(delay_seconds * 1000, loop.quit)
                 loop.exec_()
 
             except exceptions.ApiError as e:
@@ -164,19 +204,38 @@ def fetch_with_retry(
         return json.loads(content)
 
     def get_delay_seconds(self, retry_counter: int) -> int:
+        """Calculate delay before next retry attempt.
+
+        First retry waits exactly 61 seconds. Subsequent retries use exponential
+        backoff with base delay of 60s * 1.5^(retry_counter-1), capped at 300s,
+        with random jitter between 30-60% of the calculated delay.
+
+        :param retry_counter: Zero-based retry attempt number
+        :type retry_counter: int
+        :return: Delay in seconds before next retry
+        :rtype: int
+        """
         if retry_counter == 0:
-            delay_seconds = 61  # First retry after exactly 61 seconds
+            delay_seconds = 61
         else:
-            # Exponential backoff starting from 60 seconds
-            base_delay = min(60 * (1.5 ** (retry_counter - 1)), 300)  # Cap at 5 minutes
+            base_delay = min(60 * (1.5 ** (retry_counter - 1)), 300)
             jitter = random.uniform(0.3, 0.6)
             delay_seconds = base_delay * jitter
 
         logger.log(f"Retry Counter: {retry_counter}, Delay: {delay_seconds:.2f}s", 1)
         return int(delay_seconds)
 
     def _check_status(self, reply: QNetworkReply) -> None:
-        """Check response status and raise appropriate exceptions."""
+        """Check HTTP response status and raise appropriate exceptions.
+
+        :param reply: Network reply to check
+        :type reply: QNetworkReply
+        :raises exceptions.InvalidKey: On 403 Forbidden (invalid API key)
+        :raises exceptions.OverQueryLimit: On 429 Too Many Requests
+        :raises exceptions.ApiError: On 4xx client errors
+        :raises exceptions.GenericServerError: On 5xx server errors
+        :raises Exception: On network errors or invalid responses
+        """
         status_code = reply.attribute(QNetworkRequest.HttpStatusCodeAttribute)
         message = reply.content().data().decode()
 
@@ -197,19 +256,15 @@ def _check_status(self, reply: QNetworkReply) -> None:
             raise exceptions.GenericServerError(str(status_code), message)
 
     def _generate_auth_url(self, path: str, params: Union[Dict, List]) -> str:
-        """Returns the path and query string portion of the request URL, first
-        adding any necessary parameters.
-
-        :param path: The path portion of the URL.
-        :type path: string
-
-        :param params: URL parameters.
-        :type params: dict or list of key/value tuples
-
-        :returns: encoded URL
-        :rtype: string
+        """Generate authenticated URL with query parameters.
+
+        :param path: API endpoint path
+        :type path: str
+        :param params: Query parameters as dict or list of tuples
+        :type params: dict or list
+        :return: URL path with encoded query string
+        :rtype: str
         """
-
         if isinstance(params, dict):
             params = sorted(dict(**params).items())