Add Async Support (#124)

* Refactor: Move exceptions to a separate module

* Refactor: Move exceptions to a separate module

* Refactor: Move exceptions to a separate module

* Add async support

* Fix: Set follow_redirects=True for all AsyncClient instances

* Fix: Resolve example image paths in tests

Author: techinz

README.md

@@ -76,6 +76,18 @@ from twocaptcha import TwoCaptcha
 
 solver = TwoCaptcha('YOUR_API_KEY')
 ```
+
+<details>
+<summary>Async</summary>
+
+```python 
+from twocaptcha import AsyncTwoCaptcha
+
+solver = AsyncTwoCaptcha('YOUR_API_KEY')
+```
+
+</details>
+
 Also, there are a few options that can be configured:
 
 ```python 
@@ -517,7 +529,55 @@ proxy={
 ```
 
 ## Async calls
-You can also make async calls with [asyncio], for example:
+
+To use the async version, just replace `TwoCaptcha` with `AsyncTwoCaptcha`:
+
+```python
+import asyncio
+from twocaptcha import AsyncTwoCaptcha
+
+async def solve_captcha():
+    solver = AsyncTwoCaptcha('YOUR_API_KEY')
+    
+    try:
+        recaptcha_result = await solver.recaptcha(...)
+        return recaptcha_result
+    except Exception as e:
+        print(e)
+        return None
+
+if __name__ == '__main__':
+    result = asyncio.run(solve_captcha())
+```
+
+The `AsyncTwoCaptcha` class supports all the same methods and parameters as the synchronous `TwoCaptcha` class but operates asynchronously. Configuration is identical.
+
+### Solving Multiple Captchas in Parallel
+
+One of the main advantages of using async support is the ability to solve multiple captchas concurrently:
+
+```python
+async def solve_multiple_captchas():
+    solver = AsyncTwoCaptcha('YOUR_API_KEY')
+    
+    # Start all tasks simultaneously
+    task1 = asyncio.create_task(solver.text('What color is the sky on a clear day?'))
+    task2 = asyncio.create_task(solver.text('What is 2+2?'))
+    task3 = asyncio.create_task(solver.text('Name of the planet we live on?'))
+    
+    # Wait for all tasks to complete
+    results = await asyncio.gather(task1, task2, task3, return_exceptions=True)
+    return results
+
+# This completes much faster than solving captchas sequentially
+results = asyncio.run(solve_multiple_captchas())
+```
+
+Examples of solving all supported captcha types asynchronously are located in the [examples/async directory] directory.
+
+### Legacy Async Method
+
+For backward compatibility, you can also use the traditional executor-based approach with the synchronous client:
 
 ```python
 import asyncio
@@ -535,6 +595,7 @@ async def captchaSolver(image):
 
 captcha_result = asyncio.run(captchaSolver(image))
 ```
+
 ## Examples
 Examples of solving all supported captcha types are located in the [examples] directory.
 
@@ -574,6 +635,8 @@ The graphics and trademarks included in this repository are not covered by the M
 [post options]: https://2captcha.com/2captcha-api#normal_post
 [list of supported languages]: https://2captcha.com/2captcha-api#language
 [examples directory]: /examples
+[examples/sync directory]: /examples/sync
+[examples/async directory]: /examples/async
 [asyncio]: https://docs.python.org/3/library/asyncio.html
 [Buy residential proxies]: https://2captcha.com/proxy/residential-proxies
 [Quick start]: https://2captcha.com/proxy?openAddTrafficModal=true

examples/async/async_amazon_waf.py

@@ -0,0 +1,40 @@
+import asyncio
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))))
+
+from twocaptcha import AsyncTwoCaptcha
+
+# in this example we store the API key inside environment variables that can be set like:
+# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS
+# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows
+# you can just set the API key directly to it's value like:
+# api_key="1abc234de56fab7c89012d34e56fa7b8"
+
+api_key = os.getenv('APIKEY_2CAPTCHA', 'YOUR_API_KEY')
+
+solver = AsyncTwoCaptcha(api_key)
+
+"""
+Important: the values of the 'iv' and 'context' parameters are dynamic, for every request to our API you need to get new values. 
+The values 'iv' and 'context' need to be looked for in the page code.
+"""
+
+
+async def solve_captcha():
+    try:
+        return await solver.amazon_waf(
+            sitekey='AQIDAHjcYu/GjX+QlghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AFsClhVgr5q0UFRdXhhHEwiAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMLMbH8d6uQSrYTraoAgEQgDvtSNxdEyG7Zu393cHyPdWNCZgeIB52+W7fCTI8U5z15z1NdPUdnB1ZHoK7ewpwoSMm5mzkJJld0cnvGw==',
+            iv='CgAAYDJb9CAAACAq',
+            context='wCho9T9OcETTT8fu1k6+rszr5aGt4eLd+K3mHpV8VbSkjAWJGJx/iQ16RKDCTQBtU5OSeE+SQqoS5iTzhgGtvwgmBbr7X/I+aXaNfb2JRZ8eJ7CnQpM9QRwnv7vGgrGRBGhkh/jaVYmXdy0j0x21s3dCBlA4VN3naDHIweZqkyhXqJBNI1Ep8OMSnhXtPebboB117aBW4IU4XEOii8EE1G4Z7ndWhrNVVXYYwVoxfnSqfYX//CJir6dZfLMbCt5t7NnO8yjsx/YHGVXFVBt2Zrj0ZTxowoYbHU/BKyFaXgUj+ZQ=',
+            url='https://efw47fpad9.execute-api.us-east-1.amazonaws.com/latest',
+        )
+    except Exception as e:
+        print(e)
+        return e
+
+
+if __name__ == '__main__':
+    result = asyncio.run(solve_captcha())
+    sys.exit('result: ' + str(result))

examples/async/async_amazon_waf_options.py

@@ -0,0 +1,60 @@
+import asyncio
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))))
+
+from twocaptcha import AsyncTwoCaptcha
+
+# in this example we store the API key inside environment variables that can be set like:
+# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS
+# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows
+# you can just set the API key directly to it's value like:
+# api_key="1abc234de56fab7c89012d34e56fa7b8"
+
+api_key = os.getenv('APIKEY_2CAPTCHA', 'YOUR_API_KEY')
+
+config = {
+    'server': '2captcha.com',  # can be also set to 'rucaptcha.com'
+    'apiKey': api_key,
+    'softId': 123,
+    # 'callback':         'https://your.site/result-receiver', # if set, sovler with just return captchaId, not polling API for the answer
+    'defaultTimeout': 120,
+    'recaptchaTimeout': 600,
+    'pollingInterval': 10,
+}
+
+solver = AsyncTwoCaptcha(**config)
+
+"""
+Important: the values of the 'iv' and 'context' parameters are dynamic, for every request to our API you need to get new values. 
+The values 'iv' and 'context' need to be looked for in the page code.
+"""
+
+
+async def solve_amazon_waf():
+    try:
+        return await solver.amazon_waf(
+            sitekey='AQIDAHjcYu/GjX+QlghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AGIqvS8v6ScFa8ZpNRrlQgKAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMx9gxoe10Zg35PWhzAgEQgDvUtMMkqkFQByMLK2329D8iX4mjvaTuUhU70LD4vLp54v3+4K1nYY2hB+OM1hMbncnMbP63y4UOrY77jg==',
+            iv='CgAGVTNd9JAAAAnB',
+            context='Lte3LdSjiAN6nNcV0omaNt/ydFmd/eTwRCxYEeuW97LZe3IbAXWi4Er9CWQ3HbDgJ0KSpDgwyoskjKCK4VRQzYufPCdrfCYCveZCt9pMNoAluEtj0oix2GXOPVkw2d4bYOg3MtY5ZUHLR3L467NEInnRE99w5NOgokH5Ie7eOi5sYAqYtZrHABGEgrdAOVvU7bcwvrCERi9wB/WS75geb3oFy6z7Apue9GFa86Ld20jjgy4LWfaen+2fpfKHmCHTKVWfto17Bg+l5i0sr+uFRzpk1We64Fhh1Wl1NHF6M6dpS5s=',
+            url='https://efw47fpad9.execute-api.us-east-1.amazonaws.com/latest',
+            challenge_script="https://41bcdd4fb3cb.610cd090.us-east-1.token.awswaf.com/41bcdd4fb3cb/0d21de737ccb/cd77baa6c832/challenge.js",
+            captcha_script="https://41bcdd4fb3cb.610cd090.us-east-1.captcha.awswaf.com/41bcdd4fb3cb/0d21de737ccb/cd77baa6c832/captcha.js",
+            callback="https://mysite.com/2captcha.txt"
+            # proxy={
+            #     'type': 'HTTPS',
+            #     'uri': 'login:password@IP_address:PORT'
+            # }
+            )
+    except Exception as e:
+        print(e)
+        raise e
+
+
+if __name__ == '__main__':
+    try:
+        result = asyncio.run(solve_amazon_waf())
+        sys.exit('result: ' + str(result))
+    except Exception as e:
+        sys.exit(str(e))

examples/async/async_atb_captcha.py

@@ -0,0 +1,34 @@
+import asyncio
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))))
+
+from twocaptcha import AsyncTwoCaptcha
+
+# in this example we store the API key inside environment variables that can be set like:
+# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS
+# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows
+# you can just set the API key directly to it's value like:
+# api_key="1abc234de56fab7c89012d34e56fa7b8"
+
+api_key = os.getenv('APIKEY_2CAPTCHA', 'YOUR_API_KEY')
+
+solver = AsyncTwoCaptcha(api_key)
+
+
+async def solve_captcha():
+    try:
+        return await solver.atb_captcha(
+            app_id='af25e409b33d722a95e56a230ff8771c',
+            api_server='https://cap.aisecurius.com',
+            url='http://mysite.com/',
+        )
+    except Exception as e:
+        print(e)
+        return e
+
+
+if __name__ == '__main__':
+    result = asyncio.run(solve_captcha())
+    sys.exit('result: ' + str(result))

examples/async/async_atb_captcha_options.py

@@ -0,0 +1,48 @@
+import asyncio
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))))
+
+from twocaptcha import AsyncTwoCaptcha
+
+# in this example we store the API key inside environment variables that can be set like:
+# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS
+# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows
+# you can just set the API key directly to it's value like:
+# api_key="1abc234de56fab7c89012d34e56fa7b8"
+
+api_key = os.getenv('APIKEY_2CAPTCHA', 'YOUR_API_KEY')
+
+config = {
+    'server': '2captcha.com',  # can be also set to 'rucaptcha.com'
+    'apiKey': api_key,
+    'softId': 123,
+    # 'callback':         'https://your.site/result-receiver', # if set, sovler with just return captchaId, not polling API for the answer
+    'defaultTimeout': 120,
+    'recaptchaTimeout': 600,
+    'pollingInterval': 10,
+}
+
+solver = AsyncTwoCaptcha(**config)
+
+
+async def solve_captcha():
+    try:
+        return await solver.atb_captcha(
+            app_id='af25e409b33d722a95e56a230ff8771c',
+            api_server='https://cap.aisecurius.com',
+            url='http://mysite.com/',
+            # proxy={
+            #     'type': 'HTTPS',
+            #     'uri': 'login:password@IP_address:PORT'
+            # }
+        )
+    except Exception as e:
+        print(e)
+        return e
+
+
+if __name__ == '__main__':
+    result = asyncio.run(solve_captcha())
+    sys.exit('result: ' + str(result))

examples/async/async_audio.py

@@ -0,0 +1,30 @@
+import asyncio
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))))
+
+from twocaptcha import AsyncTwoCaptcha
+
+# in this example we store the API key inside environment variables that can be set like:
+# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS
+# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows
+# you can just set the API key directly to it's value like:
+# api_key="1abc234de56fab7c89012d34e56fa7b8"
+
+api_key = os.getenv('APIKEY', 'YOUR_API_KEY')
+
+solver = AsyncTwoCaptcha(api_key)
+
+
+async def solve_captcha():
+    try:
+        return await solver.audio('../audio/example.mp3', lang='en')
+    except Exception as e:
+        print(e)
+        return e
+
+
+if __name__ == '__main__':
+    result = asyncio.run(solve_captcha())
+    sys.exit('result: ' + str(result))

examples/async/async_canvas.py

@@ -0,0 +1,29 @@
+import asyncio
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))))
+from twocaptcha import AsyncTwoCaptcha
+
+# in this example we store the API key inside environment variables that can be set like:
+# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS
+# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows
+# you can just set the API key directly to it's value like:
+# api_key="1abc234de56fab7c89012d34e56fa7b8"
+
+api_key = os.getenv('APIKEY_2CAPTCHA', 'YOUR_API_KEY')
+
+solver = AsyncTwoCaptcha(api_key)
+
+
+async def solve_captcha():
+    try:
+        return await solver.canvas('../images/canvas.jpg', hintText='Draw around apple')
+    except Exception as e:
+        print(e)
+        return e
+
+
+if __name__ == '__main__':
+    result = asyncio.run(solve_captcha())
+    sys.exit('result: ' + str(result))

examples/async/async_canvas_base64.py

@@ -0,0 +1,35 @@
+import asyncio
+import os
+import sys
+from base64 import b64encode
+
+import aiofiles
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))))
+from twocaptcha import AsyncTwoCaptcha
+
+# in this example we store the API key inside environment variables that can be set like:
+# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS
+# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows
+# you can just set the API key directly to it's value like:
+# api_key="1abc234de56fab7c89012d34e56fa7b8"
+
+api_key = os.getenv('APIKEY_2CAPTCHA', 'YOUR_API_KEY')
+
+solver = AsyncTwoCaptcha(api_key)
+
+
+async def solve_captcha():
+    async with aiofiles.open('../images/canvas.jpg', 'rb') as f:
+        b64 = b64encode(await f.read()).decode('utf-8')
+
+    try:
+        return await solver.canvas(b64, hintText='Draw around apple')
+    except Exception as e:
+        print(e)
+        return e
+
+
+if __name__ == '__main__':
+    result = asyncio.run(solve_captcha())
+    sys.exit('result: ' + str(result))