python3-capsolver 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

python3_capsolver/__version__.py

@@ -1 +1 @@
-__version__ = "1.1.0"
+__version__ = "1.2.0"

python3_capsolver/core/aio_captcha_instrument.py

@@ -30,6 +30,8 @@ class AIOCaptchaInstrument(CaptchaInstrumentBase):
 
         # if task created and already ready - return result
         if self.created_task_data.errorId == 0:
+            if str(self.created_task_data.status).lower() == ResponseStatusEnm.Ready.value:
+                return self.created_task_data.to_dict()
             return (await self.__get_result()).to_dict()
         else:
             self.created_task_data.status = ResponseStatusEnm.Failed
@@ -72,7 +74,10 @@ class AIOCaptchaInstrument(CaptchaInstrumentBase):
                     ) as resp:
                         if resp.status in VALID_STATUS_CODES:
                             result_data = CaptchaResponseSer(**await resp.json())
-                            if result_data.status in (ResponseStatusEnm.Ready, ResponseStatusEnm.Failed):
+                            if result_data.status in (
+                                ResponseStatusEnm.Ready,
+                                ResponseStatusEnm.Failed,
+                            ):
                                 # if captcha ready\failed or have unknown status - return exist data
                                 return result_data
                         else:
@@ -90,10 +95,12 @@ class AIOCaptchaInstrument(CaptchaInstrumentBase):
         self.result.errorDescription = self.CAPTCHA_UNSOLVABLE_DESCRIPTION
         self.result.taskId = self.created_task_data.taskId
         self.result.status = ResponseStatusEnm.Failed
+        return self.result
 
     @staticmethod
     async def send_post_request(
-        payload: Optional[dict] = None, url_postfix: EndpointPostfixEnm = EndpointPostfixEnm.GET_BALANCE
+        payload: Optional[dict] = None,
+        url_postfix: EndpointPostfixEnm = EndpointPostfixEnm.GET_BALANCE,
     ) -> dict:
         """
         Function send ASYNC request to service and wait for result

python3_capsolver/core/captcha_instrument.py

@@ -83,7 +83,10 @@ class FileInstrument:
             async for attempt in ASYNC_RETRIES:
                 with attempt:
                     async with session.get(url=url, **kwargs) as resp:
-                        return await resp.content.read()
+                        if resp.status == 200:
+                            return await resp.content.read()
+                        return b""
+        return b""
 
     def file_processing(
         self,

python3_capsolver/core/serializer.py

@@ -1,12 +1,18 @@
 from enum import Enum
-from typing import Any, Dict, Literal, Optional
+from typing import Any, Dict, Union, Optional
 
 from msgspec import Struct
 
 from .enum import ResponseStatusEnm
 from .const import APP_ID
 
-__all__ = ("PostRequestSer", "TaskSer", "RequestCreateTaskSer", "CaptchaResponseSer", "RequestGetTaskResultSer")
+__all__ = (
+    "PostRequestSer",
+    "TaskSer",
+    "RequestCreateTaskSer",
+    "CaptchaResponseSer",
+    "RequestGetTaskResultSer",
+)
 
 
 class MyBaseModel(Struct):
@@ -36,7 +42,7 @@ class TaskSer(MyBaseModel):
 
 
 class RequestCreateTaskSer(PostRequestSer):
-    appId: Literal[APP_ID] = APP_ID
+    appId: str = APP_ID
 
 
 class RequestGetTaskResultSer(MyBaseModel):
@@ -58,5 +64,5 @@ class ResponseSer(MyBaseModel):
 
 class CaptchaResponseSer(ResponseSer):
     taskId: Optional[str] = None
-    status: ResponseStatusEnm = ResponseStatusEnm.Processing
+    status: Union[ResponseStatusEnm, str] = ResponseStatusEnm.Processing
     solution: Optional[Dict[str, Any]] = None

python3_capsolver/core/sio_captcha_instrument.py

@@ -24,6 +24,7 @@ class SIOCaptchaInstrument(CaptchaInstrumentBase):
         super().__init__()
         self.captcha_params = captcha_params
         self.created_task_data = CaptchaResponseSer
+
         # prepare session
         self.session = requests.Session()
         self.session.mount("http://", HTTPAdapter(max_retries=RETRIES))
@@ -37,6 +38,8 @@ class SIOCaptchaInstrument(CaptchaInstrumentBase):
 
         # if task created and ready - return result
         if self.created_task_data.errorId == 0:
+            if str(self.created_task_data.status).lower() == ResponseStatusEnm.Ready.value:
+                return self.created_task_data.to_dict()
             return self.__get_result().to_dict()
         else:
             self.created_task_data.status = ResponseStatusEnm.Failed
@@ -78,7 +81,10 @@ class SIOCaptchaInstrument(CaptchaInstrumentBase):
                 )
                 if resp.status_code in VALID_STATUS_CODES:
                     result_data = CaptchaResponseSer(**resp.json())
-                    if result_data.status in (ResponseStatusEnm.Ready, ResponseStatusEnm.Failed):
+                    if result_data.status in (
+                        ResponseStatusEnm.Ready,
+                        ResponseStatusEnm.Failed,
+                    ):
                         # if captcha ready\failed or have unknown status - return exist data
                         return result_data
                 else:
@@ -89,12 +95,14 @@ class SIOCaptchaInstrument(CaptchaInstrumentBase):
 
             # if captcha just created or in processing now - wait
             time.sleep(self.captcha_params.sleep_time)
+
         # default response if server is silent
         self.result.errorId = 1
         self.result.errorCode = self.CAPTCHA_UNSOLVABLE
         self.result.errorDescription = self.CAPTCHA_UNSOLVABLE_DESCRIPTION
         self.result.taskId = self.created_task_data.taskId
         self.result.status = ResponseStatusEnm.Failed
+        return self.result
 
     @staticmethod
     def send_post_request(

python3_capsolver/image_to_text.py

@@ -83,7 +83,12 @@ class ImageToText(CaptchaParams):
     """
 
     def __init__(
-        self, api_key: str, captcha_type: Union[CaptchaTypeEnm, str] = CaptchaTypeEnm.ImageToTextTask, **kwargs
+        self,
+        api_key: str,
+        captcha_type: Union[CaptchaTypeEnm, str] = CaptchaTypeEnm.ImageToTextTask,
+        **kwargs,
     ):
+        if isinstance(captcha_type, str):
+            captcha_type = CaptchaTypeEnm(captcha_type)
 
         super().__init__(api_key=api_key, captcha_type=captcha_type, **kwargs)

{python3_capsolver-1.1.0.dist-info → python3_capsolver-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python3-capsolver
-Version: 1.1.0
+Version: 1.2.0
 Summary: Python 3.8+ Capsolver library with AIO module.
 Author-email: AndreiDrang <python-captcha@pm.me>
 License: MIT License
@@ -30,7 +30,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.20,>=0.18
+Requires-Dist: msgspec<=0.21,>=0.18
 Requires-Dist: tenacity<10,>=8
 Dynamic: license-file
 
@@ -61,6 +61,13 @@ 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
+- **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`.
+- **Performance**: High-speed JSON serialization with `msgspec`.
+- **Coverage**: Supports ReCaptcha (V2/V3), Cloudflare, DataDome, GeeTest, MtCaptcha, AWS WAF, Yandex, and ImageToText.
+
 ## How to install?
 
 We recommend using the latest version of Python. `python3-capsolver` supports Python 3.7+.
@@ -73,8 +80,74 @@ pip install python3-capsolver
 
 ## How to use?
 
-Is described in the [documentation-website](https://andreidrang.github.io/python3-capsolver/).
+Detailed documentation is available on the [website](https://andreidrang.github.io/python3-capsolver/).
+
+### Quick Start
+
+#### Synchronous Example (ImageToText)
+```python
+from python3_capsolver.image_to_text import ImageToText
+
+# 1. Initialize with API Key
+solver = ImageToText(api_key="YOUR_API_KEY")
+
+# 2. Solve
+result = solver.captcha_handler(
+    task_payload={
+        "body": "base64_encoded_image_string"
+    }
+)
+
+# 3. Check result
+if result["errorId"] == 0:
+    print("Solution:", result["solution"])
+else:
+    print("Error:", result["errorCode"])
+```
+
+#### Asynchronous Example (ReCaptcha)
+```python
+import asyncio
+from python3_capsolver.recaptcha import ReCaptcha
+from python3_capsolver.core.enum import CaptchaTypeEnm
+
+async def main():
+    # 1. Initialize
+    solver = ReCaptcha(
+        api_key="YOUR_API_KEY", 
+        captcha_type=CaptchaTypeEnm.ReCaptchaV2TaskProxyLess
+    )
+
+    # 2. Solve
+    result = await solver.aio_captcha_handler(
+        task_payload={
+            "websiteURL": "https://example.com",
+            "websiteKey": "SITE_KEY"
+        }
+    )
+    
+    print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
 
+## Supported Captcha Types
+- **ReCaptcha**: V2 (Task/Enterprise), V3 (Task/Enterprise)
+- **HCaptcha**: Task, Enterprise
+- **Cloudflare**: Turnstile
+- **GeeTest**: V3, V4
+- **DataDome**: Slider
+- **MtCaptcha**
+- **AWS WAF**
+- **Yandex SmartCaptcha**
+- **ImageToText**: General image CAPTCHAs
+
+## Documentation & Context (For LLMs)
+- **Project Structure**: See `AGENTS.md` in root and subdirectories for internal architecture.
+- **Entry Points**: `src/python3_capsolver/*.py` contains service-specific classes (e.g., `ReCaptcha`, `HCaptcha`).
+- **Core Logic**: `src/python3_capsolver/core/base.py` handles the API communication loop.
+- **Enums**: Use `python3_capsolver.core.enum` for type-safe parameters.
 
 ## How to test?
 

{python3_capsolver-1.1.0.dist-info → python3_capsolver-1.2.0.dist-info}/RECORD

@@ -1,28 +1,28 @@
 python3_capsolver/__init__.py,sha256=141uoiYvgRblIWZAy7AhQJz6iVqzY4b5cLxExIaKUlg,62
-python3_capsolver/__version__.py,sha256=LGVQyDsWifdACo7qztwb8RWWHds1E7uQ-ZqD8SAjyw4,22
+python3_capsolver/__version__.py,sha256=MpAT5hgNoHnTtG1XRD_GV_A7QrHVU6vJjGSw_8qMGA4,22
 python3_capsolver/aws_waf.py,sha256=wwNjW2bkS-EdxEkTDxW9zwUGCnW_bbEhtruSgw_R94I,5677
 python3_capsolver/cloudflare.py,sha256=SCuC4femAkNWY9taGELuGiGI8mDI5N2ziWAewNhAQrI,5367
 python3_capsolver/control.py,sha256=TEhH2xGpJVX5QSiH3senhqoASnuJlDiFZfEZ1CLD1oA,16982
 python3_capsolver/datadome_slider.py,sha256=kh15W30CQl-RgzcyCm_2ldluYAvbjyTl3mS9SFGj51k,2805
 python3_capsolver/friendly_captcha.py,sha256=S1nenBwG3P2hiB-In13tWMNnITou68s8q-h3QXplubI,4412
 python3_capsolver/gee_test.py,sha256=VjBOVggAkVRx6pGRys8kXl0-ZLFNCOMSYK_Bn95zk7o,2903
-python3_capsolver/image_to_text.py,sha256=i3ezTvy4cZD98LhVisyWINTbnHf08EKCGYGS_G_XH6o,3372
+python3_capsolver/image_to_text.py,sha256=lYEzENjEoKlBMFiyjGeLHgpczZaa184_X5MPommIOgs,3495
 python3_capsolver/mt_captcha.py,sha256=mtHyqGat34odh_2KLBviEHMxnFi3SSSvRaVQAE1k0HA,2267
 python3_capsolver/recaptcha.py,sha256=tiZPC_OGfhA30SH6lnqo2curVDLDwGwGLvx1zVn3gYY,3052
 python3_capsolver/vision_engine.py,sha256=h82S6NvRbQTQUPTsLKQ1xpGMzlqHXaDGRRtDOSa275Q,2918
 python3_capsolver/yandex.py,sha256=4NvopCD9pKVyUNLlQqj2Yra3n_YY0NG8Gqc5sVK9Yis,2770
 python3_capsolver/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-python3_capsolver/core/aio_captcha_instrument.py,sha256=iYbML1dL2X_y7zaqPKhI93K2Ye4-DQQ8ewAVNDudiaE,4532
+python3_capsolver/core/aio_captcha_instrument.py,sha256=9LYx51KodjbDUZ0pcNxlSEW5KCqHQAiPfhCwF2J0PYE,4811
 python3_capsolver/core/base.py,sha256=WScd52oKm28EE-yxOibYwlJRlaZH_q5sFzs8ynQwau0,3110
-python3_capsolver/core/captcha_instrument.py,sha256=tdpfV-3zayJrAqHRSvDz4Ac2JejwKu5zh0nTl5aLPcY,9157
+python3_capsolver/core/captcha_instrument.py,sha256=Lg2fe0mpIre6z5Mb1LDvjHmbi-16BJ5zDS3_sJbMvXE,9262
 python3_capsolver/core/const.py,sha256=AEU2IFQ6xbMRGdXzBNtZflxNFJ4VTshGx1skBtdrQ2w,613
 python3_capsolver/core/context_instr.py,sha256=x3JQNd1ydlNdhuGKX_5gc-5Duq2pZJME0fs2YMQyGv4,503
 python3_capsolver/core/enum.py,sha256=M4gfCzzkIMQ8JZd3qwFsA1iXW8cbfYFxJGTxiVvTUsE,2490
-python3_capsolver/core/serializer.py,sha256=rE7VX_6FCisOnK-HS4K90LkuWU3cOVa6GwkvbFgjhnA,1342
-python3_capsolver/core/sio_captcha_instrument.py,sha256=NVYS93ZuW2yOaYXla66nKHTDp0Ac4Qn4pZxYfm7Nr3A,4433
+python3_capsolver/core/serializer.py,sha256=048uf015XtPirdtdijDxpO8sg3xoDIFXucUwmHKLUMo,1363
+python3_capsolver/core/sio_captcha_instrument.py,sha256=LZlcftx_L8IjB0xhH2dFdbd7No_l8ZDSS9aX02feWn8,4681
 python3_capsolver/core/utils.py,sha256=5PMxryy22MIUmUXPIHqz38vg2C2bqa7uXHUNYRF8DlY,633
-python3_capsolver-1.1.0.dist-info/licenses/LICENSE,sha256=N_utAsqhTp1pXXp-PTE-CFMg5BfIIqTbF-phwwzOHeQ,1063
-python3_capsolver-1.1.0.dist-info/METADATA,sha256=8E9C3Dl89H0gqLBRTIu6l13H_c3DLPKqNHvbD7UARK0,5370
-python3_capsolver-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-python3_capsolver-1.1.0.dist-info/top_level.txt,sha256=yws7CqjoBfrn2ebCkAQmEaVlZ-zhbtflqpCDwAEX4kI,18
-python3_capsolver-1.1.0.dist-info/RECORD,,
+python3_capsolver-1.2.0.dist-info/licenses/LICENSE,sha256=N_utAsqhTp1pXXp-PTE-CFMg5BfIIqTbF-phwwzOHeQ,1063
+python3_capsolver-1.2.0.dist-info/METADATA,sha256=7OfV6UwZU3MV3FQBKryNWmu5TAUqpPvg3Pli9_1piZM,7573
+python3_capsolver-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+python3_capsolver-1.2.0.dist-info/top_level.txt,sha256=yws7CqjoBfrn2ebCkAQmEaVlZ-zhbtflqpCDwAEX4kI,18
+python3_capsolver-1.2.0.dist-info/RECORD,,