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

thordata/enums.py

@@ -1,25 +1,315 @@
-# src/thordata/enums.py
+"""
+Enumerations for the Thordata Python SDK.
+
+This module provides type-safe enumerations for all Thordata API parameters,
+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"
+    EUROPE = "eu"
+    NORTH_AMERICA = "na"
+    OCEANIA = "oc"
+    SOUTH_AMERICA = "sa"
+
+
+# =============================================================================
+# 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"
+    GATE = "gate.thordata.com"
+
+
+class ProxyPort(IntEnum):
+    """
+    Available proxy gateway ports.
+    """
+
+    DEFAULT = 9999
+    MOBILE = 5555
+    DATACENTER = 7777
+    ISP = 6666
+    ALTERNATIVE = 22225
+
+
+# =============================================================================
+# Search Engine Enums
+# =============================================================================
 
-from enum import Enum
 
 class Engine(str, Enum):
     """
-    Supported Search Engines for SERP API.
+    Supported search engines for SERP API.
     """
+
     GOOGLE = "google"
     BING = "bing"
     YANDEX = "yandex"
     DUCKDUCKGO = "duckduckgo"
     BAIDU = "baidu"
+    YAHOO = "yahoo"
+    NAVER = "naver"
+
 
 class GoogleSearchType(str, Enum):
     """
-    Specific search types for Google Engine.
+    Search types specific to Google.
+    """
+
+    SEARCH = "search"
+    MAPS = "maps"
+    SHOPPING = "shopping"
+    NEWS = "news"
+    IMAGES = "images"
+    VIDEOS = "videos"
+    SCHOLAR = "scholar"
+    PATENTS = "patents"
+    JOBS = "jobs"
+    FLIGHTS = "flights"
+    FINANCE = "finance"
+
+
+class BingSearchType(str, Enum):
+    """
+    Search types specific to Bing.
+    """
+
+    SEARCH = "search"
+    IMAGES = "images"
+    VIDEOS = "videos"
+    NEWS = "news"
+    MAPS = "maps"
+
+
+class Device(str, Enum):
+    """
+    Device types for SERP API.
+    """
+
+    DESKTOP = "desktop"
+    MOBILE = "mobile"
+    TABLET = "tablet"
+
+
+class TimeRange(str, Enum):
+    """
+    Time range filters for search results.
+    """
+
+    HOUR = "hour"
+    DAY = "day"
+    WEEK = "week"
+    MONTH = "month"
+    YEAR = "year"
+
+
+# =============================================================================
+# Proxy Enums
+# =============================================================================
+
+
+class ProxyType(IntEnum):
+    """
+    Types of proxy networks available.
+    """
+
+    RESIDENTIAL = 1
+    UNLIMITED = 2
+    DATACENTER = 3
+    ISP = 4
+    MOBILE = 5
+
+
+class SessionType(str, Enum):
+    """
+    Proxy session types for connection persistence.
+    """
+
+    ROTATING = "rotating"
+    STICKY = "sticky"
+
+
+# =============================================================================
+# Output Format Enums
+# =============================================================================
+
+
+class OutputFormat(str, Enum):
+    """
+    Output formats for Universal Scraping API.
+    """
+
+    HTML = "html"
+    PNG = "png"
+    PDF = "pdf"
+    MARKDOWN = "markdown"
+    TEXT = "text"
+
+
+class DataFormat(str, Enum):
+    """
+    Data formats for task result download.
+    """
+
+    JSON = "json"
+    CSV = "csv"
+    XLSX = "xlsx"
+
+
+# =============================================================================
+# Task Status Enums
+# =============================================================================
+
+
+class TaskStatus(str, Enum):
+    """
+    Possible statuses for async scraping tasks.
+    """
+
+    PENDING = "pending"
+    RUNNING = "running"
+    READY = "ready"
+    SUCCESS = "success"
+    FINISHED = "finished"
+    FAILED = "failed"
+    ERROR = "error"
+    CANCELLED = "cancelled"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    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,
+        }
+
+    @classmethod
+    def is_success(cls, status: "TaskStatus") -> bool:
+        """Check if a status indicates success."""
+        return status in {cls.READY, cls.SUCCESS, cls.FINISHED}
+
+    @classmethod
+    def is_failure(cls, status: "TaskStatus") -> bool:
+        """Check if a status indicates failure."""
+        return status in {cls.FAILED, cls.ERROR}
+
+
+# =============================================================================
+# Country Enum (常用国家)
+# =============================================================================
+
+
+class Country(str, Enum):
+    """
+    Common country codes for geo-targeting.
+    """
+
+    # North America
+    US = "us"
+    CA = "ca"
+    MX = "mx"
+
+    # Europe
+    GB = "gb"
+    DE = "de"
+    FR = "fr"
+    ES = "es"
+    IT = "it"
+    NL = "nl"
+    PL = "pl"
+    RU = "ru"
+    UA = "ua"
+    SE = "se"
+    NO = "no"
+    DK = "dk"
+    FI = "fi"
+    CH = "ch"
+    AT = "at"
+    BE = "be"
+    PT = "pt"
+    IE = "ie"
+    CZ = "cz"
+    GR = "gr"
+
+    # Asia Pacific
+    CN = "cn"
+    JP = "jp"
+    KR = "kr"
+    IN = "in"
+    AU = "au"
+    NZ = "nz"
+    SG = "sg"
+    HK = "hk"
+    TW = "tw"
+    TH = "th"
+    VN = "vn"
+    ID = "id"
+    MY = "my"
+    PH = "ph"
+    PK = "pk"
+    BD = "bd"
+
+    # South America
+    BR = "br"
+    AR = "ar"
+    CL = "cl"
+    CO = "co"
+    PE = "pe"
+    VE = "ve"
+
+    # Middle East & Africa
+    AE = "ae"
+    SA = "sa"
+    IL = "il"
+    TR = "tr"
+    ZA = "za"
+    EG = "eg"
+    NG = "ng"
+    KE = "ke"
+    MA = "ma"
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def normalize_enum_value(value: object, enum_class: type) -> str:
+    """
+    Safely convert an enum or string to its string value.
     """
-    SEARCH = "search"      # Default web search
-    MAPS = "maps"          # Google Maps
-    SHOPPING = "shopping"  # Google Shopping
-    NEWS = "news"          # Google News
-    IMAGES = "images"      # Google Images
-    VIDEOS = "videos"      # Google Videos
-    # Users can pass other strings manually if needed
+    if isinstance(value, enum_class):
+        # 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

@@ -0,0 +1,344 @@
+"""
+Custom exception types for the Thordata Python SDK.
+
+Exception Hierarchy:
+    ThordataError (base)
+    ├── ThordataConfigError      - Configuration/initialization issues
+    ├── ThordataNetworkError     - Network connectivity issues (retryable)
+    │   └── ThordataTimeoutError - Request timeout (retryable)
+    └── ThordataAPIError         - API returned an error
+        ├── ThordataAuthError        - 401/403 authentication issues
+        ├── ThordataRateLimitError   - 429/402 rate limit/quota issues
+        ├── ThordataServerError      - 5xx server errors (retryable)
+        └── ThordataValidationError  - 400 bad request / validation errors
+"""
+
+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
+
+
+# =============================================================================
+# Configuration Errors
+# =============================================================================
+
+
+class ThordataConfigError(ThordataError):
+    """
+    Raised when the SDK is misconfigured.
+
+    Examples:
+        - Missing required tokens
+        - Invalid parameter combinations
+    """
+
+    pass
+
+
+# =============================================================================
+# 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,
+        *,
+        original_error: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message)
+        self.original_error = original_error
+
+
+class ThordataTimeoutError(ThordataNetworkError):
+    """
+    Raised when a request times out.
+
+    This is typically retryable.
+    """
+
+    pass
+
+
+# =============================================================================
+# API Errors
+# =============================================================================
+
+
+class ThordataAPIError(ThordataError):
+    """
+    Generic API error raised when the backend returns a non-success code
+    or an unexpected response payload.
+
+    Attributes:
+        message:      Human-readable error message.
+        status_code:  HTTP status code from the response (e.g., 401, 500).
+        code:         Application-level code from the Thordata API JSON response.
+        payload:      Raw payload (dict/str) returned by the API.
+        request_id:   Optional request ID for debugging with support.
+    """
+
+    # HTTP status codes that indicate this error type
+    HTTP_STATUS_CODES: Set[int] = set()
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[int] = None,
+        payload: Any = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.payload = payload
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={self.message!r}, "
+            f"status_code={self.status_code}, "
+            f"code={self.code}, "
+            f"request_id={self.request_id!r})"
+        )
+
+    @property
+    def is_retryable(self) -> bool:
+        """Whether this error is typically safe to retry."""
+        return False
+
+
+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
+    def is_retryable(self) -> bool:
+        return False  # Auth errors shouldn't be retried
+
+
+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__(
+        self,
+        message: str,
+        *,
+        retry_after: Optional[int] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+    @property
+    def is_retryable(self) -> bool:
+        # Rate limits are retryable after waiting
+        return True
+
+
+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
+    def is_retryable(self) -> bool:
+        return True
+
+
+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
+    def is_retryable(self) -> bool:
+        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,
+    *,
+    status_code: Optional[int] = None,
+    code: Optional[int] = None,
+    payload: Any = None,
+    request_id: Optional[str] = None,
+) -> 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.
+        ThordataServerError: For 5xx codes.
+        ThordataValidationError: For 400/422 codes.
+        ThordataAPIError: For all other error codes.
+    """
+    # 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
+        retry_after = None
+        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)
+
+
+# =============================================================================
+# 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