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

thordata/__init__.py

@@ -1,16 +1,138 @@
-# src/thordata/__init__.py
+"""
+Thordata Python SDK
 
+Official Python client for Thordata's Proxy Network, SERP API,
+Universal Scraping API (Web Unlocker), and Web Scraper API.
+
+Basic Usage:
+    >>> from thordata import ThordataClient
+    >>> 
+    >>> client = ThordataClient(
+    ...     scraper_token="your_token",
+    ...     public_token="your_public_token",
+    ...     public_key="your_public_key"
+    ... )
+    >>> 
+    >>> # Proxy request
+    >>> response = client.get("https://httpbin.org/ip")
+    >>> 
+    >>> # SERP search
+    >>> results = client.serp_search("python tutorial", engine="google")
+    >>> 
+    >>> # Universal scrape
+    >>> html = client.universal_scrape("https://example.com", js_render=True)
+
+Async Usage:
+    >>> from thordata import AsyncThordataClient
+    >>> import asyncio
+    >>> 
+    >>> async def main():
+    ...     async with AsyncThordataClient(
+    ...         scraper_token="your_token"
+    ...     ) as client:
+    ...         response = await client.get("https://httpbin.org/ip")
+    >>> 
+    >>> asyncio.run(main())
+"""
+
+__version__ = "0.4.0"
+__author__ = "Thordata Developer Team"
+__email__ = "support@thordata.com"
+
+# Main clients
 from .client import ThordataClient
 from .async_client import AsyncThordataClient
-from .enums import Engine, GoogleSearchType
 
-# Package version
-__version__ = "0.3.1"
+# Enums
+from .enums import (
+    Engine,
+    GoogleSearchType,
+    BingSearchType,
+    ProxyType,
+    SessionType,
+    Continent,
+    Country,
+    OutputFormat,
+    DataFormat,
+    TaskStatus,
+    Device,
+    TimeRange,
+    ProxyHost,
+    ProxyPort,
+)
+
+# Models
+from .models import (
+    ProxyConfig,
+    ProxyProduct,
+    StickySession,
+    SerpRequest,
+    UniversalScrapeRequest,
+    ScraperTaskConfig,
+    TaskStatusResponse,
+)
+
+# Exceptions
+from .exceptions import (
+    ThordataError,
+    ThordataConfigError,
+    ThordataNetworkError,
+    ThordataTimeoutError,
+    ThordataAPIError,
+    ThordataAuthError,
+    ThordataRateLimitError,
+    ThordataServerError,
+    ThordataValidationError,
+)
+
+# Retry utilities
+from .retry import RetryConfig
 
-# Explicitly export classes to simplify user imports
+# Public API
 __all__ = [
-    "ThordataClient", 
-    "AsyncThordataClient", 
-    "Engine", 
-    "GoogleSearchType"
+    # Version
+    "__version__",
+    
+    # Clients
+    "ThordataClient",
+    "AsyncThordataClient",
+    
+    # Enums
+    "Engine",
+    "GoogleSearchType",
+    "BingSearchType",
+    "ProxyType",
+    "SessionType",
+    "Continent",
+    "Country",
+    "OutputFormat",
+    "DataFormat",
+    "TaskStatus",
+    "Device",
+    "TimeRange",
+    "ProxyHost",
+    "ProxyPort",
+    
+    # Models
+    "ProxyConfig",
+    "ProxyProduct",
+    "StickySession",
+    "SerpRequest",
+    "UniversalScrapeRequest",
+    "ScraperTaskConfig",
+    "TaskStatusResponse",
+    
+    # Exceptions
+    "ThordataError",
+    "ThordataConfigError",
+    "ThordataNetworkError",
+    "ThordataTimeoutError",
+    "ThordataAPIError",
+    "ThordataAuthError",
+    "ThordataRateLimitError",
+    "ThordataServerError",
+    "ThordataValidationError",
+    
+    # Retry
+    "RetryConfig",
 ]

thordata/_utils.py

@@ -0,0 +1,126 @@
+"""
+Internal utility functions for the Thordata Python SDK.
+
+These are not part of the public API and may change without notice.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from typing import Any, Dict, Optional, Union
+
+logger = logging.getLogger(__name__)
+
+
+def parse_json_response(data: Any) -> Any:
+    """
+    Parse a response that might be double-encoded JSON.
+    
+    Some API endpoints return JSON as a string inside JSON.
+    
+    Args:
+        data: The response data to parse.
+    
+    Returns:
+        Parsed data.
+    """
+    if isinstance(data, str):
+        try:
+            return json.loads(data)
+        except json.JSONDecodeError:
+            return data
+    return data
+
+
+def decode_base64_image(png_str: str) -> bytes:
+    """
+    Decode a base64-encoded PNG image.
+    
+    Handles Data URI scheme (data:image/png;base64,...) and fixes padding.
+    
+    Args:
+        png_str: Base64-encoded string, possibly with Data URI prefix.
+    
+    Returns:
+        Decoded PNG bytes.
+    
+    Raises:
+        ValueError: If the string is empty or cannot be decoded.
+    """
+    if not png_str:
+        raise ValueError("Empty PNG data received")
+    
+    # Remove Data URI scheme if present
+    if "," in png_str:
+        png_str = png_str.split(",", 1)[1]
+    
+    # Clean up whitespace
+    png_str = png_str.replace("\n", "").replace("\r", "").replace(" ", "")
+    
+    # Fix Base64 padding
+    missing_padding = len(png_str) % 4
+    if missing_padding:
+        png_str += "=" * (4 - missing_padding)
+    
+    try:
+        return base64.b64decode(png_str)
+    except Exception as e:
+        raise ValueError(f"Failed to decode base64 image: {e}")
+
+
+def build_auth_headers(token: str) -> Dict[str, str]:
+    """
+    Build authorization headers for API requests.
+    
+    Args:
+        token: The scraper token.
+    
+    Returns:
+        Headers dict with Authorization and Content-Type.
+    """
+    return {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/x-www-form-urlencoded",
+    }
+
+
+def build_public_api_headers(public_token: str, public_key: str) -> Dict[str, str]:
+    """
+    Build headers for public API requests (task status, locations, etc.)
+    
+    Args:
+        public_token: The public API token.
+        public_key: The public API key.
+    
+    Returns:
+        Headers dict with token, key, and Content-Type.
+    """
+    return {
+        "token": public_token,
+        "key": public_key,
+        "Content-Type": "application/x-www-form-urlencoded",
+    }
+
+
+def extract_error_message(payload: Any) -> str:
+    """
+    Extract a human-readable error message from an API response.
+    
+    Args:
+        payload: The API response payload.
+    
+    Returns:
+        Error message string.
+    """
+    if isinstance(payload, dict):
+        # Try common error message fields
+        for key in ("msg", "message", "error", "detail", "description"):
+            if key in payload:
+                return str(payload[key])
+        
+        # Fall back to full payload
+        return str(payload)
+    
+    return str(payload)