python3-capsolver 1.2.0__tar.gz → 1.2.2__tar.gz

{python3_capsolver-1.2.0/src/python3_capsolver.egg-info → python3_capsolver-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python3-capsolver
-Version: 1.2.0
+Version: 1.2.2
 Summary: Python 3.8+ Capsolver library with AIO module.
 Author-email: AndreiDrang <python-captcha@pm.me>
 License: MIT License
@@ -21,6 +21,8 @@ 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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Framework :: AsyncIO
 Classifier: Operating System :: Unix
 Classifier: Operating System :: Microsoft :: Windows
@@ -30,7 +32,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.21.0
 Requires-Dist: aiohttp>=3.9.2
-Requires-Dist: msgspec<=0.21,>=0.18
+Requires-Dist: msgspec>=0.18
 Requires-Dist: tenacity<10,>=8
 Dynamic: license-file
 
@@ -62,6 +64,7 @@ Tested on UNIX based OS.
 The library is intended for software developers and is used to work with the [Capsolver](https://dashboard.capsolver.com/passport/register?inviteCode=kQTn-tG07Jb1) service API.
 
 ## Features
+- **Modern Tooling**: Uses `uv` for fast, reliable dependency management and environment isolation.
 - **Sync & Async Support**: Full support for both synchronous (`requests`) and asynchronous (`aiohttp`) operations.
 - **Type Safety**: Enums for captcha types and response statuses.
 - **Resilience**: Built-in retries using `tenacity`.
@@ -70,9 +73,21 @@ The library is intended for software developers and is used to work with the [Ca
 
 ## How to install?
 
-We recommend using the latest version of Python. `python3-capsolver` supports Python 3.7+.
+We recommend using the latest version of Python. `python3-capsolver` supports Python 3.8+.
 
-### pip
+### Development (using uv)
+
+This project uses [uv](https://github.com/astral-sh/uv) for fast, reliable dependency management.
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install project dependencies
+uv sync --all-groups
+```
+
+### Production (pip)
 
 ```bash
 pip install python3-capsolver
@@ -151,13 +166,28 @@ if __name__ == "__main__":
 
 ## How to test?
 
-1. You need set ``API_KEY`` in your environment(get this value from you account).
-2. Run command ``make tests``, from root directory.
+The project uses `uv` for testing and development tasks.
+
+```bash
+# 1. Set API_KEY in your environment (get this value from your account)
+export API_KEY="your_api_key_here"
+
+# 2. Run tests (uses uv internally)
+make tests
+
+# Other useful make targets:
+# make install     # Install dependencies with uv sync
+# make lint        # Run linting checks
+# make build       # Build the package
+# make doc         # Generate documentation
+```
+
+All `make` commands automatically use `uv` to run commands in the isolated environment.
 
 
 ### Changelog
 
-Check [releases page](https://github.com/AndreiDrang/python3-capsolver/releases).
+See [CHANGELOG.md](https://github.com/AndreiDrang/python3-capsolver/blob/main/CHANGELOG.md) for version history and detailed changes.
 
 ### How to get API Key to work with the library
 1. On the page - https://dashboard.capsolver.com/overview/user-center

{python3_capsolver-1.2.0 → python3_capsolver-1.2.2}/README.md

@@ -26,6 +26,7 @@ Tested on UNIX based OS.
 The library is intended for software developers and is used to work with the [Capsolver](https://dashboard.capsolver.com/passport/register?inviteCode=kQTn-tG07Jb1) service API.
 
 ## Features
+- **Modern Tooling**: Uses `uv` for fast, reliable dependency management and environment isolation.
 - **Sync & Async Support**: Full support for both synchronous (`requests`) and asynchronous (`aiohttp`) operations.
 - **Type Safety**: Enums for captcha types and response statuses.
 - **Resilience**: Built-in retries using `tenacity`.
@@ -34,9 +35,21 @@ The library is intended for software developers and is used to work with the [Ca
 
 ## How to install?
 
-We recommend using the latest version of Python. `python3-capsolver` supports Python 3.7+.
+We recommend using the latest version of Python. `python3-capsolver` supports Python 3.8+.
 
-### pip
+### Development (using uv)
+
+This project uses [uv](https://github.com/astral-sh/uv) for fast, reliable dependency management.
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install project dependencies
+uv sync --all-groups
+```
+
+### Production (pip)
 
 ```bash
 pip install python3-capsolver
@@ -115,13 +128,28 @@ if __name__ == "__main__":
 
 ## How to test?
 
-1. You need set ``API_KEY`` in your environment(get this value from you account).
-2. Run command ``make tests``, from root directory.
+The project uses `uv` for testing and development tasks.
+
+```bash
+# 1. Set API_KEY in your environment (get this value from your account)
+export API_KEY="your_api_key_here"
+
+# 2. Run tests (uses uv internally)
+make tests
+
+# Other useful make targets:
+# make install     # Install dependencies with uv sync
+# make lint        # Run linting checks
+# make build       # Build the package
+# make doc         # Generate documentation
+```
+
+All `make` commands automatically use `uv` to run commands in the isolated environment.
 
 
 ### Changelog
 
-Check [releases page](https://github.com/AndreiDrang/python3-capsolver/releases).
+See [CHANGELOG.md](https://github.com/AndreiDrang/python3-capsolver/blob/main/CHANGELOG.md) for version history and detailed changes.
 
 ### How to get API Key to work with the library
 1. On the page - https://dashboard.capsolver.com/overview/user-center

{python3_capsolver-1.2.0 → python3_capsolver-1.2.2}/pyproject.toml

@@ -78,6 +78,8 @@ classifiers = [
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
         "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Programming Language :: Python :: 3.14",
         "Framework :: AsyncIO",
         "Operating System :: Unix",
         "Operating System :: Microsoft :: Windows",
@@ -86,7 +88,7 @@ classifiers = [
 dependencies = [
     "requests>=2.21.0",
     "aiohttp>=3.9.2",
-    "msgspec>=0.18,<=0.21",
+    "msgspec>=0.18",
     "tenacity>=8,<10"
 ]
 

python3_capsolver-1.2.2/src/python3_capsolver/__version__.py

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

{python3_capsolver-1.2.0 → python3_capsolver-1.2.2}/src/python3_capsolver/core/aio_captcha_instrument.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 import asyncio
 import logging
-from typing import Optional
+from typing import TYPE_CHECKING
 from urllib import parse
 
 import aiohttp
@@ -11,6 +13,9 @@ from .utils import attempts_generator
 from .serializer import CaptchaResponseSer
 from .captcha_instrument import CaptchaInstrumentBase
 
+if TYPE_CHECKING:
+    from .base import CaptchaParams
+
 __all__ = ("AIOCaptchaInstrument",)
 
 
@@ -19,7 +24,7 @@ class AIOCaptchaInstrument(CaptchaInstrumentBase):
     Instrument for working with async captcha
     """
 
-    def __init__(self, captcha_params: "CaptchaParams"):
+    def __init__(self, captcha_params: CaptchaParams):
         super().__init__()
         self.captcha_params = captcha_params
         self.created_task_data = CaptchaResponseSer
@@ -99,7 +104,7 @@ class AIOCaptchaInstrument(CaptchaInstrumentBase):
 
     @staticmethod
     async def send_post_request(
-        payload: Optional[dict] = None,
+        payload: dict | None = None,
         url_postfix: EndpointPostfixEnm = EndpointPostfixEnm.GET_BALANCE,
     ) -> dict:
         """

{python3_capsolver-1.2.0 → python3_capsolver-1.2.2}/src/python3_capsolver/core/sio_captcha_instrument.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 import time
 import logging
-from typing import Optional
+from typing import TYPE_CHECKING
 from urllib import parse
 
 import requests
@@ -12,6 +14,9 @@ from .utils import attempts_generator
 from .serializer import CaptchaResponseSer
 from .captcha_instrument import CaptchaInstrumentBase
 
+if TYPE_CHECKING:
+    from .base import CaptchaParams
+
 __all__ = ("SIOCaptchaInstrument",)
 
 
@@ -20,7 +25,7 @@ class SIOCaptchaInstrument(CaptchaInstrumentBase):
     Instrument for working with sync captcha
     """
 
-    def __init__(self, captcha_params: "CaptchaParams"):
+    def __init__(self, captcha_params: CaptchaParams):
         super().__init__()
         self.captcha_params = captcha_params
         self.created_task_data = CaptchaResponseSer
@@ -106,7 +111,7 @@ class SIOCaptchaInstrument(CaptchaInstrumentBase):
 
     @staticmethod
     def send_post_request(
-        payload: Optional[dict] = None,
+        payload: dict | None = None,
         session: requests.Session = requests.Session(),
         url_postfix: EndpointPostfixEnm = EndpointPostfixEnm.GET_BALANCE,
     ) -> dict:

{python3_capsolver-1.2.0 → python3_capsolver-1.2.2/src/python3_capsolver.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python3-capsolver
-Version: 1.2.0
+Version: 1.2.2
 Summary: Python 3.8+ Capsolver library with AIO module.
 Author-email: AndreiDrang <python-captcha@pm.me>
 License: MIT License
@@ -21,6 +21,8 @@ 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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Framework :: AsyncIO
 Classifier: Operating System :: Unix
 Classifier: Operating System :: Microsoft :: Windows
@@ -30,7 +32,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.21.0
 Requires-Dist: aiohttp>=3.9.2
-Requires-Dist: msgspec<=0.21,>=0.18
+Requires-Dist: msgspec>=0.18
 Requires-Dist: tenacity<10,>=8
 Dynamic: license-file
 
@@ -62,6 +64,7 @@ Tested on UNIX based OS.
 The library is intended for software developers and is used to work with the [Capsolver](https://dashboard.capsolver.com/passport/register?inviteCode=kQTn-tG07Jb1) service API.
 
 ## Features
+- **Modern Tooling**: Uses `uv` for fast, reliable dependency management and environment isolation.
 - **Sync & Async Support**: Full support for both synchronous (`requests`) and asynchronous (`aiohttp`) operations.
 - **Type Safety**: Enums for captcha types and response statuses.
 - **Resilience**: Built-in retries using `tenacity`.
@@ -70,9 +73,21 @@ The library is intended for software developers and is used to work with the [Ca
 
 ## How to install?
 
-We recommend using the latest version of Python. `python3-capsolver` supports Python 3.7+.
+We recommend using the latest version of Python. `python3-capsolver` supports Python 3.8+.
 
-### pip
+### Development (using uv)
+
+This project uses [uv](https://github.com/astral-sh/uv) for fast, reliable dependency management.
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install project dependencies
+uv sync --all-groups
+```
+
+### Production (pip)
 
 ```bash
 pip install python3-capsolver
@@ -151,13 +166,28 @@ if __name__ == "__main__":
 
 ## How to test?
 
-1. You need set ``API_KEY`` in your environment(get this value from you account).
-2. Run command ``make tests``, from root directory.
+The project uses `uv` for testing and development tasks.
+
+```bash
+# 1. Set API_KEY in your environment (get this value from your account)
+export API_KEY="your_api_key_here"
+
+# 2. Run tests (uses uv internally)
+make tests
+
+# Other useful make targets:
+# make install     # Install dependencies with uv sync
+# make lint        # Run linting checks
+# make build       # Build the package
+# make doc         # Generate documentation
+```
+
+All `make` commands automatically use `uv` to run commands in the isolated environment.
 
 
 ### Changelog
 
-Check [releases page](https://github.com/AndreiDrang/python3-capsolver/releases).
+See [CHANGELOG.md](https://github.com/AndreiDrang/python3-capsolver/blob/main/CHANGELOG.md) for version history and detailed changes.
 
 ### How to get API Key to work with the library
 1. On the page - https://dashboard.capsolver.com/overview/user-center

{python3_capsolver-1.2.0 → python3_capsolver-1.2.2}/src/python3_capsolver.egg-info/SOURCES.txt

@@ -30,6 +30,7 @@ src/python3_capsolver/core/enum.py
 src/python3_capsolver/core/serializer.py
 src/python3_capsolver/core/sio_captcha_instrument.py
 src/python3_capsolver/core/utils.py
+tests/test_aio_captcha_instrument.py
 tests/test_aws_waf.py
 tests/test_cloudflare.py
 tests/test_control.py
@@ -41,5 +42,6 @@ tests/test_image_to_text.py
 tests/test_instrument.py
 tests/test_mt_captcha.py
 tests/test_recaptcha.py
+tests/test_sio_captcha_instrument.py
 tests/test_vision_engine.py
 tests/test_yandex.py

{python3_capsolver-1.2.0 → python3_capsolver-1.2.2}/src/python3_capsolver.egg-info/requires.txt

@@ -1,4 +1,4 @@
 requests>=2.21.0
 aiohttp>=3.9.2
-msgspec<=0.21,>=0.18
+msgspec>=0.18
 tenacity<10,>=8

python3_capsolver-1.2.2/tests/test_aio_captcha_instrument.py

@@ -0,0 +1,186 @@
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from tests.conftest import BaseTest
+from python3_capsolver.core.base import CaptchaParams
+from python3_capsolver.core.enum import CaptchaTypeEnm, EndpointPostfixEnm
+from python3_capsolver.core.const import REQUEST_URL
+from python3_capsolver.core.aio_captcha_instrument import AIOCaptchaInstrument
+
+API_KEY_STUB = "unit-test-api-key-000000000000000000000000"
+CREATE_TASK_URL = "https://unit.test/createTask"
+GET_TASK_RESULT_URL = "https://unit.test/getTaskResult"
+
+
+def create_captcha_params() -> CaptchaParams:
+    """
+    Build params pointing to a fake API host with zero sleep between polls:
+    no real request can leave the mocked `aiohttp.ClientSession.post` boundary
+    """
+    return CaptchaParams(
+        api_key=API_KEY_STUB,
+        captcha_type=CaptchaTypeEnm.Control,
+        sleep_time=0,
+        request_url="https://unit.test/",
+    )
+
+
+def aio_response(payload=None, status: int = 200, reason: str = "unit test failure") -> MagicMock:
+    """
+    Build fake response for the `aiohttp` boundary, usable as async context manager.
+
+    For non-parsable bodies (``payload is None``) any ``json()`` call raises -
+    an error status must never be parsed as a success body
+    """
+    response = MagicMock()
+    response.status = status
+    response.reason = reason
+    if payload is None:
+        response.json = AsyncMock(side_effect=AssertionError("body of an error response must not be parsed"))
+    else:
+        response.json = AsyncMock(return_value=payload)
+    response.__aenter__.return_value = response
+    return response
+
+
+class TestAIOCaptchaInstrument(BaseTest):
+    """
+    Mocked unit tests for AIOCaptchaInstrument
+    """
+
+    @patch("python3_capsolver.core.aio_captcha_instrument.aiohttp.ClientSession.post")
+    async def test_returns_created_result_without_polling_when_task_is_ready(self, mock_post):
+        mock_post.return_value = aio_response(
+            {"errorId": 0, "taskId": "task-ready-1", "status": "ready", "solution": {"text": "wg6x"}}
+        )
+
+        result = await AIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["errorId"] == 0
+        assert result["status"] == "ready"
+        assert result["taskId"] == "task-ready-1"
+        assert result["solution"] == {"text": "wg6x"}
+        # task was solved at creation - no `getTaskResult` polling must follow
+        mock_post.assert_called_once()
+        assert mock_post.call_args.args[0] == CREATE_TASK_URL
+        assert mock_post.call_args.kwargs["json"]["task"] == {"type": "Control"}
+        assert mock_post.call_args.kwargs["json"]["clientKey"] == API_KEY_STUB
+
+    @patch("python3_capsolver.core.aio_captcha_instrument.aiohttp.ClientSession.post")
+    async def test_polls_get_task_result_until_ready(self, mock_post):
+        mock_post.side_effect = [
+            aio_response({"errorId": 0, "taskId": "task-42", "status": "processing"}),
+            aio_response({"errorId": 0, "taskId": "task-42", "status": "processing"}),
+            aio_response({"errorId": 0, "taskId": "task-42", "status": "ready", "solution": {"text": "ab12"}}),
+        ]
+
+        result = await AIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["errorId"] == 0
+        assert result["status"] == "ready"
+        assert result["solution"] == {"text": "ab12"}
+        assert [call.args[0] for call in mock_post.call_args_list] == [
+            CREATE_TASK_URL,
+            GET_TASK_RESULT_URL,
+            GET_TASK_RESULT_URL,
+        ]
+        # created taskId must be propagated to every polling request
+        assert mock_post.call_args_list[1].kwargs["json"]["taskId"] == "task-42"
+        assert mock_post.call_args_list[2].kwargs["json"]["taskId"] == "task-42"
+
+    @patch("python3_capsolver.core.aio_captcha_instrument.aiohttp.ClientSession.post")
+    async def test_returns_failed_result_when_polling_reports_failure(self, mock_post):
+        mock_post.side_effect = [
+            aio_response({"errorId": 0, "taskId": "task-42", "status": "processing"}),
+            aio_response({"errorId": 1, "errorCode": "ERROR_TASK_NOT_FOUND", "status": "failed"}),
+        ]
+
+        result = await AIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["errorId"] == 1
+        assert result["status"] == "failed"
+        assert result["errorCode"] == "ERROR_TASK_NOT_FOUND"
+        assert len(mock_post.call_args_list) == 2
+
+    @patch("python3_capsolver.core.aio_captcha_instrument.aiohttp.ClientSession.post")
+    async def test_marks_result_failed_when_task_creation_is_rejected(self, mock_post):
+        mock_post.return_value = aio_response(
+            {"errorId": 1, "errorCode": "ERROR_KEY_DOES_NOT_EXIST", "errorDescription": "Client key is invalid"}
+        )
+
+        result = await AIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["errorId"] == 1
+        assert result["status"] == "failed"
+        assert result["errorCode"] == "ERROR_KEY_DOES_NOT_EXIST"
+        assert result["errorDescription"] == "Client key is invalid"
+        # rejected creation must not trigger result polling
+        mock_post.assert_called_once()
+
+    @patch("python3_capsolver.core.aio_captcha_instrument.aiohttp.ClientSession.post")
+    async def test_parses_error_payload_when_status_code_is_valid_error_status(self, mock_post):
+        mock_post.return_value = aio_response({"errorId": 1, "errorCode": "ERROR_WRONG_USERKEY"}, status=400)
+
+        result = await AIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["status"] == "failed"
+        assert result["errorCode"] == "ERROR_WRONG_USERKEY"
+
+    @patch("python3_capsolver.core.aio_captcha_instrument.aiohttp.ClientSession.post")
+    async def test_returns_unsolvable_default_when_server_never_finishes(self, mock_post):
+        mock_post.side_effect = [aio_response({"errorId": 0, "taskId": "task-silent", "status": "processing"})] * 16
+
+        result = await AIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["errorId"] == 1
+        assert result["errorCode"] == "ERROR_CAPTCHA_UNSOLVABLE"
+        assert result["errorDescription"] == "Captcha not recognized"
+        assert result["status"] == "failed"
+        assert result["taskId"] == "task-silent"
+        # 1 `createTask` + 15 polling attempts, then the instrument gives up
+        assert len(mock_post.call_args_list) == 16
+
+    @pytest.mark.parametrize("bad_status", [404, 500])
+    @patch("python3_capsolver.core.aio_captcha_instrument.aiohttp.ClientSession.post")
+    async def test_raises_when_create_task_returns_invalid_status(self, mock_post, bad_status):
+        mock_post.return_value = aio_response(status=bad_status, reason="Internal Server Error")
+
+        with pytest.raises(ValueError):
+            await AIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        mock_post.assert_called_once()
+
+    @patch("python3_capsolver.core.aio_captcha_instrument.aiohttp.ClientSession.post")
+    async def test_raises_when_get_task_result_returns_invalid_status(self, mock_post):
+        mock_post.side_effect = [
+            aio_response({"errorId": 0, "taskId": "task-42", "status": "processing"}),
+            aio_response(status=503, reason="Service Unavailable"),
+        ]
+
+        with pytest.raises(ValueError):
+            await AIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert len(mock_post.call_args_list) == 2
+
+    @patch("python3_capsolver.core.aio_captcha_instrument.aiohttp.ClientSession.post")
+    async def test_send_post_request_returns_decoded_payload(self, mock_post):
+        mock_post.return_value = aio_response({"errorId": 0, "balance": 107.7})
+
+        result = await AIOCaptchaInstrument.send_post_request(
+            payload={"clientKey": API_KEY_STUB},
+            url_postfix=EndpointPostfixEnm.GET_BALANCE,
+        )
+
+        assert result == {"errorId": 0, "balance": 107.7}
+        assert mock_post.call_args.args[0] == f"{REQUEST_URL}/{EndpointPostfixEnm.GET_BALANCE.value}"
+        assert mock_post.call_args.kwargs["json"] == {"clientKey": API_KEY_STUB}
+
+    @patch("python3_capsolver.core.aio_captcha_instrument.aiohttp.ClientSession.post")
+    async def test_send_post_request_raises_for_error_status(self, mock_post):
+        mock_post.return_value = aio_response(status=403)
+
+        with pytest.raises(ValueError):
+            await AIOCaptchaInstrument.send_post_request(payload={"clientKey": API_KEY_STUB})
+
+        mock_post.assert_called_once()

{python3_capsolver-1.2.0 → python3_capsolver-1.2.2}/tests/test_instrument.py

@@ -1,3 +1,5 @@
+from unittest.mock import MagicMock, patch
+
 import pytest
 
 from tests.conftest import BaseTest
@@ -11,8 +13,8 @@ class TestFileInstrument(BaseTest):
     """
 
     def test_file_processing_exist(self):
-        assert "file_processing" in FileInstrument.__dict__.keys()
-        assert "aio_file_processing" in FileInstrument.__dict__.keys()
+        assert "file_processing" in FileInstrument.__dict__
+        assert "aio_file_processing" in FileInstrument.__dict__
 
     def test_captcha_base64(self):
         assert self.read_image_as_str() == FileInstrument().file_processing(captcha_base64=self.read_image())
@@ -55,3 +57,15 @@ class TestFileInstrument(BaseTest):
     async def test_aio_file_processing_err(self):
         with pytest.raises(ValueError):
             await FileInstrument().aio_file_processing()
+
+    @patch("python3_capsolver.core.captcha_instrument.aiohttp.ClientSession.get")
+    async def test_aio_captcha_link_download_err(self, mock_get):
+        mock_response = MagicMock()
+        mock_response.status = 404
+        mock_response.__aenter__.return_value = mock_response
+        mock_get.return_value = mock_response
+
+        result = await FileInstrument().aio_file_processing(captcha_link=self.image_captcha_url_example)
+
+        # unreachable link returns empty content instead of raising
+        assert result == ""

python3_capsolver-1.2.2/tests/test_sio_captcha_instrument.py

@@ -0,0 +1,185 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from tests.conftest import BaseTest
+from python3_capsolver.core.base import CaptchaParams
+from python3_capsolver.core.enum import CaptchaTypeEnm, EndpointPostfixEnm
+from python3_capsolver.core.const import REQUEST_URL
+from python3_capsolver.core.sio_captcha_instrument import SIOCaptchaInstrument
+
+API_KEY_STUB = "unit-test-api-key-000000000000000000000000"
+CREATE_TASK_URL = "https://unit.test/createTask"
+GET_TASK_RESULT_URL = "https://unit.test/getTaskResult"
+
+
+def create_captcha_params() -> CaptchaParams:
+    """
+    Build params pointing to a fake API host with zero sleep between polls:
+    no real request can leave the mocked `Session.post` boundary
+    """
+    return CaptchaParams(
+        api_key=API_KEY_STUB,
+        captcha_type=CaptchaTypeEnm.Control,
+        sleep_time=0,
+        request_url="https://unit.test/",
+    )
+
+
+def sio_response(payload=None, status_code: int = 200) -> MagicMock:
+    """
+    Build fake response for the `requests` boundary.
+
+    For non-parsable bodies (``payload is None``) any ``json()`` call raises -
+    an error status must never be parsed as a success body
+    """
+    response = MagicMock()
+    response.status_code = status_code
+    if payload is None:
+        response.json.side_effect = AssertionError("body of an error response must not be parsed")
+    else:
+        response.json.return_value = payload
+    response.raise_for_status.return_value = None
+    return response
+
+
+class TestSIOCaptchaInstrument(BaseTest):
+    """
+    Mocked unit tests for SIOCaptchaInstrument
+    """
+
+    @patch("python3_capsolver.core.sio_captcha_instrument.requests.Session.post")
+    def test_returns_created_result_without_polling_when_task_is_ready(self, mock_post):
+        mock_post.return_value = sio_response(
+            {"errorId": 0, "taskId": "task-ready-1", "status": "ready", "solution": {"text": "wg6x"}}
+        )
+
+        result = SIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["errorId"] == 0
+        assert result["status"] == "ready"
+        assert result["taskId"] == "task-ready-1"
+        assert result["solution"] == {"text": "wg6x"}
+        # task was solved at creation - no `getTaskResult` polling must follow
+        mock_post.assert_called_once()
+        assert mock_post.call_args.args[0] == CREATE_TASK_URL
+        assert mock_post.call_args.kwargs["json"]["task"] == {"type": "Control"}
+        assert mock_post.call_args.kwargs["json"]["clientKey"] == API_KEY_STUB
+
+    @patch("python3_capsolver.core.sio_captcha_instrument.requests.Session.post")
+    def test_polls_get_task_result_until_ready(self, mock_post):
+        mock_post.side_effect = [
+            sio_response({"errorId": 0, "taskId": "task-42", "status": "processing"}),
+            sio_response({"errorId": 0, "taskId": "task-42", "status": "processing"}),
+            sio_response({"errorId": 0, "taskId": "task-42", "status": "ready", "solution": {"text": "ab12"}}),
+        ]
+
+        result = SIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["errorId"] == 0
+        assert result["status"] == "ready"
+        assert result["solution"] == {"text": "ab12"}
+        assert [call.args[0] for call in mock_post.call_args_list] == [
+            CREATE_TASK_URL,
+            GET_TASK_RESULT_URL,
+            GET_TASK_RESULT_URL,
+        ]
+        # created taskId must be propagated to every polling request
+        assert mock_post.call_args_list[1].kwargs["json"]["taskId"] == "task-42"
+        assert mock_post.call_args_list[2].kwargs["json"]["taskId"] == "task-42"
+
+    @patch("python3_capsolver.core.sio_captcha_instrument.requests.Session.post")
+    def test_returns_failed_result_when_polling_reports_failure(self, mock_post):
+        mock_post.side_effect = [
+            sio_response({"errorId": 0, "taskId": "task-42", "status": "processing"}),
+            sio_response({"errorId": 1, "errorCode": "ERROR_TASK_NOT_FOUND", "status": "failed"}),
+        ]
+
+        result = SIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["errorId"] == 1
+        assert result["status"] == "failed"
+        assert result["errorCode"] == "ERROR_TASK_NOT_FOUND"
+        assert len(mock_post.call_args_list) == 2
+
+    @patch("python3_capsolver.core.sio_captcha_instrument.requests.Session.post")
+    def test_marks_result_failed_when_task_creation_is_rejected(self, mock_post):
+        mock_post.return_value = sio_response(
+            {"errorId": 1, "errorCode": "ERROR_KEY_DOES_NOT_EXIST", "errorDescription": "Client key is invalid"}
+        )
+
+        result = SIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["errorId"] == 1
+        assert result["status"] == "failed"
+        assert result["errorCode"] == "ERROR_KEY_DOES_NOT_EXIST"
+        assert result["errorDescription"] == "Client key is invalid"
+        # rejected creation must not trigger result polling
+        mock_post.assert_called_once()
+
+    @patch("python3_capsolver.core.sio_captcha_instrument.requests.Session.post")
+    def test_parses_error_payload_when_status_code_is_valid_error_status(self, mock_post):
+        mock_post.return_value = sio_response({"errorId": 1, "errorCode": "ERROR_WRONG_USERKEY"}, status_code=400)
+
+        result = SIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["status"] == "failed"
+        assert result["errorCode"] == "ERROR_WRONG_USERKEY"
+
+    @patch("python3_capsolver.core.sio_captcha_instrument.requests.Session.post")
+    def test_returns_unsolvable_default_when_server_never_finishes(self, mock_post):
+        mock_post.side_effect = [sio_response({"errorId": 0, "taskId": "task-silent", "status": "processing"})] * 16
+
+        result = SIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert result["errorId"] == 1
+        assert result["errorCode"] == "ERROR_CAPTCHA_UNSOLVABLE"
+        assert result["errorDescription"] == "Captcha not recognized"
+        assert result["status"] == "failed"
+        assert result["taskId"] == "task-silent"
+        # 1 `createTask` + 15 polling attempts, then the instrument gives up
+        assert len(mock_post.call_args_list) == 16
+
+    @pytest.mark.parametrize("bad_status", [404, 500])
+    @patch("python3_capsolver.core.sio_captcha_instrument.requests.Session.post")
+    def test_raises_when_create_task_returns_invalid_status(self, mock_post, bad_status):
+        mock_post.return_value = sio_response(status_code=bad_status)
+
+        with pytest.raises(ValueError):
+            SIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        mock_post.assert_called_once()
+
+    @patch("python3_capsolver.core.sio_captcha_instrument.requests.Session.post")
+    def test_raises_when_get_task_result_returns_invalid_status(self, mock_post):
+        mock_post.side_effect = [
+            sio_response({"errorId": 0, "taskId": "task-42", "status": "processing"}),
+            sio_response(status_code=503),
+        ]
+
+        with pytest.raises(ValueError):
+            SIOCaptchaInstrument(captcha_params=create_captcha_params()).processing_captcha()
+
+        assert len(mock_post.call_args_list) == 2
+
+    @patch("python3_capsolver.core.sio_captcha_instrument.requests.Session.post")
+    def test_send_post_request_returns_decoded_payload(self, mock_post):
+        mock_post.return_value = sio_response({"errorId": 0, "balance": 107.7})
+
+        result = SIOCaptchaInstrument.send_post_request(
+            payload={"clientKey": API_KEY_STUB},
+            url_postfix=EndpointPostfixEnm.GET_BALANCE,
+        )
+
+        assert result == {"errorId": 0, "balance": 107.7}
+        assert mock_post.call_args.args[0] == f"{REQUEST_URL}/{EndpointPostfixEnm.GET_BALANCE.value}"
+        assert mock_post.call_args.kwargs["json"] == {"clientKey": API_KEY_STUB}
+
+    @patch("python3_capsolver.core.sio_captcha_instrument.requests.Session.post")
+    def test_send_post_request_raises_for_error_status(self, mock_post):
+        mock_post.return_value = sio_response(status_code=403)
+
+        with pytest.raises(ValueError):
+            SIOCaptchaInstrument.send_post_request(payload={"clientKey": API_KEY_STUB})
+
+        mock_post.assert_called_once()

python3_capsolver-1.2.0/src/python3_capsolver/__version__.py

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