captcha-solver-api 1.0.4__tar.gz → 1.1.0__tar.gz

{captcha_solver_api-1.0.4 → captcha_solver_api-1.1.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: captcha-solver-api
-Version: 1.0.4
+Version: 1.1.0
 Summary: Official Python SDK for solving reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3/v4, Yandex SmartCaptcha, Tencent, and image/click captchas via the Captcha Solver API
 Author: Captcha Solver Team
 License-Expression: MIT
 Project-URL: Homepage, https://captcha-solver.com
-Project-URL: Documentation, https://captcha-solver.com/en/docs/captcha-types
+Project-URL: Documentation, https://github.com/captcha-solver-api/python-sdk#readme
 Project-URL: Repository, https://github.com/captcha-solver-api/python-sdk
 Keywords: captcha,captcha solver,recaptcha,recaptcha v2,recaptcha v3,cloudflare turnstile,geetest,geetest v4,yandex smartcaptcha,tencent captcha,image captcha,coordinates,click captcha,api
 Classifier: Development Status :: 5 - Production/Stable
@@ -25,8 +25,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: requests>=2.28
-Requires-Dist: httpx>=0.24
+Requires-Dist: requests>=2.32.4
+Requires-Dist: httpx>=0.27
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
@@ -115,6 +115,10 @@ enabled in your editor, hover over `CaptchaClient`, `AsyncCaptchaClient`, their
 methods, or a task class such as `RecaptchaV2TaskProxyless` to read the documentation.
 Signature help shows argument names, types, and defaults while you type a call.
 
+The `captcha_solver_api/py.typed` file is intentionally empty. It is the standard
+[PEP 561](https://peps.python.org/pep-0561/) marker that tells type checkers to use
+the inline type annotations shipped with this package.
+
 Docstrings describe parameters, solution fields, exceptions, and usage examples.
 Task examples assume an existing synchronous `client`; with `AsyncCaptchaClient`,
 use `solution = await client.solve(task)` instead. Async snippets run inside an
@@ -191,15 +195,19 @@ on the target page.
 |---|---|---|
 | reCAPTCHA v2 | ✅ | ✅ |
 | reCAPTCHA v2 Enterprise | ✅ | ✅ |
-| reCAPTCHA v3 | ✅ | ❌ |
+| reCAPTCHA v3 | ✅ | - |
 | Cloudflare Turnstile | ✅ | ✅ |
 | GeeTest v3 | ✅ | ✅ |
 | GeeTest v4 | ✅ | ✅ |
-| Image to Text | ✅ | ❌ |
+| Image to Text | ✅ | - |
 | Yandex SmartCaptcha | ✅ | ✅ |
-| Coordinates (click captcha) | ✅ | ❌ |
+| Yandex SmartCaptcha Image | ✅ | - |
+| Coordinates (click captcha) | ✅ | - |
 | Tencent | ✅ | ✅ |
 
+A dash (`-`) means that this CAPTCHA type has no separate task class that accepts
+your own proxy; it does not indicate that solving the CAPTCHA is unsupported.
+
 ## Client Reference
 
 Every method below is available on both `CaptchaClient` (sync, `requests`-based) and
@@ -247,14 +255,17 @@ solution -- wraps `create_task()` + `get_task_result()` so you don't poll by han
 
 Returns the `solution` dict once `status` is `"ready"` -- its shape depends on
 the task type (see [Captcha Types](#captcha-types)).
-Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
+Raises `ValidationError` before any request if `task` is not a task object or a
+required task parameter is missing or empty. Otherwise raises `ApiError`,
+`CaptchaTimeoutError`, or `NetworkError`.
 
 ### `create_task(task, language_pool=None)`
 
 Submits `task` and returns its numeric task ID without waiting for a solution.
 Accepts `task` and `language_pool`; it does not accept `timeout`. Use this instead of `solve()` if you need to
 manage polling yourself (e.g. checking on many tasks from a different process).
-Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
+Raises `ValidationError` before any request if `task` is invalid (same rules as
+`solve()`). Otherwise raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ### `get_task_result(task_id)`
 
@@ -519,7 +530,7 @@ print(result["validate"])
 print(result["seccode"])
 ```
 `challenge` is session-specific and expires quickly, so it can't be hardcoded
-into a static example -- see [examples/sync/geetest_v3.py](https://github.com/captcha-solver-api/python-sdk/blob/main/examples/sync/geetest_v3.py)
+into a static example -- see [examples/sync/geetest_v3_proxyless.py](https://github.com/captcha-solver-api/python-sdk/blob/main/examples/sync/geetest_v3_proxyless.py)
 for where the fetch belongs in the flow.
 
 ```python
@@ -539,11 +550,9 @@ With proxy, use `GeeTestTask` (same proxy fields as reCAPTCHA v2).
 <sup>[API method description.](https://captcha-solver.com/en/docs/captcha-types#yandex-smartcaptcha)</sup>
 
 Use this method to solve the token-based Yandex SmartCaptcha and obtain a token
-for the widget on the target page. Use the coordinates method for image challenges.
+for the widget on the target page. Use the dedicated image method for image challenges.
 
-`YandexSmartCaptchaTaskProxyless` / `YandexSmartCaptchaTask` -- token-based
-challenge. For the image challenge instead, use `CoordinatesTask` with
-[Coordinates](#coordinates-click-captcha) is available for generic click captchas.
+`YandexSmartCaptchaTaskProxyless` / `YandexSmartCaptchaTask` -- token-based challenge.
 
 | Parameter | Required | Description |
 |---|---|---|
@@ -572,15 +581,45 @@ print(result["token"])
 With proxy, use `YandexSmartCaptchaTask` (same proxy fields as reCAPTCHA v2,
 plus the `https` option above).
 
+#### Image challenge
+
+Use `YandexSmartCaptchaImageTask` when SmartCaptcha shows a main image and a
+separate strip indicating the symbols to click. The SDK sends API v2 type
+`SmartCaptchaTask`; both images must be base64-encoded.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `image` | yes | Main captcha image, base64-encoded. |
+| `imgInstructions` | yes | Click-order instruction image, base64-encoded. |
+| `comment` | no | Optional text hint for the worker. |
+
+**Response:** `coordinates` -- ordered `{"x": int, "y": int}` click positions.
+
+```python
+import base64
+from captcha_solver_api import CaptchaClient
+from captcha_solver_api.tasks import YandexSmartCaptchaImageTask
+
+with open("captcha.png", "rb") as f:
+    image = base64.b64encode(f.read()).decode("utf-8")
+with open("instructions.png", "rb") as f:
+    instructions = base64.b64encode(f.read()).decode("utf-8")
+
+task = YandexSmartCaptchaImageTask(
+    image=image,
+    imgInstructions=instructions,
+)
+result = CaptchaClient("your_api_key").solve(task)
+print(result["coordinates"])
+```
+
 ### Coordinates (click captcha)
 
 <sup>[API method description.](https://captcha-solver.com/en/docs/captcha-types#coordinates)</sup>
 
-Use this method to identify points that a worker should click in an image. It
-supports generic click captchas and the image version of Yandex SmartCaptcha.
+Use this method to identify points that a worker should click in a generic image.
 
-`CoordinatesTask`. Used both for generic "click on X" captchas and for Yandex
-SmartCaptcha's image challenge. No proxy variant -- the image is submitted directly.
+`CoordinatesTask`. No proxy variant -- the image is submitted directly.
 
 | Parameter | Required | Description |
 |---|---|---|
@@ -674,6 +713,16 @@ task lifetime. A local timeout does not cancel a task or mean that the API
 failed to solve it. Use `create_task()` and keep its `task_id` if you need to
 check the same task later; calling `solve()` again creates a new task.
 
+While polling, `solve()` retries short network failures and HTTP timeouts of
+`getTaskResult` on the next poll, so a brief outage does not lose an already
+created task. After `poll_retries` (default 3) consecutive failures the error is
+raised. API errors are not retried, and `createTask` is never retried because
+that could create and pay for a second task. To change the limit:
+
+```python
+client.poll_retries = 5
+```
+
 ### Worker language pool
 
 Set a default `language_pool` once at construction instead of passing it to every call:
@@ -743,13 +792,26 @@ try:
 except ValidationError as e:
     print(f"Invalid argument: {e}")
 except ApiError as e:
-    print(f"API error: {e.error_code} {e.error_description}")
-except CaptchaTimeoutError:
-    print("Task timed out")
+    print(f"API error: {e.error_code} {e.error_description} (task {e.task_id})")
+except CaptchaTimeoutError as e:
+    print(f"Task {e.task_id} timed out")
 except NetworkError as e:
     print(f"Network error: {e}")
 ```
 
+Every SDK error has a `task_id` attribute. It is set when the error happens
+after the task was created (while polling in `solve()` or in `get_task_result()`)
+and is `None` otherwise. A polling timeout does not cancel the task, so you can
+keep checking it:
+
+```python
+try:
+    result = client.solve(task)
+except CaptchaTimeoutError as e:
+    if e.task_id is not None:
+        status = client.get_task_result(e.task_id)
+```
+
 `TimeoutError` is still exported as a deprecated alias of `CaptchaTimeoutError`.
 Avoid importing it by name: it shadows Python's built-in `TimeoutError`.
 
@@ -758,16 +820,17 @@ Avoid importing it by name: it shadows Python's built-in `TimeoutError`.
 See the dedicated [examples documentation](https://github.com/captcha-solver-api/python-sdk/blob/main/examples/README.md) for the full
 sync/async example list, setup steps, expected results, and placeholder guidance.
 
-- **Image/click captchas** (`image_to_text.py`, `coordinates.py`) run after installing the dependencies and setting a valid
+- **Image/click captchas** (`image_to_text.py`, `coordinates.py`,
+  `yandex_smartcaptcha_image.py`) run after installing the dependencies and setting a valid
   `CAPTCHA_API_KEY` -- they read sample images bundled in
   [examples/assets](https://github.com/captcha-solver-api/python-sdk/tree/main/examples/assets), no target page needed.
   `python-dotenv` is optional: install it only if you want the scripts to load a `.env` file.
-- **Token captchas** (`recaptcha_v2.py`, `recaptcha_v2_enterprise.py`, `recaptcha_v3.py`,
-  `turnstile.py`, `yandex_smartcaptcha.py`, `geetest_v4.py`, `tencent.py`) use
+- **Token captchas** (`recaptcha_v2_*.py`, `recaptcha_v2_enterprise_*.py`, `recaptcha_v3.py`,
+  `turnstile_*.py`, `yandex_smartcaptcha_*.py`, `geetest_v4_*.py`, `tencent_*.py`) use
   placeholder values (`https://example.com/...`, `YOUR_WEBSITE_KEY`, `YOUR_APP_ID`,
   `YOUR_CAPTCHA_ID`) -- replace these with the real values from your own target
   page before running.
-- **`geetest_v3.py`** additionally needs `challenge` fetched fresh for every
+- **`geetest_v3_*.py`** additionally needs `challenge` fetched fresh for every
   request -- it's single-use and expires within seconds, so it can't be
   hardcoded into a static example. `"https://target-site.com/path/to/geetest/init"`
   is a placeholder; replace it with a request to your own target's equivalent
@@ -783,6 +846,7 @@ export CAPTCHA_API_KEY=your_api_key
 python examples/sync/balance.py
 python examples/sync/image_to_text.py
 python examples/sync/coordinates.py
+python examples/sync/yandex_smartcaptcha_image.py
 ```
 
 Live checks with real parameters have exercised all supported task types.
@@ -807,8 +871,8 @@ Full API reference: https://captcha-solver.com/en/docs/captcha-types
 - [Selenium Python examples](https://github.com/captcha-solver-api/captcha-solver-selenium-python-examples)
 - [JavaScript examples](https://github.com/captcha-solver-api/javascript-examples)
 - [Tencent CAPTCHA automation examples](https://github.com/captcha-solver-api/How-to-Automate-Tencent-CAPTCHA)
-- [Cloudflare Turnstile Puppeteer Demo](https://github.com/captcha-solver-api/cloudflare-turnstile-puppeteer-demo) — a working browser automation example for Cloudflare Turnstile.
-- [How to Automate Tencent CAPTCHA](https://captcha-solver.com/en/blog/how-to-automate-tencent-captcha) — a step-by-step guide with Python and JavaScript SDK examples.
+- [Cloudflare Turnstile Puppeteer Demo](https://github.com/captcha-solver-api/cloudflare-turnstile-puppeteer-demo) - a working browser automation example for Cloudflare Turnstile.
+- [How to Automate Tencent CAPTCHA](https://captcha-solver.com/en/blog/how-to-automate-tencent-captcha) - a step-by-step guide with Python and JavaScript SDK examples.
 
 ## License
 

{captcha_solver_api-1.0.4 → captcha_solver_api-1.1.0}/README.md

@@ -75,6 +75,10 @@ enabled in your editor, hover over `CaptchaClient`, `AsyncCaptchaClient`, their
 methods, or a task class such as `RecaptchaV2TaskProxyless` to read the documentation.
 Signature help shows argument names, types, and defaults while you type a call.
 
+The `captcha_solver_api/py.typed` file is intentionally empty. It is the standard
+[PEP 561](https://peps.python.org/pep-0561/) marker that tells type checkers to use
+the inline type annotations shipped with this package.
+
 Docstrings describe parameters, solution fields, exceptions, and usage examples.
 Task examples assume an existing synchronous `client`; with `AsyncCaptchaClient`,
 use `solution = await client.solve(task)` instead. Async snippets run inside an
@@ -151,15 +155,19 @@ on the target page.
 |---|---|---|
 | reCAPTCHA v2 | ✅ | ✅ |
 | reCAPTCHA v2 Enterprise | ✅ | ✅ |
-| reCAPTCHA v3 | ✅ | ❌ |
+| reCAPTCHA v3 | ✅ | - |
 | Cloudflare Turnstile | ✅ | ✅ |
 | GeeTest v3 | ✅ | ✅ |
 | GeeTest v4 | ✅ | ✅ |
-| Image to Text | ✅ | ❌ |
+| Image to Text | ✅ | - |
 | Yandex SmartCaptcha | ✅ | ✅ |
-| Coordinates (click captcha) | ✅ | ❌ |
+| Yandex SmartCaptcha Image | ✅ | - |
+| Coordinates (click captcha) | ✅ | - |
 | Tencent | ✅ | ✅ |
 
+A dash (`-`) means that this CAPTCHA type has no separate task class that accepts
+your own proxy; it does not indicate that solving the CAPTCHA is unsupported.
+
 ## Client Reference
 
 Every method below is available on both `CaptchaClient` (sync, `requests`-based) and
@@ -207,14 +215,17 @@ solution -- wraps `create_task()` + `get_task_result()` so you don't poll by han
 
 Returns the `solution` dict once `status` is `"ready"` -- its shape depends on
 the task type (see [Captcha Types](#captcha-types)).
-Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
+Raises `ValidationError` before any request if `task` is not a task object or a
+required task parameter is missing or empty. Otherwise raises `ApiError`,
+`CaptchaTimeoutError`, or `NetworkError`.
 
 ### `create_task(task, language_pool=None)`
 
 Submits `task` and returns its numeric task ID without waiting for a solution.
 Accepts `task` and `language_pool`; it does not accept `timeout`. Use this instead of `solve()` if you need to
 manage polling yourself (e.g. checking on many tasks from a different process).
-Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
+Raises `ValidationError` before any request if `task` is invalid (same rules as
+`solve()`). Otherwise raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ### `get_task_result(task_id)`
 
@@ -479,7 +490,7 @@ print(result["validate"])
 print(result["seccode"])
 ```
 `challenge` is session-specific and expires quickly, so it can't be hardcoded
-into a static example -- see [examples/sync/geetest_v3.py](https://github.com/captcha-solver-api/python-sdk/blob/main/examples/sync/geetest_v3.py)
+into a static example -- see [examples/sync/geetest_v3_proxyless.py](https://github.com/captcha-solver-api/python-sdk/blob/main/examples/sync/geetest_v3_proxyless.py)
 for where the fetch belongs in the flow.
 
 ```python
@@ -499,11 +510,9 @@ With proxy, use `GeeTestTask` (same proxy fields as reCAPTCHA v2).
 <sup>[API method description.](https://captcha-solver.com/en/docs/captcha-types#yandex-smartcaptcha)</sup>
 
 Use this method to solve the token-based Yandex SmartCaptcha and obtain a token
-for the widget on the target page. Use the coordinates method for image challenges.
+for the widget on the target page. Use the dedicated image method for image challenges.
 
-`YandexSmartCaptchaTaskProxyless` / `YandexSmartCaptchaTask` -- token-based
-challenge. For the image challenge instead, use `CoordinatesTask` with
-[Coordinates](#coordinates-click-captcha) is available for generic click captchas.
+`YandexSmartCaptchaTaskProxyless` / `YandexSmartCaptchaTask` -- token-based challenge.
 
 | Parameter | Required | Description |
 |---|---|---|
@@ -532,15 +541,45 @@ print(result["token"])
 With proxy, use `YandexSmartCaptchaTask` (same proxy fields as reCAPTCHA v2,
 plus the `https` option above).
 
+#### Image challenge
+
+Use `YandexSmartCaptchaImageTask` when SmartCaptcha shows a main image and a
+separate strip indicating the symbols to click. The SDK sends API v2 type
+`SmartCaptchaTask`; both images must be base64-encoded.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `image` | yes | Main captcha image, base64-encoded. |
+| `imgInstructions` | yes | Click-order instruction image, base64-encoded. |
+| `comment` | no | Optional text hint for the worker. |
+
+**Response:** `coordinates` -- ordered `{"x": int, "y": int}` click positions.
+
+```python
+import base64
+from captcha_solver_api import CaptchaClient
+from captcha_solver_api.tasks import YandexSmartCaptchaImageTask
+
+with open("captcha.png", "rb") as f:
+    image = base64.b64encode(f.read()).decode("utf-8")
+with open("instructions.png", "rb") as f:
+    instructions = base64.b64encode(f.read()).decode("utf-8")
+
+task = YandexSmartCaptchaImageTask(
+    image=image,
+    imgInstructions=instructions,
+)
+result = CaptchaClient("your_api_key").solve(task)
+print(result["coordinates"])
+```
+
 ### Coordinates (click captcha)
 
 <sup>[API method description.](https://captcha-solver.com/en/docs/captcha-types#coordinates)</sup>
 
-Use this method to identify points that a worker should click in an image. It
-supports generic click captchas and the image version of Yandex SmartCaptcha.
+Use this method to identify points that a worker should click in a generic image.
 
-`CoordinatesTask`. Used both for generic "click on X" captchas and for Yandex
-SmartCaptcha's image challenge. No proxy variant -- the image is submitted directly.
+`CoordinatesTask`. No proxy variant -- the image is submitted directly.
 
 | Parameter | Required | Description |
 |---|---|---|
@@ -634,6 +673,16 @@ task lifetime. A local timeout does not cancel a task or mean that the API
 failed to solve it. Use `create_task()` and keep its `task_id` if you need to
 check the same task later; calling `solve()` again creates a new task.
 
+While polling, `solve()` retries short network failures and HTTP timeouts of
+`getTaskResult` on the next poll, so a brief outage does not lose an already
+created task. After `poll_retries` (default 3) consecutive failures the error is
+raised. API errors are not retried, and `createTask` is never retried because
+that could create and pay for a second task. To change the limit:
+
+```python
+client.poll_retries = 5
+```
+
 ### Worker language pool
 
 Set a default `language_pool` once at construction instead of passing it to every call:
@@ -703,13 +752,26 @@ try:
 except ValidationError as e:
     print(f"Invalid argument: {e}")
 except ApiError as e:
-    print(f"API error: {e.error_code} {e.error_description}")
-except CaptchaTimeoutError:
-    print("Task timed out")
+    print(f"API error: {e.error_code} {e.error_description} (task {e.task_id})")
+except CaptchaTimeoutError as e:
+    print(f"Task {e.task_id} timed out")
 except NetworkError as e:
     print(f"Network error: {e}")
 ```
 
+Every SDK error has a `task_id` attribute. It is set when the error happens
+after the task was created (while polling in `solve()` or in `get_task_result()`)
+and is `None` otherwise. A polling timeout does not cancel the task, so you can
+keep checking it:
+
+```python
+try:
+    result = client.solve(task)
+except CaptchaTimeoutError as e:
+    if e.task_id is not None:
+        status = client.get_task_result(e.task_id)
+```
+
 `TimeoutError` is still exported as a deprecated alias of `CaptchaTimeoutError`.
 Avoid importing it by name: it shadows Python's built-in `TimeoutError`.
 
@@ -718,16 +780,17 @@ Avoid importing it by name: it shadows Python's built-in `TimeoutError`.
 See the dedicated [examples documentation](https://github.com/captcha-solver-api/python-sdk/blob/main/examples/README.md) for the full
 sync/async example list, setup steps, expected results, and placeholder guidance.
 
-- **Image/click captchas** (`image_to_text.py`, `coordinates.py`) run after installing the dependencies and setting a valid
+- **Image/click captchas** (`image_to_text.py`, `coordinates.py`,
+  `yandex_smartcaptcha_image.py`) run after installing the dependencies and setting a valid
   `CAPTCHA_API_KEY` -- they read sample images bundled in
   [examples/assets](https://github.com/captcha-solver-api/python-sdk/tree/main/examples/assets), no target page needed.
   `python-dotenv` is optional: install it only if you want the scripts to load a `.env` file.
-- **Token captchas** (`recaptcha_v2.py`, `recaptcha_v2_enterprise.py`, `recaptcha_v3.py`,
-  `turnstile.py`, `yandex_smartcaptcha.py`, `geetest_v4.py`, `tencent.py`) use
+- **Token captchas** (`recaptcha_v2_*.py`, `recaptcha_v2_enterprise_*.py`, `recaptcha_v3.py`,
+  `turnstile_*.py`, `yandex_smartcaptcha_*.py`, `geetest_v4_*.py`, `tencent_*.py`) use
   placeholder values (`https://example.com/...`, `YOUR_WEBSITE_KEY`, `YOUR_APP_ID`,
   `YOUR_CAPTCHA_ID`) -- replace these with the real values from your own target
   page before running.
-- **`geetest_v3.py`** additionally needs `challenge` fetched fresh for every
+- **`geetest_v3_*.py`** additionally needs `challenge` fetched fresh for every
   request -- it's single-use and expires within seconds, so it can't be
   hardcoded into a static example. `"https://target-site.com/path/to/geetest/init"`
   is a placeholder; replace it with a request to your own target's equivalent
@@ -743,6 +806,7 @@ export CAPTCHA_API_KEY=your_api_key
 python examples/sync/balance.py
 python examples/sync/image_to_text.py
 python examples/sync/coordinates.py
+python examples/sync/yandex_smartcaptcha_image.py
 ```
 
 Live checks with real parameters have exercised all supported task types.
@@ -767,8 +831,8 @@ Full API reference: https://captcha-solver.com/en/docs/captcha-types
 - [Selenium Python examples](https://github.com/captcha-solver-api/captcha-solver-selenium-python-examples)
 - [JavaScript examples](https://github.com/captcha-solver-api/javascript-examples)
 - [Tencent CAPTCHA automation examples](https://github.com/captcha-solver-api/How-to-Automate-Tencent-CAPTCHA)
-- [Cloudflare Turnstile Puppeteer Demo](https://github.com/captcha-solver-api/cloudflare-turnstile-puppeteer-demo) — a working browser automation example for Cloudflare Turnstile.
-- [How to Automate Tencent CAPTCHA](https://captcha-solver.com/en/blog/how-to-automate-tencent-captcha) — a step-by-step guide with Python and JavaScript SDK examples.
+- [Cloudflare Turnstile Puppeteer Demo](https://github.com/captcha-solver-api/cloudflare-turnstile-puppeteer-demo) - a working browser automation example for Cloudflare Turnstile.
+- [How to Automate Tencent CAPTCHA](https://captcha-solver.com/en/blog/how-to-automate-tencent-captcha) - a step-by-step guide with Python and JavaScript SDK examples.
 
 ## License
 

captcha_solver_api-1.1.0/captcha_solver_api/_version.py

@@ -0,0 +1 @@
+__version__ = "1.1.0"

{captcha_solver_api-1.0.4 → captcha_solver_api-1.1.0}/captcha_solver_api/async_client.py

@@ -15,10 +15,12 @@ import httpx
 from ._version import __version__
 from .exceptions import (
     ApiError,
+    CaptchaError,
     CaptchaTimeoutError,
     NetworkError,
     ValidationError,
 )
+from .tasks import BaseTask
 
 
 class AsyncCaptchaClient:
@@ -42,7 +44,7 @@ class AsyncCaptchaClient:
             the account default. Can be overridden in `solve()` or `create_task()`.
 
     Raises:
-        ValidationError: `client_key` is empty.
+        ValidationError: `client_key` is missing, empty, or whitespace.
 
     Example:
         from captcha_solver_api import AsyncCaptchaClient
@@ -57,6 +59,10 @@ class AsyncCaptchaClient:
             token = solution["gRecaptchaResponse"]
     """
 
+    #: Consecutive `getTaskResult` network failures or HTTP timeouts that
+    #: `solve()` tolerates before raising. Each retry happens on the next poll.
+    poll_retries: int = 3
+
     def __init__(
         self,
         client_key: str,
@@ -84,9 +90,9 @@ class AsyncCaptchaClient:
                 pool.
 
         Raises:
-            ValidationError: `client_key` is empty.
+            ValidationError: `client_key` is missing, empty, or whitespace.
         """
-        if not client_key:
+        if not isinstance(client_key, str) or not client_key.strip():
             raise ValidationError("client_key is required")
 
         self.client_key = client_key
@@ -165,6 +171,8 @@ class AsyncCaptchaClient:
             The numeric task ID to pass to `get_task_result()`.
 
         Raises:
+            ValidationError: `task` is not a task object, or a required task
+                parameter is missing or empty. Raised before any request is sent.
             ApiError: The API rejected the task or its parameters.
             NetworkError: The request failed at the transport level.
             CaptchaTimeoutError: The HTTP request timed out.
@@ -172,6 +180,9 @@ class AsyncCaptchaClient:
         Example:
             task_id = await client.create_task(task, language_pool="en")
         """
+        if not isinstance(task, BaseTask):
+            raise ValidationError("task must be an instance of BaseTask")
+
         payload: Dict[str, Any] = {
             "clientKey": self.client_key,
             "task": task.to_dict(),
@@ -216,8 +227,12 @@ class AsyncCaptchaClient:
             "clientKey": self.client_key,
             "taskId": task_id,
         }
-        data = await self._request("getTaskResult", payload)
-        self._ensure_success(data)
+        try:
+            data = await self._request("getTaskResult", payload)
+            self._ensure_success(data)
+        except CaptchaError as exc:
+            exc.task_id = task_id
+            raise
         return data
 
     async def get_balance(self) -> float:
@@ -273,10 +288,17 @@ class AsyncCaptchaClient:
             or the README's method reference.
 
         Raises:
+            ValidationError: `task` is not a task object, or a required task
+                parameter is missing or empty. Raised before any request is sent.
             ApiError: The API rejected the task or reported a solving error.
             CaptchaTimeoutError: Polling exceeded its deadline or an HTTP request
                 timed out.
             NetworkError: A request failed or the API returned an invalid response.
+                While polling, up to `poll_retries` consecutive network failures or
+                HTTP timeouts are retried on the next poll before this is raised.
+
+            Errors raised after the task is created have `task_id` set, so the
+            task can still be checked with `get_task_result(exc.task_id)`.
 
         Example:
             from captcha_solver_api.tasks import RecaptchaV2TaskProxyless
@@ -292,18 +314,35 @@ class AsyncCaptchaClient:
         task_id = await self.create_task(task, language_pool=language_pool)
 
         deadline = time.monotonic() + (timeout if timeout is not None else self.timeout)
+        poll_failures = 0
 
         while time.monotonic() < deadline:
             remaining = deadline - time.monotonic()
             await asyncio.sleep(min(self.polling_interval, max(0, remaining)))
             if time.monotonic() >= deadline:
                 break
-            result = await self.get_task_result(task_id)
+            try:
+                result = await self.get_task_result(task_id)
+            except (NetworkError, CaptchaTimeoutError):
+                # getTaskResult is safe to repeat: retry a short transport
+                # failure on the next poll instead of losing a paid task.
+                poll_failures += 1
+                if poll_failures > self.poll_retries:
+                    raise
+                continue
+            poll_failures = 0
 
             if result.get("status") == "ready":
                 solution = result["solution"]
                 if not isinstance(solution, dict):
-                    raise NetworkError("API returned a ready task without a solution object")
+                    raise NetworkError(
+                        "API returned a ready task without a solution object",
+                        task_id=task_id,
+                    )
                 return solution
 
-        raise CaptchaTimeoutError("Task solving timed out.")
+        raise CaptchaTimeoutError(
+            f"Task {task_id} was not solved within the polling timeout. It may still "
+            f"be solved later: check it with get_task_result({task_id}).",
+            task_id=task_id,
+        )