pdfdancer-client-python 0.2.22__py3-none-any.whl → 0.2.24__py3-none-any.whl

pdfdancer/__init__.py

@@ -10,6 +10,7 @@ from .exceptions import (
     FontNotFoundException,
     HttpClientException,
     PdfDancerException,
+    RateLimitException,
     SessionException,
     ValidationException,
 )
@@ -80,6 +81,7 @@ __all__ = [
     "ValidationException",
     "HttpClientException",
     "SessionException",
+    "RateLimitException",
     "set_ssl_verify",
 ]
 

pdfdancer/exceptions.py

@@ -62,3 +62,20 @@ class ValidationException(PdfDancerException):
     """
 
     pass
+
+
+class RateLimitException(PdfDancerException):
+    """
+    Exception raised when the API rate limit is exceeded (HTTP 429).
+    Includes retry-after information if provided by the server.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[int] = None,
+        response: Optional[httpx.Response] = None,
+    ):
+        super().__init__(message)
+        self.retry_after = retry_after
+        self.response = response

pdfdancer/pdfdancer_v1.py

@@ -11,6 +11,7 @@ import gzip
 import json
 import logging
 import os
+import sys
 import time
 from datetime import datetime, timezone
 from pathlib import Path
@@ -24,6 +25,7 @@ from .exceptions import (
     FontNotFoundException,
     HttpClientException,
     PdfDancerException,
+    RateLimitException,
     SessionException,
     ValidationException,
 )
@@ -234,6 +236,30 @@ def _is_retryable_error(error: Exception) -> bool:
     return any(msg in error_msg for msg in retryable_messages)
 
 
+def _get_retry_after_delay(response: httpx.Response) -> Optional[int]:
+    """
+    Extract Retry-After delay from response headers.
+
+    Args:
+        response: HTTP response with potential Retry-After header
+
+    Returns:
+        Delay in seconds, or None if header not present or invalid
+    """
+    retry_after = response.headers.get("Retry-After")
+    if not retry_after:
+        return None
+
+    try:
+        # Retry-After can be either a number of seconds or an HTTP date
+        # Try parsing as integer first (seconds)
+        return int(retry_after)
+    except ValueError:
+        # If not a number, it might be an HTTP date - ignore for now
+        # Most rate limiting APIs use seconds
+        return None
+
+
 class PageClient:
     def __init__(
         self,
@@ -708,38 +734,102 @@ class PDFDancer:
 
         Raises:
             HttpClientException: If token request fails
+            RateLimitException: If rate limit is exceeded
         """
+        # Create temporary client without authentication
+        temp_client = httpx.Client(http2=True, verify=not DISABLE_SSL_VERIFY)
+        max_retries = 3
+        retry_backoff_factor = 1.0
+
         try:
-            # Create temporary client without authentication
-            temp_client = httpx.Client(http2=True, verify=not DISABLE_SSL_VERIFY)
+            last_error: Optional[Exception] = None
+            attempt = 0
 
-            headers = {"X-Fingerprint": Fingerprint.generate()}
+            while attempt <= max_retries:
+                try:
+                    headers = {"X-Fingerprint": Fingerprint.generate()}
 
-            response = temp_client.post(
-                cls._cleanup_url_path(base_url, "/keys/anon"),
-                headers=headers,
-                timeout=timeout if timeout > 0 else None,
-            )
+                    response = temp_client.post(
+                        cls._cleanup_url_path(base_url, "/keys/anon"),
+                        headers=headers,
+                        timeout=timeout if timeout > 0 else None,
+                    )
 
-            response.raise_for_status()
-            token_data = response.json()
+                    response.raise_for_status()
+                    token_data = response.json()
 
-            # Extract token from response (matches Java AnonTokenResponse structure)
-            if isinstance(token_data, dict) and "token" in token_data:
-                return token_data["token"]
-            else:
-                raise HttpClientException("Invalid anonymous token response format")
+                    # Extract token from response (matches Java AnonTokenResponse structure)
+                    if isinstance(token_data, dict) and "token" in token_data:
+                        return token_data["token"]
+                    else:
+                        raise HttpClientException(
+                            "Invalid anonymous token response format"
+                        )
 
-        except httpx.HTTPStatusError as e:
-            raise HttpClientException(
-                f"Failed to obtain anonymous token: HTTP {e.response.status_code}",
-                response=e.response,
-                cause=e,
-            ) from None
-        except httpx.RequestError as e:
-            raise HttpClientException(
-                f"Failed to obtain anonymous token: {str(e)}", response=None, cause=e
-            ) from None
+                except httpx.HTTPStatusError as e:
+                    # Handle 429 (rate limit) with retry
+                    if e.response.status_code == 429 and attempt < max_retries:
+                        retry_after = _get_retry_after_delay(e.response)
+                        if retry_after is not None:
+                            delay = retry_after
+                        else:
+                            # Use exponential backoff if no Retry-After header
+                            delay = retry_backoff_factor * (2**attempt)
+
+                        # Always log 429 to stderr for visibility
+                        print(
+                            f"Rate limit (429) on POST /keys/anon - retrying in {delay}s "
+                            f"(attempt {attempt + 1}/{max_retries})",
+                            file=sys.stderr,
+                        )
+                        if DEBUG:
+                            print(
+                                f"{time.time()}|POST /keys/anon - Rate limit exceeded (429), "
+                                f"retrying in {delay}s (attempt {attempt + 1}/{max_retries})"
+                            )
+                        time.sleep(delay)
+                        attempt += 1
+                        continue
+
+                    # Raise RateLimitException for 429 after exhausting retries
+                    if e.response.status_code == 429:
+                        retry_after = _get_retry_after_delay(e.response)
+                        print(
+                            "Rate limit (429) on POST /keys/anon - max retries exhausted",
+                            file=sys.stderr,
+                        )
+                        raise RateLimitException(
+                            "Rate limit exceeded when obtaining anonymous token",
+                            retry_after=retry_after,
+                            response=e.response,
+                        ) from None
+
+                    # Other HTTP status errors
+                    raise HttpClientException(
+                        f"Failed to obtain anonymous token: HTTP {e.response.status_code}",
+                        response=e.response,
+                        cause=e,
+                    ) from None
+                except httpx.RequestError as e:
+                    last_error = e
+                    raise HttpClientException(
+                        f"Failed to obtain anonymous token: {str(e)}",
+                        response=None,
+                        cause=e,
+                    ) from None
+
+            # Should not reach here, but handle just in case
+            if last_error:
+                raise HttpClientException(
+                    f"Failed to obtain anonymous token after {max_retries + 1} attempts: {str(last_error)}",
+                    response=None,
+                    cause=last_error,
+                ) from None
+            else:
+                raise HttpClientException(
+                    f"Failed to obtain anonymous token after {max_retries + 1} attempts",
+                    response=None,
+                )
         finally:
             temp_client.close()
 
@@ -1029,7 +1119,9 @@ class PDFDancer:
                     b'Content-Disposition: form-data; name="pdf"; filename="document.pdf"\r\n'
                 )
                 body_parts.append(b"Content-Type: application/pdf\r\n")
-                body_parts.append(b"\r\n")  # End of headers, no Content-Transfer-Encoding
+                body_parts.append(
+                    b"\r\n"
+                )  # End of headers, no Content-Transfer-Encoding
                 body_parts.append(self._pdf_bytes)
                 body_parts.append(b"\r\n")
                 body_parts.append(f"--{boundary}--\r\n".encode("utf-8"))
@@ -1042,11 +1134,17 @@ class PDFDancer:
                 original_size = len(uncompressed_body)
                 compressed_size = len(compressed_body)
                 compression_ratio = (
-                    (1 - compressed_size / original_size) * 100 if original_size > 0 else 0
+                    (1 - compressed_size / original_size) * 100
+                    if original_size > 0
+                    else 0
                 )
 
                 if DEBUG:
-                    retry_info = f" (attempt {attempt + 1}/{self._max_retries + 1})" if attempt > 0 else ""
+                    retry_info = (
+                        f" (attempt {attempt + 1}/{self._max_retries + 1})"
+                        if attempt > 0
+                        else ""
+                    )
                     print(
                         f"{time.time()}|POST /session/create{retry_info} - original size: {original_size} bytes, "
                         f"compressed size: {compressed_size} bytes, "
@@ -1083,9 +1181,47 @@ class PDFDancer:
                 return session_id
 
             except httpx.HTTPStatusError as e:
-                # HTTP status errors are not retried (these are application-level errors)
+                # Handle 429 (rate limit) with retry
+                if e.response.status_code == 429 and attempt < self._max_retries:
+                    retry_after = _get_retry_after_delay(e.response)
+                    if retry_after is not None:
+                        delay = retry_after
+                    else:
+                        # Use exponential backoff if no Retry-After header
+                        delay = self._retry_backoff_factor * (2**attempt)
+
+                    # Always log 429 to stderr for visibility
+                    print(
+                        f"Rate limit (429) on POST /session/create - retrying in {delay}s "
+                        f"(attempt {attempt + 1}/{self._max_retries})",
+                        file=sys.stderr,
+                    )
+                    if DEBUG:
+                        print(
+                            f"{time.time()}|POST /session/create - Rate limit exceeded (429), "
+                            f"retrying in {delay}s (attempt {attempt + 1}/{self._max_retries})"
+                        )
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+
+                # Other HTTP status errors are not retried (these are application-level errors)
                 self._handle_authentication_error(e.response)
                 error_message = self._extract_error_message(e.response)
+
+                # Raise RateLimitException for 429 after exhausting retries
+                if e.response.status_code == 429:
+                    retry_after = _get_retry_after_delay(e.response)
+                    print(
+                        "Rate limit (429) on POST /session/create - max retries exhausted",
+                        file=sys.stderr,
+                    )
+                    raise RateLimitException(
+                        f"Rate limit exceeded: {error_message}",
+                        retry_after=retry_after,
+                        response=e.response,
+                    ) from None
+
                 raise HttpClientException(
                     f"Failed to create session: {error_message}",
                     response=e.response,
@@ -1097,7 +1233,7 @@ class PDFDancer:
                 # Check if this is a retryable error
                 if _is_retryable_error(e) and attempt < self._max_retries:
                     # Calculate exponential backoff delay
-                    delay = self._retry_backoff_factor * (2 ** attempt)
+                    delay = self._retry_backoff_factor * (2**attempt)
                     if DEBUG:
                         print(
                             f"{time.time()}|POST /session/create - Retryable error: {str(e)}, "
@@ -1157,9 +1293,7 @@ class PDFDancer:
             except ValueError as exc:
                 raise ValidationException(str(exc)) from exc
             except TypeError:
-                raise ValidationException(
-                    f"Invalid page_size type: {type(page_size)}"
-                )
+                raise ValidationException(f"Invalid page_size type: {type(page_size)}")
 
         # Handle orientation
         if orientation is not None:
@@ -1187,7 +1321,11 @@ class PDFDancer:
                 request_body = json.dumps(request_data)
                 request_size = len(request_body.encode("utf-8"))
                 if DEBUG:
-                    retry_info = f" (attempt {attempt + 1}/{self._max_retries + 1})" if attempt > 0 else ""
+                    retry_info = (
+                        f" (attempt {attempt + 1}/{self._max_retries + 1})"
+                        if attempt > 0
+                        else ""
+                    )
                     print(
                         f"{time.time()}|POST /session/new{retry_info} - request size: {request_size} bytes"
                     )
@@ -1220,9 +1358,47 @@ class PDFDancer:
                 return session_id
 
             except httpx.HTTPStatusError as e:
-                # HTTP status errors are not retried (these are application-level errors)
+                # Handle 429 (rate limit) with retry
+                if e.response.status_code == 429 and attempt < self._max_retries:
+                    retry_after = _get_retry_after_delay(e.response)
+                    if retry_after is not None:
+                        delay = retry_after
+                    else:
+                        # Use exponential backoff if no Retry-After header
+                        delay = self._retry_backoff_factor * (2**attempt)
+
+                    # Always log 429 to stderr for visibility
+                    print(
+                        f"Rate limit (429) on POST /session/new - retrying in {delay}s "
+                        f"(attempt {attempt + 1}/{self._max_retries})",
+                        file=sys.stderr,
+                    )
+                    if DEBUG:
+                        print(
+                            f"{time.time()}|POST /session/new - Rate limit exceeded (429), "
+                            f"retrying in {delay}s (attempt {attempt + 1}/{self._max_retries})"
+                        )
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+
+                # Other HTTP status errors are not retried (these are application-level errors)
                 self._handle_authentication_error(e.response)
                 error_message = self._extract_error_message(e.response)
+
+                # Raise RateLimitException for 429 after exhausting retries
+                if e.response.status_code == 429:
+                    retry_after = _get_retry_after_delay(e.response)
+                    print(
+                        "Rate limit (429) on POST /session/new - max retries exhausted",
+                        file=sys.stderr,
+                    )
+                    raise RateLimitException(
+                        f"Rate limit exceeded: {error_message}",
+                        retry_after=retry_after,
+                        response=e.response,
+                    ) from None
+
                 raise HttpClientException(
                     f"Failed to create blank PDF session: {error_message}",
                     response=e.response,
@@ -1234,7 +1410,7 @@ class PDFDancer:
                 # Check if this is a retryable error
                 if _is_retryable_error(e) and attempt < self._max_retries:
                     # Calculate exponential backoff delay
-                    delay = self._retry_backoff_factor * (2 ** attempt)
+                    delay = self._retry_backoff_factor * (2**attempt)
                     if DEBUG:
                         print(
                             f"{time.time()}|POST /session/new - Retryable error: {str(e)}, "
@@ -1246,7 +1422,9 @@ class PDFDancer:
                 else:
                     # Non-retryable error or exhausted retries
                     raise HttpClientException(
-                        f"Failed to create blank PDF session: {str(e)}", response=None, cause=e
+                        f"Failed to create blank PDF session: {str(e)}",
+                        response=None,
+                        cause=e,
                     ) from None
 
         # Should not reach here, but handle just in case
@@ -1289,7 +1467,11 @@ class PDFDancer:
                     request_body = json.dumps(data)
                     request_size = len(request_body.encode("utf-8"))
                 if DEBUG:
-                    retry_info = f" (attempt {attempt + 1}/{self._max_retries + 1})" if attempt > 0 else ""
+                    retry_info = (
+                        f" (attempt {attempt + 1}/{self._max_retries + 1})"
+                        if attempt > 0
+                        else ""
+                    )
                     print(
                         f"{time.time()}|{method} {path}{retry_info} - request size: {request_size} bytes"
                     )
@@ -1327,9 +1509,47 @@ class PDFDancer:
                 return response
 
             except httpx.HTTPStatusError as e:
-                # HTTP status errors are not retried (these are application-level errors)
+                # Handle 429 (rate limit) with retry
+                if e.response.status_code == 429 and attempt < self._max_retries:
+                    retry_after = _get_retry_after_delay(e.response)
+                    if retry_after is not None:
+                        delay = retry_after
+                    else:
+                        # Use exponential backoff if no Retry-After header
+                        delay = self._retry_backoff_factor * (2**attempt)
+
+                    # Always log 429 to stderr for visibility
+                    print(
+                        f"Rate limit (429) on {method} {path} - retrying in {delay}s "
+                        f"(attempt {attempt + 1}/{self._max_retries})",
+                        file=sys.stderr,
+                    )
+                    if DEBUG:
+                        print(
+                            f"{time.time()}|{method} {path} - Rate limit exceeded (429), "
+                            f"retrying in {delay}s (attempt {attempt + 1}/{self._max_retries})"
+                        )
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+
+                # Other HTTP status errors are not retried (these are application-level errors)
                 self._handle_authentication_error(e.response)
                 error_message = self._extract_error_message(e.response)
+
+                # Raise RateLimitException for 429 after exhausting retries
+                if e.response.status_code == 429:
+                    retry_after = _get_retry_after_delay(e.response)
+                    print(
+                        f"Rate limit (429) on {method} {path} - max retries exhausted",
+                        file=sys.stderr,
+                    )
+                    raise RateLimitException(
+                        f"Rate limit exceeded: {error_message}",
+                        retry_after=retry_after,
+                        response=e.response,
+                    ) from None
+
                 raise HttpClientException(
                     f"API request failed: {error_message}", response=e.response, cause=e
                 ) from None
@@ -1339,7 +1559,7 @@ class PDFDancer:
                 # Check if this is a retryable error
                 if _is_retryable_error(e) and attempt < self._max_retries:
                     # Calculate exponential backoff delay
-                    delay = self._retry_backoff_factor * (2 ** attempt)
+                    delay = self._retry_backoff_factor * (2**attempt)
                     if DEBUG:
                         print(
                             f"{time.time()}|{method} {path} - Retryable error: {str(e)}, "

{pdfdancer_client_python-0.2.22.dist-info → pdfdancer_client_python-0.2.24.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.2.22
+Version: 0.2.24
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: 
@@ -207,7 +207,9 @@ License:
            limitations under the License.
         
 Project-URL: Homepage, https://www.pdfdancer.com/
-Project-URL: Repository, https://github.com/MenschMachine/pdfdancer-client-python
+Project-URL: Documentation, https://www.pdfdancer.com/
+Project-URL: Source, https://github.com/MenschMachine/pdfdancer-client-python
+Project-URL: Issues, https://github.com/MenschMachine/pdfdancer-client-python/issues
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License

{pdfdancer_client_python-0.2.22.dist-info → pdfdancer_client_python-0.2.24.dist-info}/RECORD

@@ -1,16 +1,16 @@
-pdfdancer/__init__.py,sha256=cQcdVubVoEXEFyWXtbIzXLb0OaMNm4JkOqFQpsbMysU,2307
-pdfdancer/exceptions.py,sha256=7XQum7xZj19e1__UvX0jhr5bL_FeaKVByaT0I3mjS9c,1599
+pdfdancer/__init__.py,sha256=8E5dsMRws_zZZpM0i8k3zc34wHauCFZOuVa5BkumuBE,2357
+pdfdancer/exceptions.py,sha256=mJacmUJTPGUsB8Bo_FgfeXYkvZkH5OPJCVBfilBVmQo,2058
 pdfdancer/fingerprint.py,sha256=eL3PHPgv-knMya7s95RXg3qzzpkAA1aevxqb6tuOb34,3061
 pdfdancer/image_builder.py,sha256=MdSvZYU7-tq5HcuIpj2cfsd1iJKL9nryp87pCGlMnpM,1888
 pdfdancer/models.py,sha256=feEZc7kr5aN2QgIHpayCWksPLhxJVnukkFfe_Ri1E_w,49003
 pdfdancer/page_builder.py,sha256=ecEK0lXk-7CoWEDOftZ-GwgRfNu5h7AD_J__LNkxJwI,3092
 pdfdancer/paragraph_builder.py,sha256=yXdn2hoxpJYcUVAmSEOgoq-ApGIe9k9GWkokIIQWIJA,20489
 pdfdancer/path_builder.py,sha256=2w0LPJo1u8bSjGAbYevTtOF4VD8M9B4SLe_wSLIYJx8,23917
-pdfdancer/pdfdancer_v1.py,sha256=rh3W0YYWOlF_9Q598y1tRZ5JD_WcAj9IZT8IuWS-A6Y,108560
+pdfdancer/pdfdancer_v1.py,sha256=pjNwBHF_tPCXv7fnjxcm-6m5g_u91773rtvz9j_W9Yg,118088
 pdfdancer/types.py,sha256=9F5LqgNVz48s0Q6lGgOcIfIbvE3vkPI_Vr4fOQqFk2k,13225
-pdfdancer_client_python-0.2.22.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-pdfdancer_client_python-0.2.22.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
-pdfdancer_client_python-0.2.22.dist-info/METADATA,sha256=OXKDeRe_8huC1COwCQiHyvQPAt-oU405iO1VNVanXBk,24668
-pdfdancer_client_python-0.2.22.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pdfdancer_client_python-0.2.22.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
-pdfdancer_client_python-0.2.22.dist-info/RECORD,,
+pdfdancer_client_python-0.2.24.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+pdfdancer_client_python-0.2.24.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
+pdfdancer_client_python-0.2.24.dist-info/METADATA,sha256=_uluVSNqy7WP2TZQhTj97nYRtDcOmxElytYGocW71wQ,24804
+pdfdancer_client_python-0.2.24.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdfdancer_client_python-0.2.24.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
+pdfdancer_client_python-0.2.24.dist-info/RECORD,,