# Raven Captcha Solver
A Python client library for the Raven Captcha API, providing both synchronous and asynchronous interfaces for solving Google reCAPTCHA v2 and v3 challenges.
## Features
- 🔄 **Dual Interface**: Both sync and async clients available
- 🛡️ **Google reCAPTCHA Support**: v2 and v3 variants
- 🌐 **Proxy Support**: Full proxy configuration options
- ⚡ **Type Safety**: Fully typed with comprehensive error handling
- 🔧 **Configurable**: Timeout, retry, and polling customization
- 📦 **Clean Architecture**: Modular design with clear separation of concerns
## Installation
Install from PyPI:
```bash
pip install raven-captcha-solver
```
## Quick Start
### Async Usage (Recommended)
```python
import asyncio
from raven import AsyncRavenClient
async def solve_captcha():
client = AsyncRavenClient(api_key="your-api-key")
# Solve reCAPTCHA v2
result = await client.google.RecaptchaV2(
website_url="https://example.com",
website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
)
print(f"Solution token: {result.solution.token}")
# Run the async function
asyncio.run(solve_captcha())
```
### Sync Usage
```python
from raven import RavenClient
client = RavenClient(api_key="your-api-key")
# Solve reCAPTCHA v3
result = client.google.RecaptchaV3(
website_url="https://example.com",
website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
action="submit"
)
print(f"Solution token: {result.solution.token}")
```
## API Reference
### Client Initialization
#### AsyncRavenClient
```python
client = AsyncRavenClient(
api_key="your-api-key",
base_url="https://ai.ravens.best", # Optional, default shown
timeout=30.0 # Optional, request timeout in seconds
)
```
#### RavenClient
```python
client = RavenClient(
api_key="your-api-key",
base_url="https://ai.ravens.best", # Optional, default shown
timeout=30.0 # Optional, request timeout in seconds
)
```
### Google reCAPTCHA Methods
Both async and sync clients provide the same methods under `client.google`:
#### RecaptchaV2
Solves Google reCAPTCHA v2 challenges.
```python
# Async
result = await client.google.RecaptchaV2(
website_url="https://example.com",
website_key="site-key",
invisible=None, # Optional: True for invisible captcha
enterprise=None, # Optional: True for enterprise mode
action=None, # Optional: action string
proxy_scheme=None, # Optional: "http" or "https"
proxy_host=None, # Optional: proxy hostname
proxy_port=None, # Optional: proxy port
proxy_username=None, # Optional: proxy auth username
proxy_password=None, # Optional: proxy auth password
max_retry=None, # Optional: max retry attempts
poll_interval=1.0, # Optional: polling interval in seconds
timeout=None # Optional: max wait time, None = indefinite
)
# Sync - same parameters
result = client.google.RecaptchaV2(...)
```
#### RecaptchaV3
Solves Google reCAPTCHA v3 challenges.
```python
# Async
result = await client.google.RecaptchaV3(
website_url="https://example.com",
website_key="site-key",
action=None, # Optional: action for v3 scoring
enterprise=None, # Optional: True for enterprise mode
proxy_scheme=None, # Optional: "http" or "https"
proxy_host=None, # Optional: proxy hostname
proxy_port=None, # Optional: proxy port
proxy_username=None, # Optional: proxy auth username
proxy_password=None, # Optional: proxy auth password
max_retry=None, # Optional: max retry attempts
poll_interval=1.0, # Optional: polling interval in seconds
timeout=None # Optional: max wait time, None = indefinite
)
# Sync - same parameters
result = client.google.RecaptchaV3(...)
```
### Response Format
All methods return a `TaskStatusResponse` object:
```python
@dataclass
class TaskStatusResponse:
success: bool # Whether the task completed successfully
status: str # Task status: "completed", "processing", "failed"
created_at: Optional[str] # Task creation timestamp
task_id: str # Unique task identifier
solution: Solution # Contains the captcha solution
@dataclass
class Solution:
token: Optional[str] # The captcha solution token
duration: Optional[Any] # Time taken to solve
```
### Cloudflare Turnstile
Solves Cloudflare Turnstile challenges. This provider supports proxy configuration only; no additional `options` are sent.
```python
# Async
result = await client.cloudflare.Turnstile(
website_url="https://example.com",
website_key="site-key",
proxy_scheme=None, # Optional: "http" or "https"
proxy_host=None, # Optional: proxy hostname
proxy_port=None, # Optional: proxy port
proxy_username=None,# Optional: proxy auth username
proxy_password=None,# Optional: proxy auth password
max_retry=None, # Optional: max retry attempts
poll_interval=1.0, # Optional: polling interval in seconds
timeout=None # Optional: max wait time, None = indefinite
)
print(result.solution.token)
# Sync - same parameters
result = client.cloudflare.Turnstile(
website_url="https://example.com",
website_key="site-key"
)
```
## Configuration Examples
### Using Proxies
```python
result = await client.google.RecaptchaV2(
website_url="https://example.com",
website_key="site-key",
proxy_scheme="http",
proxy_host="proxy.example.com",
proxy_port="8080",
proxy_username="user",
proxy_password="pass"
)
```
### Custom Timeouts and Polling
```python
result = await client.google.RecaptchaV3(
website_url="https://example.com",
website_key="site-key",
poll_interval=2.0, # Check every 2 seconds
timeout=120.0, # Give up after 2 minutes
max_retry=3 # Retry failed tasks up to 3 times
)
```
### Enterprise reCAPTCHA
```python
result = await client.google.RecaptchaV2(
website_url="https://example.com",
website_key="enterprise-site-key",
enterprise=True
)
```
## Error Handling
The library provides specific exceptions for different error conditions:
```python
from raven.exceptions import (
RavenError, # Base exception
InvalidApiKeyError,
TaskFailedError,
MaxConcurrencyReachedError,
# ... and many more specific exceptions
)
try:
result = await client.google.RecaptchaV2(
website_url="https://example.com",
website_key="invalid-key"
)
except InvalidApiKeyError:
print("API key is invalid")
except TaskFailedError:
print("Captcha solving failed")
except RavenError as e:
print(f"Other Raven error: {e}")
```
### Common Exceptions
- `InvalidApiKeyError`: API key is invalid or missing
- `TaskFailedError`: Task failed during processing or timed out
- `MaxConcurrencyReachedError`: Account concurrency limit reached
- `WebsiteUrlRequiredError`: Website URL parameter missing
- `WebsiteKeyRequiredError`: Website key parameter missing
- `InvalidCaptchaTypeError`: Unsupported captcha type requested
## Parameter Defaults
| Parameter | Default Value | Description |
|-----------|---------------|-------------|
| `base_url` | `"https://ai.ravens.best"` | API endpoint URL |
| `timeout` | `30.0` | HTTP request timeout (seconds) |
| `poll_interval` | `1.0` | Status polling interval (seconds) |
| `invisible` | `None` | Auto-detect invisible captcha mode |
| `enterprise` | `None` | Auto-detect enterprise mode |
| `action` | `None` | No action specified (v3 uses default) |
| `max_retry` | `None` | Use service default retry policy |
| `proxy_*` | `None` | No proxy configuration |
## Architecture
The library is structured with clean separation of concerns:
- **Clients** (`raven.clients`): User-facing sync/async interfaces
- **Providers** (`raven.providers.google`): Service-specific implementations
- **Services** (`raven.services.captcha_service`): Core business logic
- **HTTP Client** (`raven.http.client`): Low-level HTTP communication
- **Models** (`raven.models`): Data structures and serialization
- **Exceptions** (`raven.exceptions`): Error handling and mapping
## Requirements
- Python 3.7+
- `requests >= 2.28.0`
## License
This project is licensed under the MIT License.
## Support
For issues and questions:
- Check the [GitHub Issues](https://github.com/ravens-best/raven-python-client/issues)
- Review the API documentation at [Raven API Docs](https://ai.ravens.best/docs)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": "https://github.com/ravens-best/raven-python-client",
"name": "raven-python-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "captcha, recaptcha, google, automation, api, client, async, sync, raven, solver",
"author": "Raven Team",
"author_email": "support@ravens.best",
"download_url": "https://files.pythonhosted.org/packages/74/16/5cc38df44d8f9382ecfbc609828d4ea93d2988c545a51ee09f816456f104/raven_python_client-1.0.1.tar.gz",
"platform": null,
"description": "# Raven Captcha Solver\r\n\r\nA Python client library for the Raven Captcha API, providing both synchronous and asynchronous interfaces for solving Google reCAPTCHA v2 and v3 challenges.\r\n\r\n## Features\r\n\r\n- \ud83d\udd04 **Dual Interface**: Both sync and async clients available\r\n- \ud83d\udee1\ufe0f **Google reCAPTCHA Support**: v2 and v3 variants\r\n- \ud83c\udf10 **Proxy Support**: Full proxy configuration options\r\n- \u26a1 **Type Safety**: Fully typed with comprehensive error handling\r\n- \ud83d\udd27 **Configurable**: Timeout, retry, and polling customization\r\n- \ud83d\udce6 **Clean Architecture**: Modular design with clear separation of concerns\r\n\r\n## Installation\r\n\r\nInstall from PyPI:\r\n\r\n```bash\r\npip install raven-captcha-solver\r\n```\r\n\r\n## Quick Start\r\n\r\n### Async Usage (Recommended)\r\n\r\n```python\r\nimport asyncio\r\nfrom raven import AsyncRavenClient\r\n\r\nasync def solve_captcha():\r\n client = AsyncRavenClient(api_key=\"your-api-key\")\r\n \r\n # Solve reCAPTCHA v2\r\n result = await client.google.RecaptchaV2(\r\n website_url=\"https://example.com\",\r\n website_key=\"6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-\"\r\n )\r\n \r\n print(f\"Solution token: {result.solution.token}\")\r\n\r\n# Run the async function\r\nasyncio.run(solve_captcha())\r\n```\r\n\r\n### Sync Usage\r\n\r\n```python\r\nfrom raven import RavenClient\r\n\r\nclient = RavenClient(api_key=\"your-api-key\")\r\n\r\n# Solve reCAPTCHA v3\r\nresult = client.google.RecaptchaV3(\r\n website_url=\"https://example.com\",\r\n website_key=\"6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-\",\r\n action=\"submit\"\r\n)\r\n\r\nprint(f\"Solution token: {result.solution.token}\")\r\n```\r\n\r\n## API Reference\r\n\r\n### Client Initialization\r\n\r\n#### AsyncRavenClient\r\n\r\n```python\r\nclient = AsyncRavenClient(\r\n api_key=\"your-api-key\",\r\n base_url=\"https://ai.ravens.best\", # Optional, default shown\r\n timeout=30.0 # Optional, request timeout in seconds\r\n)\r\n```\r\n\r\n#### RavenClient\r\n\r\n```python\r\nclient = RavenClient(\r\n api_key=\"your-api-key\",\r\n base_url=\"https://ai.ravens.best\", # Optional, default shown\r\n timeout=30.0 # Optional, request timeout in seconds\r\n)\r\n```\r\n\r\n### Google reCAPTCHA Methods\r\n\r\nBoth async and sync clients provide the same methods under `client.google`:\r\n\r\n#### RecaptchaV2\r\n\r\nSolves Google reCAPTCHA v2 challenges.\r\n\r\n```python\r\n# Async\r\nresult = await client.google.RecaptchaV2(\r\n website_url=\"https://example.com\",\r\n website_key=\"site-key\",\r\n invisible=None, # Optional: True for invisible captcha\r\n enterprise=None, # Optional: True for enterprise mode\r\n action=None, # Optional: action string\r\n proxy_scheme=None, # Optional: \"http\" or \"https\"\r\n proxy_host=None, # Optional: proxy hostname\r\n proxy_port=None, # Optional: proxy port\r\n proxy_username=None, # Optional: proxy auth username\r\n proxy_password=None, # Optional: proxy auth password\r\n max_retry=None, # Optional: max retry attempts\r\n poll_interval=1.0, # Optional: polling interval in seconds\r\n timeout=None # Optional: max wait time, None = indefinite\r\n)\r\n\r\n# Sync - same parameters\r\nresult = client.google.RecaptchaV2(...)\r\n```\r\n\r\n#### RecaptchaV3\r\n\r\nSolves Google reCAPTCHA v3 challenges.\r\n\r\n```python\r\n# Async\r\nresult = await client.google.RecaptchaV3(\r\n website_url=\"https://example.com\",\r\n website_key=\"site-key\",\r\n action=None, # Optional: action for v3 scoring\r\n enterprise=None, # Optional: True for enterprise mode\r\n proxy_scheme=None, # Optional: \"http\" or \"https\"\r\n proxy_host=None, # Optional: proxy hostname\r\n proxy_port=None, # Optional: proxy port\r\n proxy_username=None, # Optional: proxy auth username\r\n proxy_password=None, # Optional: proxy auth password\r\n max_retry=None, # Optional: max retry attempts\r\n poll_interval=1.0, # Optional: polling interval in seconds\r\n timeout=None # Optional: max wait time, None = indefinite\r\n)\r\n\r\n# Sync - same parameters\r\nresult = client.google.RecaptchaV3(...)\r\n```\r\n\r\n### Response Format\r\n\r\nAll methods return a `TaskStatusResponse` object:\r\n\r\n```python\r\n@dataclass\r\nclass TaskStatusResponse:\r\n success: bool # Whether the task completed successfully\r\n status: str # Task status: \"completed\", \"processing\", \"failed\"\r\n created_at: Optional[str] # Task creation timestamp\r\n task_id: str # Unique task identifier\r\n solution: Solution # Contains the captcha solution\r\n\r\n@dataclass\r\nclass Solution:\r\n token: Optional[str] # The captcha solution token\r\n duration: Optional[Any] # Time taken to solve\r\n```\r\n\r\n### Cloudflare Turnstile\r\n\r\nSolves Cloudflare Turnstile challenges. This provider supports proxy configuration only; no additional `options` are sent.\r\n\r\n```python\r\n# Async\r\nresult = await client.cloudflare.Turnstile(\r\n website_url=\"https://example.com\",\r\n website_key=\"site-key\",\r\n proxy_scheme=None, # Optional: \"http\" or \"https\"\r\n proxy_host=None, # Optional: proxy hostname\r\n proxy_port=None, # Optional: proxy port\r\n proxy_username=None,# Optional: proxy auth username\r\n proxy_password=None,# Optional: proxy auth password\r\n max_retry=None, # Optional: max retry attempts\r\n poll_interval=1.0, # Optional: polling interval in seconds\r\n timeout=None # Optional: max wait time, None = indefinite\r\n)\r\n\r\nprint(result.solution.token)\r\n\r\n# Sync - same parameters\r\nresult = client.cloudflare.Turnstile(\r\n website_url=\"https://example.com\",\r\n website_key=\"site-key\"\r\n)\r\n```\r\n\r\n## Configuration Examples\r\n\r\n### Using Proxies\r\n\r\n```python\r\nresult = await client.google.RecaptchaV2(\r\n website_url=\"https://example.com\",\r\n website_key=\"site-key\",\r\n proxy_scheme=\"http\",\r\n proxy_host=\"proxy.example.com\",\r\n proxy_port=\"8080\",\r\n proxy_username=\"user\",\r\n proxy_password=\"pass\"\r\n)\r\n```\r\n\r\n### Custom Timeouts and Polling\r\n\r\n```python\r\nresult = await client.google.RecaptchaV3(\r\n website_url=\"https://example.com\",\r\n website_key=\"site-key\",\r\n poll_interval=2.0, # Check every 2 seconds\r\n timeout=120.0, # Give up after 2 minutes\r\n max_retry=3 # Retry failed tasks up to 3 times\r\n)\r\n```\r\n\r\n### Enterprise reCAPTCHA\r\n\r\n```python\r\nresult = await client.google.RecaptchaV2(\r\n website_url=\"https://example.com\",\r\n website_key=\"enterprise-site-key\",\r\n enterprise=True\r\n)\r\n```\r\n\r\n## Error Handling\r\n\r\nThe library provides specific exceptions for different error conditions:\r\n\r\n```python\r\nfrom raven.exceptions import (\r\n RavenError, # Base exception\r\n InvalidApiKeyError,\r\n TaskFailedError,\r\n MaxConcurrencyReachedError,\r\n # ... and many more specific exceptions\r\n)\r\n\r\ntry:\r\n result = await client.google.RecaptchaV2(\r\n website_url=\"https://example.com\",\r\n website_key=\"invalid-key\"\r\n )\r\nexcept InvalidApiKeyError:\r\n print(\"API key is invalid\")\r\nexcept TaskFailedError:\r\n print(\"Captcha solving failed\")\r\nexcept RavenError as e:\r\n print(f\"Other Raven error: {e}\")\r\n```\r\n\r\n### Common Exceptions\r\n\r\n- `InvalidApiKeyError`: API key is invalid or missing\r\n- `TaskFailedError`: Task failed during processing or timed out\r\n- `MaxConcurrencyReachedError`: Account concurrency limit reached\r\n- `WebsiteUrlRequiredError`: Website URL parameter missing\r\n- `WebsiteKeyRequiredError`: Website key parameter missing\r\n- `InvalidCaptchaTypeError`: Unsupported captcha type requested\r\n\r\n## Parameter Defaults\r\n\r\n| Parameter | Default Value | Description |\r\n|-----------|---------------|-------------|\r\n| `base_url` | `\"https://ai.ravens.best\"` | API endpoint URL |\r\n| `timeout` | `30.0` | HTTP request timeout (seconds) |\r\n| `poll_interval` | `1.0` | Status polling interval (seconds) |\r\n| `invisible` | `None` | Auto-detect invisible captcha mode |\r\n| `enterprise` | `None` | Auto-detect enterprise mode |\r\n| `action` | `None` | No action specified (v3 uses default) |\r\n| `max_retry` | `None` | Use service default retry policy |\r\n| `proxy_*` | `None` | No proxy configuration |\r\n\r\n## Architecture\r\n\r\nThe library is structured with clean separation of concerns:\r\n\r\n- **Clients** (`raven.clients`): User-facing sync/async interfaces\r\n- **Providers** (`raven.providers.google`): Service-specific implementations\r\n- **Services** (`raven.services.captcha_service`): Core business logic\r\n- **HTTP Client** (`raven.http.client`): Low-level HTTP communication\r\n- **Models** (`raven.models`): Data structures and serialization\r\n- **Exceptions** (`raven.exceptions`): Error handling and mapping\r\n\r\n## Requirements\r\n\r\n- Python 3.7+\r\n- `requests >= 2.28.0`\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License.\r\n\r\n## Support\r\n\r\nFor issues and questions:\r\n- Check the [GitHub Issues](https://github.com/ravens-best/raven-python-client/issues)\r\n- Review the API documentation at [Raven API Docs](https://ai.ravens.best/docs)\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python client library for the Raven Captcha API with sync and async support",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/ravens-best/raven-python-client/issues",
"Documentation": "https://ai.ravens.best/docs",
"Homepage": "https://ai.ravens.best",
"Source Code": "https://github.com/ravens-best/raven-python-client"
},
"split_keywords": [
"captcha",
" recaptcha",
" google",
" automation",
" api",
" client",
" async",
" sync",
" raven",
" solver"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c7324772e8cef18a89ee1e9f5a33454028da05504361a9f0b96661f8c800e018",
"md5": "175714d8c3dfe5572d7d78e5ae211e79",
"sha256": "a99b56e8b38c7879eb23fd92de4f4ca0740487f49cc781424f360f4d31af885d"
},
"downloads": -1,
"filename": "raven_python_client-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "175714d8c3dfe5572d7d78e5ae211e79",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 14481,
"upload_time": "2025-10-08T22:38:06",
"upload_time_iso_8601": "2025-10-08T22:38:06.353070Z",
"url": "https://files.pythonhosted.org/packages/c7/32/4772e8cef18a89ee1e9f5a33454028da05504361a9f0b96661f8c800e018/raven_python_client-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "74165cc38df44d8f9382ecfbc609828d4ea93d2988c545a51ee09f816456f104",
"md5": "f66e18f94625f3fe8ccb125823999980",
"sha256": "256f10e013aa0d3ef6ec59b02a5d0043eb5f3c016395c9b465656ae0e1c94bba"
},
"downloads": -1,
"filename": "raven_python_client-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "f66e18f94625f3fe8ccb125823999980",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 14308,
"upload_time": "2025-10-08T22:38:07",
"upload_time_iso_8601": "2025-10-08T22:38:07.371842Z",
"url": "https://files.pythonhosted.org/packages/74/16/5cc38df44d8f9382ecfbc609828d4ea93d2988c545a51ee09f816456f104/raven_python_client-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-08 22:38:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ravens-best",
"github_project": "raven-python-client",
"github_not_found": true,
"lcname": "raven-python-client"
}
JSON
