thordata-sdk 0.7.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

thordata/__init__.py

@@ -35,7 +35,7 @@ Async Usage:
     >>> asyncio.run(main())
 """
 
-__version__ = "0.7.0"
+__version__ = "1.0.0"
 __author__ = "Thordata Developer Team"
 __email__ = "support@thordata.com"
 
@@ -78,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
@@ -117,11 +123,17 @@ __all__ = [
     # Models
     "ProxyConfig",
     "ProxyProduct",
+    "ProxyServer",
+    "ProxyUser",
+    "ProxyUserList",
+    "UsageStatistics",
     "StaticISPProxy",
     "StickySession",
     "SerpRequest",
     "UniversalScrapeRequest",
     "ScraperTaskConfig",
+    "CommonSettings",
+    "VideoTaskConfig",
     "TaskStatusResponse",
     # Exceptions
     "ThordataError",

thordata/_example_utils.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Iterable, Optional
+
+try:
+    from dotenv import load_dotenv
+except Exception:  # pragma: no cover
+    load_dotenv = None
+
+
+def load_env() -> None:
+    """Load .env from repo root if python-dotenv is installed."""
+    if load_dotenv is None:
+        return
+    repo_root = Path(__file__).resolve().parents[2]
+    load_dotenv(dotenv_path=repo_root / ".env")
+
+
+def env(name: str) -> str:
+    return (os.getenv(name) or "").strip()
+
+
+def skip_if_missing(required: Iterable[str], *, tip: Optional[str] = None) -> bool:
+    missing = [k for k in required if not env(k)]
+    if not missing:
+        return False
+    print("Skipping live example: missing env:", ", ".join(missing))
+    if tip:
+        print(tip)
+    else:
+        print("Tip: copy .env.example to .env and fill values, then re-run.")
+    return True
+
+
+def parse_json_env(name: str, default: str = "{}") -> Any:
+    raw = env(name) or default
+    return json.loads(raw)
+
+
+def normalize_task_parameters(raw: Any) -> dict[str, Any]:
+    """Accept {..} or [{..}] and return a single dict for create_scraper_task(parameters=...)."""
+    if isinstance(raw, list):
+        if not raw:
+            raise ValueError("Task parameters JSON array must not be empty")
+        raw = raw[0]
+    if not isinstance(raw, dict):
+        raise ValueError("Task parameters must be a JSON object (or array of objects)")
+    return raw
+
+
+def output_dir() -> Path:
+    """Return output dir for examples; defaults to examples/output (ignored by git)."""
+    repo_root = Path(__file__).resolve().parents[2]
+    d = env("THORDATA_OUTPUT_DIR") or str(repo_root / "examples" / "output")
+    p = Path(d)
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def write_text(filename: str, content: str) -> Path:
+    p = output_dir() / filename
+    p.write_text(content, encoding="utf-8", errors="replace")
+    return p
+
+
+def write_json(filename: str, data: Any) -> Path:
+    p = output_dir() / filename
+    p.write_text(
+        json.dumps(data, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+        errors="replace",
+    )
+    return p

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",
     }