thordata-sdk 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

thordata/enums.py

@@ -7,15 +7,16 @@ making it easier to discover available options via IDE autocomplete.
 
 from enum import Enum, IntEnum
 
-
 # =============================================================================
 # Continent Enum
 # =============================================================================
 
+
 class Continent(str, Enum):
     """
     Continent codes for geo-targeting.
     """
+
     AFRICA = "af"
     ANTARCTICA = "an"
     ASIA = "as"
@@ -29,10 +30,12 @@ class Continent(str, Enum):
 # Proxy Host Enum
 # =============================================================================
 
+
 class ProxyHost(str, Enum):
     """
     Available proxy gateway hosts.
     """
+
     DEFAULT = "pr.thordata.net"
     NORTH_AMERICA = "t.na.thordata.net"
     EUROPE = "t.eu.thordata.net"
@@ -43,6 +46,7 @@ class ProxyPort(IntEnum):
     """
     Available proxy gateway ports.
     """
+
     DEFAULT = 9999
     MOBILE = 5555
     DATACENTER = 7777
@@ -54,10 +58,12 @@ class ProxyPort(IntEnum):
 # Search Engine Enums
 # =============================================================================
 
+
 class Engine(str, Enum):
     """
     Supported search engines for SERP API.
     """
+
     GOOGLE = "google"
     BING = "bing"
     YANDEX = "yandex"
@@ -71,6 +77,7 @@ class GoogleSearchType(str, Enum):
     """
     Search types specific to Google.
     """
+
     SEARCH = "search"
     MAPS = "maps"
     SHOPPING = "shopping"
@@ -88,6 +95,7 @@ class BingSearchType(str, Enum):
     """
     Search types specific to Bing.
     """
+
     SEARCH = "search"
     IMAGES = "images"
     VIDEOS = "videos"
@@ -99,6 +107,7 @@ class Device(str, Enum):
     """
     Device types for SERP API.
     """
+
     DESKTOP = "desktop"
     MOBILE = "mobile"
     TABLET = "tablet"
@@ -108,6 +117,7 @@ class TimeRange(str, Enum):
     """
     Time range filters for search results.
     """
+
     HOUR = "hour"
     DAY = "day"
     WEEK = "week"
@@ -119,10 +129,12 @@ class TimeRange(str, Enum):
 # Proxy Enums
 # =============================================================================
 
+
 class ProxyType(IntEnum):
     """
     Types of proxy networks available.
     """
+
     RESIDENTIAL = 1
     UNLIMITED = 2
     DATACENTER = 3
@@ -134,6 +146,7 @@ class SessionType(str, Enum):
     """
     Proxy session types for connection persistence.
     """
+
     ROTATING = "rotating"
     STICKY = "sticky"
 
@@ -142,10 +155,12 @@ class SessionType(str, Enum):
 # Output Format Enums
 # =============================================================================
 
+
 class OutputFormat(str, Enum):
     """
     Output formats for Universal Scraping API.
     """
+
     HTML = "html"
     PNG = "png"
     PDF = "pdf"
@@ -157,6 +172,7 @@ class DataFormat(str, Enum):
     """
     Data formats for task result download.
     """
+
     JSON = "json"
     CSV = "csv"
     XLSX = "xlsx"
@@ -166,10 +182,12 @@ class DataFormat(str, Enum):
 # Task Status Enums
 # =============================================================================
 
+
 class TaskStatus(str, Enum):
     """
     Possible statuses for async scraping tasks.
     """
+
     PENDING = "pending"
     RUNNING = "running"
     READY = "ready"
@@ -184,8 +202,12 @@ class TaskStatus(str, Enum):
     def is_terminal(cls, status: "TaskStatus") -> bool:
         """Check if a status is terminal (no more updates expected)."""
         return status in {
-            cls.READY, cls.SUCCESS, cls.FINISHED,
-            cls.FAILED, cls.ERROR, cls.CANCELLED
+            cls.READY,
+            cls.SUCCESS,
+            cls.FINISHED,
+            cls.FAILED,
+            cls.ERROR,
+            cls.CANCELLED,
         }
 
     @classmethod
@@ -203,10 +225,12 @@ class TaskStatus(str, Enum):
 # Country Enum (常用国家)
 # =============================================================================
 
+
 class Country(str, Enum):
     """
     Common country codes for geo-targeting.
     """
+
     # North America
     US = "us"
     CA = "ca"
@@ -276,14 +300,16 @@ class Country(str, Enum):
 # Helper Functions
 # =============================================================================
 
-def normalize_enum_value(value, enum_class: type) -> str:
+
+def normalize_enum_value(value: object, enum_class: type) -> str:
     """
     Safely convert an enum or string to its string value.
     """
     if isinstance(value, enum_class):
-        return value.value
+        # value is an enum member, get its .value
+        return str(getattr(value, "value", value)).lower()
     if isinstance(value, str):
         return value.lower()
     raise TypeError(
         f"Expected {enum_class.__name__} or str, got {type(value).__name__}"
-    )
+    )

thordata/exceptions.py

@@ -17,14 +17,14 @@ from __future__ import annotations
 
 from typing import Any, Optional, Set
 
-
 # =============================================================================
 # Base Exception
 # =============================================================================
 
+
 class ThordataError(Exception):
     """Base error for all Thordata SDK issues."""
-    
+
     def __init__(self, message: str) -> None:
         super().__init__(message)
         self.message = message
@@ -34,14 +34,16 @@ class ThordataError(Exception):
 # Configuration Errors
 # =============================================================================
 
+
 class ThordataConfigError(ThordataError):
     """
     Raised when the SDK is misconfigured.
-    
+
     Examples:
         - Missing required tokens
         - Invalid parameter combinations
     """
+
     pass
 
 
@@ -49,13 +51,14 @@ class ThordataConfigError(ThordataError):
 # Network Errors (Usually Retryable)
 # =============================================================================
 
+
 class ThordataNetworkError(ThordataError):
     """
     Raised when a network-level error occurs.
-    
+
     This is typically retryable (DNS failures, connection refused, etc.)
     """
-    
+
     def __init__(
         self,
         message: str,
@@ -69,9 +72,10 @@ class ThordataNetworkError(ThordataError):
 class ThordataTimeoutError(ThordataNetworkError):
     """
     Raised when a request times out.
-    
+
     This is typically retryable.
     """
+
     pass
 
 
@@ -79,6 +83,7 @@ class ThordataTimeoutError(ThordataNetworkError):
 # API Errors
 # =============================================================================
 
+
 class ThordataAPIError(ThordataError):
     """
     Generic API error raised when the backend returns a non-success code
@@ -128,14 +133,14 @@ class ThordataAPIError(ThordataError):
 class ThordataAuthError(ThordataAPIError):
     """
     Authentication or authorization failures.
-    
+
     HTTP Status: 401, 403
     Common causes:
         - Invalid or expired token
         - Insufficient permissions
         - IP not whitelisted
     """
-    
+
     HTTP_STATUS_CODES = {401, 403}
 
     @property
@@ -146,17 +151,17 @@ class ThordataAuthError(ThordataAPIError):
 class ThordataRateLimitError(ThordataAPIError):
     """
     Rate limiting or quota/balance issues.
-    
+
     HTTP Status: 429, 402
     Common causes:
         - Too many requests per second
         - Insufficient account balance
         - Quota exceeded
-    
+
     Attributes:
         retry_after: Suggested seconds to wait before retrying (if provided).
     """
-    
+
     HTTP_STATUS_CODES = {429, 402}
 
     def __init__(
@@ -178,11 +183,11 @@ class ThordataRateLimitError(ThordataAPIError):
 class ThordataServerError(ThordataAPIError):
     """
     Server-side errors (5xx).
-    
+
     HTTP Status: 500, 502, 503, 504
     These are typically transient and safe to retry.
     """
-    
+
     HTTP_STATUS_CODES = {500, 502, 503, 504}
 
     @property
@@ -193,14 +198,14 @@ class ThordataServerError(ThordataAPIError):
 class ThordataValidationError(ThordataAPIError):
     """
     Request validation errors.
-    
+
     HTTP Status: 400, 422
     Common causes:
         - Invalid parameters
         - Missing required fields
         - Malformed request body
     """
-    
+
     HTTP_STATUS_CODES = {400, 422}
 
     @property
@@ -208,10 +213,27 @@ class ThordataValidationError(ThordataAPIError):
         return False  # Bad requests shouldn't be retried
 
 
+class ThordataNotCollectedError(ThordataAPIError):
+    """
+    The request was accepted but no valid data could be collected/parsed.
+
+    API Code: 300
+    Billing: Not billed (per Thordata billing rules).
+    This error is often transient and typically safe to retry.
+    """
+
+    HTTP_STATUS_CODES = {300}
+
+    @property
+    def is_retryable(self) -> bool:
+        return True
+
+
 # =============================================================================
 # Exception Factory
 # =============================================================================
 
+
 def raise_for_code(
     message: str,
     *,
@@ -222,17 +244,17 @@ def raise_for_code(
 ) -> None:
     """
     Factory function to raise the appropriate exception based on status/code.
-    
+
     This centralizes the error-mapping logic that was previously duplicated
     across multiple methods.
-    
+
     Args:
         message: Human-readable error message.
         status_code: HTTP status code (if available).
         code: Application-level code from API response.
         payload: Raw API response payload.
         request_id: Optional request ID for debugging.
-    
+
     Raises:
         ThordataAuthError: For 401/403 codes.
         ThordataRateLimitError: For 429/402 codes.
@@ -242,18 +264,22 @@ def raise_for_code(
     """
     # Use the code from payload if status_code not available
     effective_code = status_code or code
-    
+
     kwargs = {
         "status_code": status_code,
         "code": code,
         "payload": payload,
         "request_id": request_id,
     }
-    
+
+    # Not collected (often retryable, not billed)
+    if effective_code in ThordataNotCollectedError.HTTP_STATUS_CODES:
+        raise ThordataNotCollectedError(message, **kwargs)
+
     # Auth errors
     if effective_code in ThordataAuthError.HTTP_STATUS_CODES:
         raise ThordataAuthError(message, **kwargs)
-    
+
     # Rate limit errors
     if effective_code in ThordataRateLimitError.HTTP_STATUS_CODES:
         # Try to extract retry_after from payload
@@ -261,15 +287,15 @@ def raise_for_code(
         if isinstance(payload, dict):
             retry_after = payload.get("retry_after")
         raise ThordataRateLimitError(message, retry_after=retry_after, **kwargs)
-    
+
     # Server errors
     if effective_code is not None and 500 <= effective_code < 600:
         raise ThordataServerError(message, **kwargs)
-    
+
     # Validation errors
     if effective_code in ThordataValidationError.HTTP_STATUS_CODES:
         raise ThordataValidationError(message, **kwargs)
-    
+
     # Generic API error
     raise ThordataAPIError(message, **kwargs)
 
@@ -278,38 +304,41 @@ def raise_for_code(
 # Retry Helper
 # =============================================================================
 
+
 def is_retryable_exception(exc: Exception) -> bool:
     """
     Check if an exception is safe to retry.
-    
+
     Args:
         exc: The exception to check.
-    
+
     Returns:
         True if the exception is typically safe to retry.
     """
     # Network errors are retryable
     if isinstance(exc, ThordataNetworkError):
         return True
-    
+
     # Check API errors with is_retryable property
     if isinstance(exc, ThordataAPIError):
         return exc.is_retryable
-    
+
     # requests/aiohttp specific exceptions
     # (imported dynamically to avoid hard dependency)
     try:
         import requests
+
         if isinstance(exc, (requests.Timeout, requests.ConnectionError)):
             return True
     except ImportError:
         pass
-    
+
     try:
         import aiohttp
+
         if isinstance(exc, (aiohttp.ClientError, aiohttp.ServerTimeoutError)):
             return True
     except ImportError:
         pass
-    
-    return False
+
+    return False