Metadata-Version: 2.4
Name: thordata-sdk
Version: 1.8.5
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
Requires-Dist: PySocks>=1.7.1
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>=25.11.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"
Provides-Extra: browser
Requires-Dist: playwright>=1.40.0; extra == "browser"
Dynamic: license-file

# Thordata Python SDK

<div align="center">

<img src="https://img.shields.io/badge/Thordata-AI%20Infrastructure-blue?style=for-the-badge" alt="Thordata Logo">

**The Official Python Client for Thordata APIs**

*Proxy Network • SERP API • Web Unlocker • Web Scraper API*

[![PyPI version](https://img.shields.io/pypi/v/thordata-sdk.svg?style=flat-square)](https://pypi.org/project/thordata-sdk/)
[![Python Versions](https://img.shields.io/pypi/pyversions/thordata-sdk.svg?style=flat-square)](https://pypi.org/project/thordata-sdk/)
[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
[![CI Status](https://img.shields.io/github/actions/workflow/status/Thordata/thordata-python-sdk/ci.yml?branch=main&style=flat-square)](https://github.com/Thordata/thordata-python-sdk/actions)

</div>

---

## Overview

The **Thordata Python SDK** is an officially supported client library for Thordata APIs:
SERP, Universal Scrape (Web Unlocker), Web Scraper Tasks, and Proxy Network.

## Installation

```bash
pip install thordata-sdk
```

## Configuration

Use environment variables (recommended). For local development, copy
[.env.example](.env.example) to `.env` and fill in values (**never commit `.env`**).

```bash
# [Scraping APIs]
export THORDATA_SCRAPER_TOKEN="your_scraper_token"

# [Management APIs]
export THORDATA_PUBLIC_TOKEN="your_public_token"
export THORDATA_PUBLIC_KEY="your_public_key"

# [Proxy: Residential / Unlimited / Datacenter / Mobile / ISP]
export THORDATA_RESIDENTIAL_USERNAME="your_username"
export THORDATA_RESIDENTIAL_PASSWORD="your_password"
```

### Loading `.env` (optional)

The SDK does not automatically load a `.env` file. If you want `.env` support:

```python
from thordata import load_env_file

load_env_file()  # loads ./.env if present, without overriding existing env vars
```

## Quick Start

### SERP Search

```python
from thordata import Engine, ThordataClient

client = ThordataClient()
results = client.serp_search(query="latest AI trends", engine=Engine.GOOGLE, num=10)
for item in results.get("organic", []):
    print(item.get("title"), item.get("link"))
```

### Universal Scrape

```python
from thordata import ThordataClient

client = ThordataClient()
html = client.universal_scrape(url="https://example.com", js_render=True, country="us")
print(type(html), len(str(html)))
```

### Web Scraper Tools

```python
from thordata import ThordataClient
from thordata.tools import Amazon

client = ThordataClient()
task_id = client.run_tool(Amazon.ProductByAsin(asin="B0BZYCJK89"))
status = client.wait_for_task(task_id, max_wait=300)
if status == "ready":
    print(client.get_task_result(task_id))
```

See `examples/` for more runnable scripts.

## Documentation

- `docs/README.md` (index)
- `docs/SDK_FEATURES_AND_USAGE.md`
- `docs/serp_reference.md`
- `docs/universal_reference.md`
- `docs/browser_reference.md`
- `docs/web_scraper_tasks_reference.md`

## Development & Testing

```bash
pip install -e ".[dev]"
ruff check src tests examples
black --check src tests examples
mypy src --ignore-missing-imports
pytest
```

### Live / Integration tests

Integration tests are skipped by default. Enable them explicitly:

```bash
THORDATA_INTEGRATION=true pytest -m integration -v
```

For live end-to-end checks (requires real credentials in `.env`), see:
- `scripts/run_comprehensive_acceptance.py`
- `scripts/acceptance/` (targeted read-only acceptance scripts)

## License

MIT License. See [LICENSE](LICENSE) for details.
