thordata-sdk 0.6.0__tar.gz → 0.8.0__tar.gz

thordata_sdk-0.8.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: thordata-sdk
+Version: 0.8.0
+Summary: The Official Python SDK for Thordata - AI Data Infrastructure & Proxy Network.
+Author-email: Thordata Developer Team <support@thordata.com>
+License: MIT
+Project-URL: Homepage, https://www.thordata.com
+Project-URL: Documentation, https://github.com/Thordata/thordata-python-sdk#readme
+Project-URL: Source, https://github.com/Thordata/thordata-python-sdk
+Project-URL: Tracker, https://github.com/Thordata/thordata-python-sdk/issues
+Project-URL: Changelog, https://github.com/Thordata/thordata-python-sdk/blob/main/CHANGELOG.md
+Keywords: web scraping,proxy,residential proxy,datacenter proxy,ai,llm,data-mining,serp,thordata,web scraper,anti-bot bypass
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-httpserver>=1.0.0; extra == "dev"
+Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-requests>=2.28.0; extra == "dev"
+Requires-Dist: aioresponses>=0.7.6; extra == "dev"
+Dynamic: license-file
+
+# Thordata Python SDK
+
+<div align="center">
+
+**Official Python client for Thordata's Proxy Network, SERP API, Web Unlocker, and Web Scraper API.**
+
+*Async-ready, type-safe, built for AI agents and large-scale data collection.*
+
+[![PyPI](https://img.shields.io/pypi/v/thordata-sdk?color=blue)](https://pypi.org/project/thordata-sdk/)
+[![Python](https://img.shields.io/badge/python-3.9+-blue)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+[Documentation](https://doc.thordata.com) • [Dashboard](https://www.thordata.com) • [Examples](examples/)
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🌐 **Proxy Network**: Residential, Mobile, Datacenter, ISP proxies with geo-targeting
+- 🔍 **SERP API**: Google, Bing, Yandex, DuckDuckGo search results
+- 🔓 **Web Unlocker**: Bypass Cloudflare, CAPTCHAs, anti-bot systems
+- 🕷️ **Web Scraper API**: Async task-based scraping (Text & Video/Audio)
+- 📊 **Account Management**: Usage stats, sub-users, IP whitelist
+- ⚡ **Async Support**: Full async/await support with aiohttp
+- 🔄 **Auto Retry**: Configurable retry with exponential backoff
+
+---
+
+## 📦 Installation
+
+```bash
+pip install thordata-sdk
+```
+
+---
+
+## 🔐 Configuration
+
+Set environment variables:
+
+```bash
+# Required for Scraper APIs (SERP, Universal, Tasks)
+export THORDATA_SCRAPER_TOKEN=your_token
+
+# Required for Public/Location APIs (Dashboard -> My Account)
+export THORDATA_PUBLIC_TOKEN=your_public_token
+export THORDATA_PUBLIC_KEY=your_public_key
+
+# Required for Public API NEW (Dashboard -> Public API NEW)
+# If not set, SDK falls back to PUBLIC_TOKEN/KEY
+export THORDATA_SIGN=your_sign
+export THORDATA_API_KEY=your_api_key
+```
+
+---
+
+## 🚀 Quick Start
+
+```python
+from thordata import ThordataClient, Engine
+
+# Initialize (reads from env vars)
+client = ThordataClient(
+    scraper_token="your_token", 
+    public_token="pub_token", 
+    public_key="pub_key"
+)
+
+# SERP Search
+results = client.serp_search("python tutorial", engine=Engine.GOOGLE)
+print(f"Found {len(results.get('organic', []))} results")
+
+# Universal Scrape
+html = client.universal_scrape("https://httpbin.org/html")
+print(html[:100])
+```
+
+---
+
+## 📖 Feature Guide
+
+### SERP API
+
+```python
+from thordata import SerpRequest
+
+# Advanced search
+results = client.serp_search_advanced(SerpRequest(
+    query="pizza",
+    engine="google_local",
+    country="us",
+    location="New York",
+    num=10
+))
+```
+
+### Web Scraper API (Async Tasks)
+
+**Create Task:**
+```python
+task_id = client.create_scraper_task(
+    file_name="my_task",
+    spider_id="universal",
+    spider_name="universal",
+    parameters={"url": "https://example.com"}
+)
+```
+
+**Video Download (New):**
+```python
+from thordata import CommonSettings
+
+task_id = client.create_video_task(
+    file_name="{{VideoID}}",
+    spider_id="youtube_video_by-url",
+    spider_name="youtube.com",
+    parameters={"url": "https://youtube.com/watch?v=..."},
+    common_settings=CommonSettings(resolution="1080p")
+)
+```
+
+**Wait & Download:**
+```python
+status = client.wait_for_task(task_id)
+if status == "ready":
+    url = client.get_task_result(task_id)
+    print(url)
+```
+
+### Account Management
+
+```python
+# Usage Statistics
+stats = client.get_usage_statistics("2024-01-01", "2024-01-31")
+print(f"Balance: {stats.balance_gb():.2f} GB")
+
+# Proxy Users
+users = client.list_proxy_users()
+print(f"Sub-users: {users.user_count}")
+
+# Whitelist IP
+client.add_whitelist_ip("1.2.3.4")
+```
+
+### Proxy Network
+
+```python
+from thordata import ProxyConfig
+
+# Generate Proxy URL
+proxy_url = client.build_proxy_url(
+    username="proxy_user",
+    password="proxy_pass",
+    country="us",
+    city="ny"
+)
+
+# Use with requests
+import requests
+requests.get("https://httpbin.org/ip", proxies={"http": proxy_url, "https": proxy_url})
+```
+
+---
+
+## 📄 License
+
+MIT License

thordata_sdk-0.8.0/README.md

@@ -0,0 +1,169 @@
+# Thordata Python SDK
+
+<div align="center">
+
+**Official Python client for Thordata's Proxy Network, SERP API, Web Unlocker, and Web Scraper API.**
+
+*Async-ready, type-safe, built for AI agents and large-scale data collection.*
+
+[![PyPI](https://img.shields.io/pypi/v/thordata-sdk?color=blue)](https://pypi.org/project/thordata-sdk/)
+[![Python](https://img.shields.io/badge/python-3.9+-blue)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+[Documentation](https://doc.thordata.com) • [Dashboard](https://www.thordata.com) • [Examples](examples/)
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🌐 **Proxy Network**: Residential, Mobile, Datacenter, ISP proxies with geo-targeting
+- 🔍 **SERP API**: Google, Bing, Yandex, DuckDuckGo search results
+- 🔓 **Web Unlocker**: Bypass Cloudflare, CAPTCHAs, anti-bot systems
+- 🕷️ **Web Scraper API**: Async task-based scraping (Text & Video/Audio)
+- 📊 **Account Management**: Usage stats, sub-users, IP whitelist
+- ⚡ **Async Support**: Full async/await support with aiohttp
+- 🔄 **Auto Retry**: Configurable retry with exponential backoff
+
+---
+
+## 📦 Installation
+
+```bash
+pip install thordata-sdk
+```
+
+---
+
+## 🔐 Configuration
+
+Set environment variables:
+
+```bash
+# Required for Scraper APIs (SERP, Universal, Tasks)
+export THORDATA_SCRAPER_TOKEN=your_token
+
+# Required for Public/Location APIs (Dashboard -> My Account)
+export THORDATA_PUBLIC_TOKEN=your_public_token
+export THORDATA_PUBLIC_KEY=your_public_key
+
+# Required for Public API NEW (Dashboard -> Public API NEW)
+# If not set, SDK falls back to PUBLIC_TOKEN/KEY
+export THORDATA_SIGN=your_sign
+export THORDATA_API_KEY=your_api_key
+```
+
+---
+
+## 🚀 Quick Start
+
+```python
+from thordata import ThordataClient, Engine
+
+# Initialize (reads from env vars)
+client = ThordataClient(
+    scraper_token="your_token", 
+    public_token="pub_token", 
+    public_key="pub_key"
+)
+
+# SERP Search
+results = client.serp_search("python tutorial", engine=Engine.GOOGLE)
+print(f"Found {len(results.get('organic', []))} results")
+
+# Universal Scrape
+html = client.universal_scrape("https://httpbin.org/html")
+print(html[:100])
+```
+
+---
+
+## 📖 Feature Guide
+
+### SERP API
+
+```python
+from thordata import SerpRequest
+
+# Advanced search
+results = client.serp_search_advanced(SerpRequest(
+    query="pizza",
+    engine="google_local",
+    country="us",
+    location="New York",
+    num=10
+))
+```
+
+### Web Scraper API (Async Tasks)
+
+**Create Task:**
+```python
+task_id = client.create_scraper_task(
+    file_name="my_task",
+    spider_id="universal",
+    spider_name="universal",
+    parameters={"url": "https://example.com"}
+)
+```
+
+**Video Download (New):**
+```python
+from thordata import CommonSettings
+
+task_id = client.create_video_task(
+    file_name="{{VideoID}}",
+    spider_id="youtube_video_by-url",
+    spider_name="youtube.com",
+    parameters={"url": "https://youtube.com/watch?v=..."},
+    common_settings=CommonSettings(resolution="1080p")
+)
+```
+
+**Wait & Download:**
+```python
+status = client.wait_for_task(task_id)
+if status == "ready":
+    url = client.get_task_result(task_id)
+    print(url)
+```
+
+### Account Management
+
+```python
+# Usage Statistics
+stats = client.get_usage_statistics("2024-01-01", "2024-01-31")
+print(f"Balance: {stats.balance_gb():.2f} GB")
+
+# Proxy Users
+users = client.list_proxy_users()
+print(f"Sub-users: {users.user_count}")
+
+# Whitelist IP
+client.add_whitelist_ip("1.2.3.4")
+```
+
+### Proxy Network
+
+```python
+from thordata import ProxyConfig
+
+# Generate Proxy URL
+proxy_url = client.build_proxy_url(
+    username="proxy_user",
+    password="proxy_pass",
+    country="us",
+    city="ny"
+)
+
+# Use with requests
+import requests
+requests.get("https://httpbin.org/ip", proxies={"http": proxy_url, "https": proxy_url})
+```
+
+---
+
+## 📄 License
+
+MIT License

{thordata_sdk-0.6.0 → thordata_sdk-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "thordata-sdk"
-version = "0.6.0"
+version = "0.8.0"
 description = "The Official Python SDK for Thordata - AI Data Infrastructure & Proxy Network."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -57,6 +57,7 @@ dev = [
     "ruff>=0.1.0",
     "mypy>=1.0.0",
     "types-requests>=2.28.0",
+    "aioresponses>=0.7.6",
 ]
 
 [project.urls]

{thordata_sdk-0.6.0 → thordata_sdk-0.8.0}/src/thordata/__init__.py

@@ -35,7 +35,7 @@ Async Usage:
     >>> asyncio.run(main())
 """
 
-__version__ = "0.6.0"
+__version__ = "0.8.0"
 __author__ = "Thordata Developer Team"
 __email__ = "support@thordata.com"
 
@@ -52,6 +52,7 @@ from .enums import (
     Device,
     Engine,
     GoogleSearchType,
+    GoogleTbm,
     OutputFormat,
     ProxyHost,
     ProxyPort,
@@ -77,14 +78,20 @@ from .exceptions import (
 
 # Models
 from .models import (
+    CommonSettings,
     ProxyConfig,
     ProxyProduct,
+    ProxyServer,
+    ProxyUser,
+    ProxyUserList,
     ScraperTaskConfig,
     SerpRequest,
     StaticISPProxy,
     StickySession,
     TaskStatusResponse,
     UniversalScrapeRequest,
+    UsageStatistics,
+    VideoTaskConfig,
 )
 
 # Retry utilities
@@ -112,14 +119,21 @@ __all__ = [
     "TimeRange",
     "ProxyHost",
     "ProxyPort",
+    "GoogleTbm",
     # Models
     "ProxyConfig",
     "ProxyProduct",
+    "ProxyServer",
+    "ProxyUser",
+    "ProxyUserList",
+    "UsageStatistics",
     "StaticISPProxy",
     "StickySession",
     "SerpRequest",
     "UniversalScrapeRequest",
     "ScraperTaskConfig",
+    "CommonSettings",
+    "VideoTaskConfig",
     "TaskStatusResponse",
     # Exceptions
     "ThordataError",

{thordata_sdk-0.6.0 → thordata_sdk-0.8.0}/src/thordata/_utils.py

@@ -70,18 +70,61 @@ def decode_base64_image(png_str: str) -> bytes:
         raise ValueError(f"Failed to decode base64 image: {e}") from e
 
 
-def build_auth_headers(token: str) -> Dict[str, str]:
+def build_auth_headers(token: str, mode: str = "bearer") -> Dict[str, str]:
     """
     Build authorization headers for API requests.
 
+    Supports two modes:
+    - bearer: Authorization: Bearer <token> (Thordata Docs examples)
+    - header_token: token: <token> (Interface documentation)
+
     Args:
         token: The scraper token.
+        mode: Authentication mode ("bearer" or "header_token").
+
+    Returns:
+        Headers dict with Authorization/token and Content-Type.
+    """
+    headers = {
+        "Content-Type": "application/x-www-form-urlencoded",
+    }
+
+    if mode == "bearer":
+        headers["Authorization"] = f"Bearer {token}"
+    elif mode == "header_token":
+        headers["token"] = token
+    else:
+        # Fallback to bearer for compatibility
+        headers["Authorization"] = f"Bearer {token}"
+
+    return headers
+
+
+def build_builder_headers(
+    scraper_token: str,
+    public_token: str,
+    public_key: str,
+) -> Dict[str, str]:
+    """
+    Build headers for Web Scraper builder API.
+
+    Builder requires THREE auth headers per official docs:
+    - token: public token
+    - key: public key
+    - Authorization: Bearer scraper_token
+
+    Args:
+        scraper_token: The scraper API token.
+        public_token: The public API token.
+        public_key: The public API key.
 
     Returns:
-        Headers dict with Authorization and Content-Type.
+        Headers dict with all required auth headers.
     """
     return {
-        "Authorization": f"Bearer {token}",
+        "token": public_token,
+        "key": public_key,
+        "Authorization": f"Bearer {scraper_token}",
         "Content-Type": "application/x-www-form-urlencoded",
     }
 
@@ -142,3 +185,23 @@ def build_user_agent(sdk_version: str, http_client: str) -> str:
     py = platform.python_version()
     system = platform.system()
     return f"thordata-python-sdk/{sdk_version} (python {py}; {system}; {http_client})"
+
+
+def build_sign_headers(sign: str, api_key: str) -> Dict[str, str]:
+    """
+    Build headers for Public API NEW (sign + apiKey authentication).
+
+    This is a different authentication system from token+key.
+
+    Args:
+        sign: The sign value from Dashboard (immutable).
+        api_key: The apiKey value from Dashboard (can be changed).
+
+    Returns:
+        Headers dict with sign, apiKey, and Content-Type.
+    """
+    return {
+        "sign": sign,
+        "apiKey": api_key,
+        "Content-Type": "application/x-www-form-urlencoded",
+    }