sfq 0.0.37__tar.gz → 0.0.39__tar.gz

{sfq-0.0.37 → sfq-0.0.39}/.github/workflows/publish.yml

@@ -76,7 +76,6 @@ jobs:
 
           echo "Updating src/sfq/__init__.py user_agent to $VERSION"
           sed -i -E "s/(user_agent: str = \"sfq\/)[0-9]+\.[0-9]+\.[0-9]+(\")/\1$VERSION\2/" src/sfq/__init__.py
-          sed -i -E "s/(user_agent: str = \"sfq\/)[0-9]+\.[0-9]+\.[0-9]+(\")/\1$VERSION\2/" src/sfq/http_client.py
           sed -i -E "s/(default is \"sfq\/)[0-9]+\.[0-9]+\.[0-9]+(\")/\1$VERSION\2/" src/sfq/__init__.py
 
           echo "Updating src/sfq/__init__.py __version__ to $VERSION"
@@ -100,7 +99,7 @@ jobs:
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add pyproject.toml uv.lock src/sfq/__init__.py
+          git add pyproject.toml uv.lock src/sfq/__init__.py src/sfq/http_client.py
           git commit -m "CI: bump version to ${{ steps.get_version.outputs.version }}"
           git push
 

{sfq-0.0.37 → sfq-0.0.39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sfq
-Version: 0.0.37
+Version: 0.0.39
 Summary: Python wrapper for the Salesforce's Query API.
 Author-email: David Moruzzi <sfq.pypi@dmoruzi.com>
 Keywords: salesforce,salesforce query

{sfq-0.0.37 → sfq-0.0.39}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sfq"
-version = "0.0.37"
+version = "0.0.39"
 description = "Python wrapper for the Salesforce's Query API."
 readme = "README.md"
 authors = [{ name = "David Moruzzi", email = "sfq.pypi@dmoruzi.com" }]

{sfq-0.0.37 → sfq-0.0.39}/src/sfq/__init__.py

@@ -18,6 +18,7 @@ from .exceptions import (
     CRUDError,
     HTTPError,
     QueryError,
+    QueryTimeoutError,
     SFQException,
     SOAPError,
 )
@@ -35,6 +36,7 @@ __all__ = [
     "AuthenticationError",
     "APIError",
     "QueryError",
+    "QueryTimeoutError",
     "CRUDError",
     "SOAPError",
     "HTTPError",
@@ -43,7 +45,7 @@ __all__ = [
     "__version__",
 ]
 
-__version__ = "0.0.37"
+__version__ = "0.0.39"
 """
 ### `__version__`
 
@@ -67,7 +69,7 @@ class SFAuth:
         access_token: Optional[str] = None,
         token_expiration_time: Optional[float] = None,
         token_lifetime: int = 15 * 60,
-        user_agent: str = "sfq/0.0.37",
+        user_agent: str = "sfq/0.0.39",
         sforce_client: str = "_auto",
         proxy: str = "_auto",
     ) -> None:
@@ -132,7 +134,7 @@ class SFAuth:
         self._debug_cleanup = DebugCleanup(sf_auth=self)
 
         # Store version information
-        self.__version__ = "0.0.37"
+        self.__version__ = "0.0.39"
         """
         ### `__version__`
         
@@ -565,6 +567,7 @@ class SFAuth:
     def records_to_html_table(
         self,
         items: List[Dict[str, Any]],
+        headers: Dict[str, str] = None,
         styled: bool = False,
     ) -> str:
         """
@@ -576,4 +579,4 @@ class SFAuth:
         """
         if "records" in items:
             items = items["records"]
-        return records_to_html_table(items, styled=styled)
+        return records_to_html_table(items, headers=headers, styled=styled)

{sfq-0.0.37 → sfq-0.0.39}/src/sfq/exceptions.py

@@ -30,6 +30,12 @@ class QueryError(APIError):
     pass
 
 
+class QueryTimeoutError(QueryError):
+    """Raised when query operations timeout after all retry attempts."""
+
+    pass
+
+
 class CRUDError(APIError):
     """Raised when CRUD operations fail."""
 

{sfq-0.0.37 → sfq-0.0.39}/src/sfq/http_client.py

@@ -10,7 +10,8 @@ import json
 from typing import Dict, Optional, Tuple
 
 from .auth import AuthManager
-from .exceptions import ConfigurationError
+from .exceptions import ConfigurationError, QueryTimeoutError
+from .timeout_detector import TimeoutDetector
 from .utils import format_headers_for_logging, get_logger, log_api_usage
 
 logger = get_logger(__name__)
@@ -28,7 +29,7 @@ class HTTPClient:
     def __init__(
         self,
         auth_manager: AuthManager,
-        user_agent: str = "sfq/0.0.37",
+        user_agent: str = "sfq/0.0.39",
         sforce_client: str = "_auto",
         high_api_usage_threshold: int = 80,
     ) -> None:
@@ -184,18 +185,134 @@ class HTTPClient:
             if key == "Sforce-Limit-Info":
                 log_api_usage(value, self.high_api_usage_threshold)
 
-    def send_authenticated_request(
+    def send_authenticated_request_with_retry(
         self,
         method: str,
         endpoint: str,
         body: Optional[str] = None,
         additional_headers: Optional[Dict[str, str]] = None,
+        max_retries: int = 3,
     ) -> Tuple[Optional[int], Optional[str]]:
         """
-        Send an authenticated HTTP request with automatic token refresh.
+        Send an authenticated HTTP request with automatic timeout retry.
 
-        This is a convenience method that handles common request patterns
-        with authentication and standard headers.
+        This method wraps the existing send_authenticated_request with retry logic
+        that handles timeout errors by retrying up to max_retries times.
+
+        :param method: HTTP method
+        :param endpoint: API endpoint path
+        :param body: Optional request body
+        :param additional_headers: Optional additional headers to include
+        :param max_retries: Maximum number of retry attempts (default: 3)
+        :return: Tuple of (status_code, response_body) or (None, None) on failure
+        :raises QueryTimeoutError: When all retry attempts fail with timeout errors
+        """
+        # Validate retry count - negative values should be treated as 0
+        if max_retries < 0:
+            max_retries = 0
+            
+        last_exception = None
+        request_context = f"{method} {endpoint}"
+        
+        # Log initial request context for debugging
+        logger.trace("Starting request with retry capability: %s (max_retries=%d)", 
+                    request_context, max_retries)
+        
+        for attempt in range(max_retries + 1):  # +1 for initial attempt
+            try:
+                # Make the request using the original method
+                status, response_body = self._send_authenticated_request_internal(
+                    method, endpoint, body, additional_headers
+                )
+                
+                # Check if this is a timeout error
+                if TimeoutDetector.is_timeout_error(status, response_body, last_exception):
+                    timeout_type = TimeoutDetector.get_timeout_type(status, response_body, last_exception)
+                    
+                    if attempt < max_retries:
+                        # Log detailed retry initiation with timeout type identification
+                        logger.debug(
+                            "Timeout detected (%s timeout) on attempt %d/%d for %s - "
+                            "status_code=%s, retrying...",
+                            timeout_type, attempt + 1, max_retries + 1, request_context, status
+                        )
+                        continue
+                    else:
+                        # All retries exhausted - log error before raising exception
+                        logger.error(
+                            "All %d retry attempts failed with timeout errors for %s - "
+                            "final timeout type: %s, final status_code: %s",
+                            max_retries + 1, request_context, timeout_type, status
+                        )
+                        raise QueryTimeoutError("QUERY_TIMEOUT")
+                
+                # Not a timeout error or successful response, return immediately
+                if attempt > 0:
+                    # Log successful retry recovery
+                    logger.debug(
+                        "Request succeeded on retry attempt %d/%d for %s - "
+                        "status_code=%s, recovered from timeout",
+                        attempt + 1, max_retries + 1, request_context, status
+                    )
+                else:
+                    # Log successful first attempt (trace level to avoid noise)
+                    logger.trace("Request succeeded on first attempt for %s - status_code=%s", 
+                               request_context, status)
+                
+                return status, response_body
+                
+            except QueryTimeoutError:
+                # Re-raise QueryTimeoutError without logging (it was already logged)
+                raise
+            except Exception as e:
+                last_exception = e
+                
+                # Check if this exception indicates a timeout
+                if TimeoutDetector.is_timeout_error(None, None, e):
+                    timeout_type = TimeoutDetector.get_timeout_type(None, None, e)
+                    
+                    if attempt < max_retries:
+                        # Log detailed retry initiation with exception context
+                        logger.debug(
+                            "Timeout exception (%s timeout) on attempt %d/%d for %s - "
+                            "exception: %s, retrying...",
+                            timeout_type, attempt + 1, max_retries + 1, request_context, 
+                            type(e).__name__
+                        )
+                        continue
+                    else:
+                        # All retries exhausted - log error with exception details before raising
+                        logger.error(
+                            "All %d retry attempts failed with timeout errors for %s - "
+                            "final timeout type: %s, final exception: %s",
+                            max_retries + 1, request_context, timeout_type, type(e).__name__
+                        )
+                        raise QueryTimeoutError("QUERY_TIMEOUT")
+                else:
+                    # Not a timeout exception - log and re-raise immediately
+                    logger.debug(
+                        "Non-timeout exception on attempt %d for %s - "
+                        "exception: %s, not retrying",
+                        attempt + 1, request_context, type(e).__name__
+                    )
+                    raise e
+        
+        # This should never be reached, but just in case
+        logger.error("Unexpected code path reached in retry logic for %s", request_context)
+        raise QueryTimeoutError("QUERY_TIMEOUT")
+
+    def _send_authenticated_request_internal(
+        self,
+        method: str,
+        endpoint: str,
+        body: Optional[str] = None,
+        additional_headers: Optional[Dict[str, str]] = None,
+    ) -> Tuple[Optional[int], Optional[str]]:
+        """
+        Internal method for sending authenticated requests without retry logic.
+        
+        This is the original send_authenticated_request logic extracted to avoid
+        recursion in the retry wrapper.
 
         :param method: HTTP method
         :param endpoint: API endpoint path
@@ -210,6 +327,32 @@ class HTTPClient:
 
         return self.send_request(method, endpoint, headers, body)
 
+    def send_authenticated_request(
+        self,
+        method: str,
+        endpoint: str,
+        body: Optional[str] = None,
+        additional_headers: Optional[Dict[str, str]] = None,
+        max_retries: int = 3,
+    ) -> Tuple[Optional[int], Optional[str]]:
+        """
+        Send an authenticated HTTP request with automatic timeout retry.
+
+        This is a convenience method that handles common request patterns
+        with authentication, standard headers, and automatic retry for timeout errors.
+
+        :param method: HTTP method
+        :param endpoint: API endpoint path
+        :param body: Optional request body
+        :param additional_headers: Optional additional headers to include
+        :param max_retries: Maximum number of retry attempts (default: 3)
+        :return: Tuple of (status_code, response_body) or (None, None) on failure
+        :raises QueryTimeoutError: When all retry attempts fail with timeout errors
+        """
+        return self.send_authenticated_request_with_retry(
+            method, endpoint, body, additional_headers, max_retries
+        )
+
     def send_token_request(
         self,
         payload: Dict[str, str],

sfq-0.0.39/src/sfq/timeout_detector.py

@@ -0,0 +1,147 @@
+"""
+Timeout detection module for the SFQ library.
+
+This module provides utilities for detecting different types of timeout errors
+that can occur during HTTP requests to Salesforce APIs.
+"""
+
+from typing import Optional
+import errno
+
+
+class TimeoutDetector:
+    """Utility class for detecting timeout conditions in HTTP responses."""
+    
+    # Server timeout message pattern
+    SERVER_TIMEOUT_MESSAGE = "Your query request was running for too long."
+    # Server timeout error code pattern
+    SERVER_TIMEOUT_ERROR_CODE = "QUERY_TIMEOUT"
+    
+    @staticmethod
+    def is_server_timeout(status_code: Optional[int], response_body: Optional[str]) -> bool:
+        """
+        Detect server-side query timeout from HTTP response.
+        
+        Server timeouts are indicated by:
+        - HTTP status code 400
+        - Response body containing the specific timeout message OR timeout error code
+        
+        Args:
+            status_code: HTTP status code from the response
+            response_body: Response body content as string
+            
+        Returns:
+            bool: True if this is a server timeout, False otherwise
+        """
+        if status_code != 400:
+            return False
+            
+        if response_body is None or response_body == "":
+            return False
+            
+        # Check for either the timeout message or the error code
+        # Handle potential encoding issues by using string containment check
+        try:
+            return (TimeoutDetector.SERVER_TIMEOUT_MESSAGE in response_body or 
+                    TimeoutDetector.SERVER_TIMEOUT_ERROR_CODE in response_body)
+        except (TypeError, UnicodeError):
+            # If there are encoding issues, assume it's not a timeout
+            return False
+    
+    @staticmethod
+    def is_connection_timeout(
+        status_code: Optional[int], 
+        response_body: Optional[str], 
+        exception: Optional[Exception] = None
+    ) -> bool:
+        """
+        Detect connection timeout from HTTP response and exception context.
+        
+        Connection timeouts are indicated by:
+        - HTTP status code is None
+        - Response body is None
+        - Exception with errno 110 (Connection timed out)
+        
+        Args:
+            status_code: HTTP status code from the response (should be None)
+            response_body: Response body content (should be None)
+            exception: Exception that occurred during the request
+            
+        Returns:
+            bool: True if this is a connection timeout, False otherwise
+        """
+        # Check for the basic connection timeout pattern
+        if status_code is not None or response_body is not None:
+            return False
+            
+        # Check if we have an exception with errno 110
+        if exception is None:
+            return False
+            
+        # Check for errno 110 in various exception types
+        if hasattr(exception, 'errno') and exception.errno == errno.ETIMEDOUT:
+            return True
+            
+        # Check for errno in nested exceptions (common in urllib/http.client)
+        if hasattr(exception, '__cause__') and exception.__cause__ is not None:
+            cause = exception.__cause__
+            if hasattr(cause, 'errno') and cause.errno == errno.ETIMEDOUT:
+                return True
+                
+        # Check for errno in args (some exceptions store it there)
+        if hasattr(exception, 'args') and exception.args:
+            for arg in exception.args:
+                if hasattr(arg, 'errno') and arg.errno == errno.ETIMEDOUT:
+                    return True
+                    
+        return False
+    
+    @staticmethod
+    def is_timeout_error(
+        status_code: Optional[int], 
+        response_body: Optional[str], 
+        exception: Optional[Exception] = None
+    ) -> bool:
+        """
+        Unified timeout detection for both server and connection timeout scenarios.
+        
+        This method combines both server timeout and connection timeout detection
+        to provide a single interface for timeout checking.
+        
+        Args:
+            status_code: HTTP status code from the response
+            response_body: Response body content as string
+            exception: Exception that occurred during the request
+            
+        Returns:
+            bool: True if this is any type of timeout error, False otherwise
+        """
+        return (
+            TimeoutDetector.is_server_timeout(status_code, response_body) or
+            TimeoutDetector.is_connection_timeout(status_code, response_body, exception)
+        )
+    
+    @staticmethod
+    def get_timeout_type(
+        status_code: Optional[int], 
+        response_body: Optional[str], 
+        exception: Optional[Exception] = None
+    ) -> Optional[str]:
+        """
+        Determine the type of timeout error.
+        
+        Args:
+            status_code: HTTP status code from the response
+            response_body: Response body content as string
+            exception: Exception that occurred during the request
+            
+        Returns:
+            str: 'server' for server timeouts, 'connection' for connection timeouts,
+                 None if not a timeout error
+        """
+        if TimeoutDetector.is_server_timeout(status_code, response_body):
+            return 'server'
+        elif TimeoutDetector.is_connection_timeout(status_code, response_body, exception):
+            return 'connection'
+        else:
+            return None

{sfq-0.0.37 → sfq-0.0.39}/src/sfq/utils.py

@@ -197,9 +197,7 @@ def extract_org_and_user_ids(token_id_url: str) -> Tuple[str, str]:
         raise ValueError(f"Invalid token ID URL format: {token_id_url}")
 
 
-def dicts_to_html_table(
-    items: List[Dict[str, Any]], styled: bool = False
-) -> str:
+def dicts_to_html_table(items: List[Dict[str, Any]], styled: bool = False) -> str:
     """
     Convert a list of dictionaries to a compact HTML table.
 
@@ -309,13 +307,70 @@ def dicts_to_html_table(
 
     return "".join(html)
 
-def records_to_html_table(records: List[Dict[str, Any]], styled: bool = False) -> str:
-    """Convert a list of records to an HTML table."""
-    # really we don't want anything associated with "attributes"
-    normalized_records = []
-    for record in records:
+
+def flatten_dict(d, parent_key="", sep="."):
+    """Recursively flatten a dictionary with dot notation."""
+    items = {}
+    for k, v in d.items():
+        new_key = f"{parent_key}{sep}{k}" if parent_key else k
+        if isinstance(v, dict):
+            items.update(flatten_dict(v, new_key, sep=sep))
+        else:
+            items[new_key] = v
+    return items
+
+
+def remove_attributes(obj):
+    """Recursively remove 'attributes' key from dicts/lists."""
+    if isinstance(obj, dict):
+        return {k: remove_attributes(v) for k, v in obj.items() if k != "attributes"}
+    elif isinstance(obj, list):
+        return [remove_attributes(item) for item in obj]
+    else:
+        return obj
+
+
+def records_to_html_table(
+    records: List[Dict[str, Any]], headers: Dict[str, str] = None, styled: bool = False
+) -> str:
+    if not isinstance(records, list):
+        raise ValueError("records must be a list of dictionaries")
+
+    cleaned = remove_attributes(records)
+
+    flat_rows = []
+    for record in cleaned:
         if not isinstance(record, dict):
             raise ValueError(f"Record is not a dictionary: {record!r}")
-        record.pop("attributes", None)
-        normalized_records.append(record)
-    return dicts_to_html_table(normalized_records, styled=styled)
+        flat_rows.append(flatten_dict(record))
+
+    # Preserve column order across all rows
+    seen = set()
+    ordered_columns = []
+    for row in flat_rows:
+        for key in row.keys():
+            if key not in seen:
+                ordered_columns.append(key)
+                seen.add(key)
+
+    # headers optionally remaps flattened field names to user-friendly display names
+    if headers is None:
+        headers = {}
+        for col in ordered_columns:
+            headers[col] = col
+    else:
+        for col in ordered_columns:
+            headers[col] = headers.get(col, col)
+
+    # Normalize rows so all have the same keys, using remapped column names
+    normalized_data = []
+    for row in flat_rows:
+        normalized_row = {
+            headers.get(col, col): (
+                "" if row.get(col, None) is None else row.get(col, "")
+            )
+            for col in ordered_columns
+        }
+        normalized_data.append(normalized_row)
+
+    return dicts_to_html_table(normalized_data, styled=styled)

{sfq-0.0.37 → sfq-0.0.39}/tests/test_compatibility.py

@@ -36,6 +36,7 @@ class TestImportCompatibility:
             CRUDError,
             HTTPError,
             QueryError,
+            QueryTimeoutError,
             SFQException,
             SOAPError,
         )
@@ -44,6 +45,7 @@ class TestImportCompatibility:
         assert issubclass(AuthenticationError, SFQException)
         assert issubclass(APIError, SFQException)
         assert issubclass(QueryError, APIError)
+        assert issubclass(QueryTimeoutError, QueryError)
         assert issubclass(CRUDError, APIError)
         assert issubclass(SOAPError, APIError)
         assert issubclass(