thordata-sdk 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

thordata_sdk-0.8.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+thordata/__init__.py,sha256=yaIxW1T_nsCeiPE6iIHunjRzPrtbiN0BciveICgL4dM,3195
+thordata/_utils.py,sha256=epF-ewHyk7McdejlhHNAfxhIQ8sN3TlIjUJ9H4HOaUE,5254
+thordata/async_client.py,sha256=tC9y1wmcO6RsXCysBo0a0GNRZR3QQjJlCmEwG5HVukQ,53169
+thordata/client.py,sha256=VN5Jm3er7fdZDfT2G9g4siBSYNo0ZWj4WOi6TAiAZcE,59638
+thordata/demo.py,sha256=zmG4I4cHXnbmQfbr063SeRK7_9IXrfof9QFoGqGTVm8,3806
+thordata/enums.py,sha256=MpZnS9_8sg2vtcFqM6UicB94cKZm5R1t83L3ejNSbLs,8502
+thordata/exceptions.py,sha256=IgMsFuh49cPxU5YofsKP1UhP5A_snhtuN6xD1yZWLiI,10018
+thordata/models.py,sha256=NG4wn1bq4-FC4Aex8vwBOldiHovwg0JzhdtBsI1mL_8,36118
+thordata/retry.py,sha256=nkh17ca2TIEcTc-uNo-xcNdJPuxZ_VGlMbC70X6p-_Q,11518
+thordata_sdk-0.8.0.dist-info/licenses/LICENSE,sha256=bAxpWgQIzb-5jl3nhLdOwOJ_vlbHLtSG7yev2B7vioY,1088
+thordata_sdk-0.8.0.dist-info/METADATA,sha256=IgL554I6mzya9FdbqCxKdvO3r-bywiHJjZi1xdk8W48,5850
+thordata_sdk-0.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+thordata_sdk-0.8.0.dist-info/top_level.txt,sha256=Z8R_07m0lXCCSb1hapL9_nxMtyO3rf_9wOvq4n9u2Hg,9
+thordata_sdk-0.8.0.dist-info/RECORD,,

thordata/parameters.py

@@ -1,53 +0,0 @@
-# src/thordata/parameters.py
-
-from typing import Any, Dict
-
-
-def normalize_serp_params(engine: str, query: str, **kwargs) -> Dict[str, Any]:
-    """
-    Normalizes parameters across different search engines to ensure a unified API surface.
-
-    Args:
-        engine (str): The search engine to use (e.g., 'google', 'yandex').
-        query (str): The search query string.
-        **kwargs: Additional parameters to pass to the API.
-
-    Returns:
-        Dict[str, Any]: The constructed payload for the API request.
-    """
-    # 1. Base parameters
-    payload = {
-        "num": str(kwargs.get("num", 10)),  # Default to 10 results
-        "json": "1",  # Force JSON response
-        "engine": engine,
-    }
-
-    # 2. Handle Query Parameter Differences (Yandex uses 'text', others use 'q')
-    if engine == "yandex":
-        payload["text"] = query
-        # Set default URL for Yandex if not provided
-        if "url" not in kwargs:
-            payload["url"] = "yandex.com"
-    else:
-        payload["q"] = query
-
-        # 3. Handle Default URLs for other engines
-        if "url" not in kwargs:
-            defaults = {
-                "google": "google.com",
-                "bing": "bing.com",
-                "duckduckgo": "duckduckgo.com",
-                "baidu": "baidu.com",
-            }
-            if engine in defaults:
-                payload["url"] = defaults[engine]
-
-    # 4. Passthrough for all other user-provided arguments
-    # This allows support for engine-specific parameters (e.g., tbm, uule, gl)
-    # without explicitly defining them all.
-    protected_keys = {"num", "engine", "q", "text"}
-    for key, value in kwargs.items():
-        if key not in protected_keys:
-            payload[key] = value
-
-    return payload