diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-2captcha-python.spec | 1051 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 1053 insertions, 0 deletions
@@ -0,0 +1 @@ +/2captcha-python-1.2.0.tar.gz diff --git a/python-2captcha-python.spec b/python-2captcha-python.spec new file mode 100644 index 0000000..0a35f1f --- /dev/null +++ b/python-2captcha-python.spec @@ -0,0 +1,1051 @@ +%global _empty_manifest_terminate_build 0 +Name: python-2captcha-python +Version: 1.2.0 +Release: 1 +Summary: Python module for easy integration with 2Captcha API +License: MIT License +URL: https://github.com/2captcha/2captcha-python/ +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/bc/72/6905bab749dcce62c1818f130db71dee0cb469baff80db1c362a975ff803/2captcha-python-1.2.0.tar.gz +BuildArch: noarch + +Requires: python3-requests + +%description +# Python Module for 2Captcha API +The easiest way to quickly integrate [2Captcha] captcha solving service into your code to automate solving of any types of captcha. + +- [Python Module for 2Captcha API](#python-module-for-2captcha-api) + - [Installation](#installation) + - [Configuration](#configuration) + - [TwoCaptcha instance options](#twocaptcha-instance-options) + - [Solve captcha](#solve-captcha) + - [Captcha options](#captcha-options) + - [Normal Captcha](#normal-captcha) + - [Text Captcha](#text-captcha) + - [ReCaptcha v2](#recaptcha-v2) + - [ReCaptcha v3](#recaptcha-v3) + - [FunCaptcha](#funcaptcha) + - [GeeTest](#geetest) + - [hCaptcha](#hcaptcha) + - [GeeTest v4](#geetest-v4) + - [Lemin Cropped Captcha](#lemin-cropped-captcha) + - [Cloudflare Turnstile](#cloudflare-turnstile) + - [Amazon WAF](#amazon-waf) + - [KeyCaptcha](#keycaptcha) + - [Capy](#capy) + - [Grid](#grid) + - [Canvas](#canvas) + - [ClickCaptcha](#clickcaptcha) + - [Rotate](#rotate) + - [Other methods](#other-methods) + - [send / getResult](#send--getresult) + - [balance](#balance) + - [report](#report) + - [Error handling](#error-handling) + - [Proxies](#proxies) + - [Async calls](#async-calls) + +## Installation + +This package can be installed with Pip: + +```pip3 install 2captcha-python``` + + +## Configuration + +TwoCaptcha instance can be created like this: + +```python +from twocaptcha import TwoCaptcha + +solver = TwoCaptcha('YOUR_API_KEY') +``` +Also there are few options that can be configured: + +```python +config = { + 'server': '2captcha.com', + 'apiKey': 'YOUR_API_KEY', + 'softId': 123, + 'callback': 'https://your.site/result-receiver', + 'defaultTimeout': 120, + 'recaptchaTimeout': 600, + 'pollingInterval': 10, + } +solver = TwoCaptcha(**config) +``` + +### TwoCaptcha instance options + +| Option | Default value | Description | +| ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| server | `2captcha.com` | API server. You can set it to `rucaptcha.com` if your account is registered there | +| softId | - | your software ID obtained after publishing in [2captcha sofware catalog] | +| callback | - | URL of your web-sever that receives the captcha recognition result. The URl should be first registered in [pingback settings] of your account | +| defaultTimeout | 120 | Polling timeout in seconds for all captcha types except ReCaptcha. Defines how long the module tries to get the answer from `res.php` API endpoint | +| recaptchaTimeout | 600 | Polling timeout for ReCaptcha in seconds. Defines how long the module tries to get the answer from `res.php` API endpoint | +| pollingInterval | 10 | Interval in seconds between requests to `res.php` API endpoint, setting values less than 5 seconds is not recommended | + +> **IMPORTANT:** once `callback` is defined for `TwoCaptcha` instance, all methods return only the captcha ID and DO NOT poll the API to get the result. The result will be sent to the callback URL. +To get the answer manually use [getResult method](#send--getresult) + +## Solve captcha +When you submit any image-based captcha use can provide additional options to help 2captcha workers to solve it properly. + +### Captcha options +| Option | Default Value | Description | +| ------------- | ------------- | -------------------------------------------------------------------------------------------------- | +| numeric | 0 | Defines if captcha contains numeric or other symbols [see more info in the API docs][post options] | +| minLength | 0 | minimal answer lenght | +| maxLength | 0 | maximum answer length | +| phrase | 0 | defines if the answer contains multiple words or not | +| caseSensitive | 0 | defines if the answer is case sensitive | +| calc | 0 | defines captcha requires calculation | +| lang | - | defines the captcha language, see the [list of supported languages] | +| hintImg | - | an image with hint shown to workers with the captcha | +| hintText | - | hint or task text shown to workers with the captcha | + +Below you can find basic examples for every captcha type. Check out [examples directory] to find more examples with all available options. + +### Normal Captcha +To bypass a normal captcha (distorted text on image) use the following method. This method also can be used to recognize any text on the image. +```python +result = solver.normal('path/to/captcha.jpg', param1=..., ...) +# OR +result = solver.normal('https://site-with-captcha.com/path/to/captcha.jpg', param1=..., ...) +``` + +### Text Captcha +This method can be used to bypass a captcha that requires to answer a question provided in clear text. +```python +result = solver.text('If tomorrow is Saturday, what day is today?', param1=..., ...) +``` + +### ReCaptcha v2 +Use this method to solve ReCaptcha V2 and obtain a token to bypass the protection. +```python +result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-', + url='https://mysite.com/page/with/recaptcha', + param1=..., ...) +``` + +### ReCaptcha v3 +This method provides ReCaptcha V3 solver and returns a token. +```python +result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-', + url='https://mysite.com/page/with/recaptcha', + version='v3', + param1=..., ...) +``` + +### FunCaptcha +FunCaptcha (Arkoselabs) solving method. Returns a token. +```python +result = solver.funcaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-', + url='https://mysite.com/page/with/funcaptcha', + param1=..., ...) + +``` + + +### GeeTest +Method to solve GeeTest puzzle captcha. Returns a set of tokens as JSON. +```python +result = solver.geetest(gt='f1ab2cdefa3456789012345b6c78d90e', + challenge='12345678abc90123d45678ef90123a456b', + url='https://www.site.com/page/', + param1=..., ...) + +``` + + +### hCaptcha +Use this method to solve hCaptcha challenge. Returns a token to bypass captcha. +```python +result = solver.hcaptcha(sitekey='10000000-ffff-ffff-ffff-000000000001', + url='https://www.site.com/page/', + param1=..., ...) + +``` + +### GeeTest v4 +Use this method to solve GeeTest v4. Returns the response in JSON. +```python +result = solver.geetest_v4(captcha_id='e392e1d7fd421dc63325744d5a2b9c73', + url='https://www.site.com/page/', + param1=..., ...) + +``` + + +### Lemin Cropped Captcha +Use this method to solve hCaptcha challenge. Returns JSON with answer containing the following values: answer, challenge_id. +```python +result = solver.lemin(captcha_id='CROPPED_1abcd2f_a1234b567c890d12ef3a456bc78d901d', + div_id='lemin-cropped-captcha', + url='https://www.site.com/page/', + param1=..., ...) + +``` + + +### Cloudflare Turnstile +Use this method to solve Cloudflare Turnstile. Returns JSON with the token. +```python +result = solver.turnstile(sitekey='0x1AAAAAAAAkg0s2VIOD34y5', + url='http://mysite.com/', + param1=..., ...) + +``` + +### Amazon WAF +Use this method to solve Amazon WAF Captcha also known as AWS WAF Captcha is a part of Intelligent threat mitigation for Amazon AWS. Returns JSON with the token. +```python +result = solver.amazon_waf(sitekey='0x1AAAAAAAAkg0s2VIOD34y5', + iv='CgAHbCe2GgAAAAAj', + context='9BUgmlm48F92WUoqv97a49ZuEJJ50TCk9MVr3C7WMtQ0X6flVbufM4n8mjFLmbLVAPgaQ1Jydeaja94iAS49ljb+sUNLoukWedAQZKrlY4RdbOOzvcFqmD/ZepQFS9N5w15Exr4VwnVq+HIxTsDJwRviElWCdzKDebN/mk8/eX2n7qJi5G3Riq0tdQw9+C4diFZU5E97RSeahejOAAJTDqduqW6uLw9NsjJBkDRBlRjxjn5CaMMo5pYOxYbGrM8Un1JH5DMOLeXbq1xWbC17YSEoM1cRFfTgOoc+VpCe36Ai9Kc=' + url='https://non-existent-example.execute-api.us-east-1.amazonaws.com/latest' + param1=..., ...) + +``` + + +### KeyCaptcha +Token-based method to solve KeyCaptcha. +```python +result = solver.keycaptcha(s_s_c_user_id=10, + s_s_c_session_id='493e52c37c10c2bcdf4a00cbc9ccd1e8', + s_s_c_web_server_sign='9006dc725760858e4c0715b835472f22-pz-', + s_s_c_web_server_sign2='2ca3abe86d90c6142d5571db98af6714', + url='https://www.keycaptcha.ru/demo-magnetic/', + param1=..., ...) + +``` + +### Capy +Token-based method to bypass Capy puzzle captcha. +```python +result = solver.capy(sitekey='PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v', + url='http://mysite.com/', + api_server='https://jp.api.capy.me/', + param1=..., ...) +``` +### Grid +Grid method is originally called Old ReCaptcha V2 method. The method can be used to bypass any type of captcha where you can apply a grid on image and need to click specific grid boxes. Returns numbers of boxes. +```python +result = solver.grid('path/to/captcha.jpg', param1=..., ...) +``` +### Canvas +Canvas method can be used when you need to draw a line around an object on image. Returns a set of points' coordinates to draw a polygon. +```python +result = solver.canvas('path/to/captcha.jpg', param1=..., ...) +``` +### ClickCaptcha +ClickCaptcha method returns coordinates of points on captcha image. Can be used if you need to click on particular points on the image. +```python +result = solver.coordinates('path/to/captcha.jpg', param1=..., ...) +``` + +### Rotate +This method can be used to solve a captcha that asks to rotate an object. Mostly used to bypass FunCaptcha. Returns the rotation angle. +```python +result = solver.rotate('path/to/captcha.jpg', param1=..., ...) +``` + +## Other methods + +### send / getResult +These methods can be used for manual captcha submission and answer polling. +```python +import time +. . . . . + + +id = solver.send(file='path/to/captcha.jpg') +time.sleep(20) + +code = solver.get_result(id) +``` + +### balance +Use this method to get your account's balance +```python +balance = solver.balance() +``` + +### report +Use this method to report good or bad captcha answer. +```python +solver.report(id, True) # captcha solved correctly +solver.report(id, False) # captcha solved incorrectly +``` + +### Error handling +In case of an error, the captcha solver throws an exception. It's important to properly handle these cases. We recommend using `try except` to handle exceptions. +```python +try: + result = solver.text('If tomorrow is Saturday, what day is today?') +except ValidationException as e: + # invalid parameters passed + print(e) +except NetworkException as e: + # network error occurred + print(e) +except ApiException as e: + # api respond with error + print(e) +except TimeoutException as e: + # captcha is not solved so far + print(e) +``` + + +### Proxies + +You can pass your proxy as an additional argument for methods: recaptcha, funcaptcha and geetest. The proxy will be forwarded to the API to solve the captcha. + +```python +proxy={ + 'type': 'HTTPS', + 'uri': 'login:password@IP_address:PORT' +} +``` + +### Async calls +You can also make async calls with [asyncio], for example: + +```python +import asyncio +import concurrent.futures +from twocaptcha import TwoCaptcha + +captcha_result = await captchaSolver(image) + +async def captchaSolver(image): + loop = asyncio.get_running_loop() + with concurrent.future.ThreadPoolExecutor() as pool: + result = await loop.run_in_executor(pool, lambda: TwoCaptcha(API_KEY).normal(image)) + return result +``` + + +[2Captcha]: https://2captcha.com/ +[2captcha sofware catalog]: https://2captcha.com/software +[pingback settings]: https://2captcha.com/setting/pingback +[post options]: https://2captcha.com/2captcha-api#normal_post +[list of supported languages]: https://2captcha.com/2captcha-api#language +[examples directory]: /examples +[asyncio]: https://docs.python.org/3/library/asyncio.html + + +%package -n python3-2captcha-python +Summary: Python module for easy integration with 2Captcha API +Provides: python-2captcha-python +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-2captcha-python +# Python Module for 2Captcha API +The easiest way to quickly integrate [2Captcha] captcha solving service into your code to automate solving of any types of captcha. + +- [Python Module for 2Captcha API](#python-module-for-2captcha-api) + - [Installation](#installation) + - [Configuration](#configuration) + - [TwoCaptcha instance options](#twocaptcha-instance-options) + - [Solve captcha](#solve-captcha) + - [Captcha options](#captcha-options) + - [Normal Captcha](#normal-captcha) + - [Text Captcha](#text-captcha) + - [ReCaptcha v2](#recaptcha-v2) + - [ReCaptcha v3](#recaptcha-v3) + - [FunCaptcha](#funcaptcha) + - [GeeTest](#geetest) + - [hCaptcha](#hcaptcha) + - [GeeTest v4](#geetest-v4) + - [Lemin Cropped Captcha](#lemin-cropped-captcha) + - [Cloudflare Turnstile](#cloudflare-turnstile) + - [Amazon WAF](#amazon-waf) + - [KeyCaptcha](#keycaptcha) + - [Capy](#capy) + - [Grid](#grid) + - [Canvas](#canvas) + - [ClickCaptcha](#clickcaptcha) + - [Rotate](#rotate) + - [Other methods](#other-methods) + - [send / getResult](#send--getresult) + - [balance](#balance) + - [report](#report) + - [Error handling](#error-handling) + - [Proxies](#proxies) + - [Async calls](#async-calls) + +## Installation + +This package can be installed with Pip: + +```pip3 install 2captcha-python``` + + +## Configuration + +TwoCaptcha instance can be created like this: + +```python +from twocaptcha import TwoCaptcha + +solver = TwoCaptcha('YOUR_API_KEY') +``` +Also there are few options that can be configured: + +```python +config = { + 'server': '2captcha.com', + 'apiKey': 'YOUR_API_KEY', + 'softId': 123, + 'callback': 'https://your.site/result-receiver', + 'defaultTimeout': 120, + 'recaptchaTimeout': 600, + 'pollingInterval': 10, + } +solver = TwoCaptcha(**config) +``` + +### TwoCaptcha instance options + +| Option | Default value | Description | +| ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| server | `2captcha.com` | API server. You can set it to `rucaptcha.com` if your account is registered there | +| softId | - | your software ID obtained after publishing in [2captcha sofware catalog] | +| callback | - | URL of your web-sever that receives the captcha recognition result. The URl should be first registered in [pingback settings] of your account | +| defaultTimeout | 120 | Polling timeout in seconds for all captcha types except ReCaptcha. Defines how long the module tries to get the answer from `res.php` API endpoint | +| recaptchaTimeout | 600 | Polling timeout for ReCaptcha in seconds. Defines how long the module tries to get the answer from `res.php` API endpoint | +| pollingInterval | 10 | Interval in seconds between requests to `res.php` API endpoint, setting values less than 5 seconds is not recommended | + +> **IMPORTANT:** once `callback` is defined for `TwoCaptcha` instance, all methods return only the captcha ID and DO NOT poll the API to get the result. The result will be sent to the callback URL. +To get the answer manually use [getResult method](#send--getresult) + +## Solve captcha +When you submit any image-based captcha use can provide additional options to help 2captcha workers to solve it properly. + +### Captcha options +| Option | Default Value | Description | +| ------------- | ------------- | -------------------------------------------------------------------------------------------------- | +| numeric | 0 | Defines if captcha contains numeric or other symbols [see more info in the API docs][post options] | +| minLength | 0 | minimal answer lenght | +| maxLength | 0 | maximum answer length | +| phrase | 0 | defines if the answer contains multiple words or not | +| caseSensitive | 0 | defines if the answer is case sensitive | +| calc | 0 | defines captcha requires calculation | +| lang | - | defines the captcha language, see the [list of supported languages] | +| hintImg | - | an image with hint shown to workers with the captcha | +| hintText | - | hint or task text shown to workers with the captcha | + +Below you can find basic examples for every captcha type. Check out [examples directory] to find more examples with all available options. + +### Normal Captcha +To bypass a normal captcha (distorted text on image) use the following method. This method also can be used to recognize any text on the image. +```python +result = solver.normal('path/to/captcha.jpg', param1=..., ...) +# OR +result = solver.normal('https://site-with-captcha.com/path/to/captcha.jpg', param1=..., ...) +``` + +### Text Captcha +This method can be used to bypass a captcha that requires to answer a question provided in clear text. +```python +result = solver.text('If tomorrow is Saturday, what day is today?', param1=..., ...) +``` + +### ReCaptcha v2 +Use this method to solve ReCaptcha V2 and obtain a token to bypass the protection. +```python +result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-', + url='https://mysite.com/page/with/recaptcha', + param1=..., ...) +``` + +### ReCaptcha v3 +This method provides ReCaptcha V3 solver and returns a token. +```python +result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-', + url='https://mysite.com/page/with/recaptcha', + version='v3', + param1=..., ...) +``` + +### FunCaptcha +FunCaptcha (Arkoselabs) solving method. Returns a token. +```python +result = solver.funcaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-', + url='https://mysite.com/page/with/funcaptcha', + param1=..., ...) + +``` + + +### GeeTest +Method to solve GeeTest puzzle captcha. Returns a set of tokens as JSON. +```python +result = solver.geetest(gt='f1ab2cdefa3456789012345b6c78d90e', + challenge='12345678abc90123d45678ef90123a456b', + url='https://www.site.com/page/', + param1=..., ...) + +``` + + +### hCaptcha +Use this method to solve hCaptcha challenge. Returns a token to bypass captcha. +```python +result = solver.hcaptcha(sitekey='10000000-ffff-ffff-ffff-000000000001', + url='https://www.site.com/page/', + param1=..., ...) + +``` + +### GeeTest v4 +Use this method to solve GeeTest v4. Returns the response in JSON. +```python +result = solver.geetest_v4(captcha_id='e392e1d7fd421dc63325744d5a2b9c73', + url='https://www.site.com/page/', + param1=..., ...) + +``` + + +### Lemin Cropped Captcha +Use this method to solve hCaptcha challenge. Returns JSON with answer containing the following values: answer, challenge_id. +```python +result = solver.lemin(captcha_id='CROPPED_1abcd2f_a1234b567c890d12ef3a456bc78d901d', + div_id='lemin-cropped-captcha', + url='https://www.site.com/page/', + param1=..., ...) + +``` + + +### Cloudflare Turnstile +Use this method to solve Cloudflare Turnstile. Returns JSON with the token. +```python +result = solver.turnstile(sitekey='0x1AAAAAAAAkg0s2VIOD34y5', + url='http://mysite.com/', + param1=..., ...) + +``` + +### Amazon WAF +Use this method to solve Amazon WAF Captcha also known as AWS WAF Captcha is a part of Intelligent threat mitigation for Amazon AWS. Returns JSON with the token. +```python +result = solver.amazon_waf(sitekey='0x1AAAAAAAAkg0s2VIOD34y5', + iv='CgAHbCe2GgAAAAAj', + context='9BUgmlm48F92WUoqv97a49ZuEJJ50TCk9MVr3C7WMtQ0X6flVbufM4n8mjFLmbLVAPgaQ1Jydeaja94iAS49ljb+sUNLoukWedAQZKrlY4RdbOOzvcFqmD/ZepQFS9N5w15Exr4VwnVq+HIxTsDJwRviElWCdzKDebN/mk8/eX2n7qJi5G3Riq0tdQw9+C4diFZU5E97RSeahejOAAJTDqduqW6uLw9NsjJBkDRBlRjxjn5CaMMo5pYOxYbGrM8Un1JH5DMOLeXbq1xWbC17YSEoM1cRFfTgOoc+VpCe36Ai9Kc=' + url='https://non-existent-example.execute-api.us-east-1.amazonaws.com/latest' + param1=..., ...) + +``` + + +### KeyCaptcha +Token-based method to solve KeyCaptcha. +```python +result = solver.keycaptcha(s_s_c_user_id=10, + s_s_c_session_id='493e52c37c10c2bcdf4a00cbc9ccd1e8', + s_s_c_web_server_sign='9006dc725760858e4c0715b835472f22-pz-', + s_s_c_web_server_sign2='2ca3abe86d90c6142d5571db98af6714', + url='https://www.keycaptcha.ru/demo-magnetic/', + param1=..., ...) + +``` + +### Capy +Token-based method to bypass Capy puzzle captcha. +```python +result = solver.capy(sitekey='PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v', + url='http://mysite.com/', + api_server='https://jp.api.capy.me/', + param1=..., ...) +``` +### Grid +Grid method is originally called Old ReCaptcha V2 method. The method can be used to bypass any type of captcha where you can apply a grid on image and need to click specific grid boxes. Returns numbers of boxes. +```python +result = solver.grid('path/to/captcha.jpg', param1=..., ...) +``` +### Canvas +Canvas method can be used when you need to draw a line around an object on image. Returns a set of points' coordinates to draw a polygon. +```python +result = solver.canvas('path/to/captcha.jpg', param1=..., ...) +``` +### ClickCaptcha +ClickCaptcha method returns coordinates of points on captcha image. Can be used if you need to click on particular points on the image. +```python +result = solver.coordinates('path/to/captcha.jpg', param1=..., ...) +``` + +### Rotate +This method can be used to solve a captcha that asks to rotate an object. Mostly used to bypass FunCaptcha. Returns the rotation angle. +```python +result = solver.rotate('path/to/captcha.jpg', param1=..., ...) +``` + +## Other methods + +### send / getResult +These methods can be used for manual captcha submission and answer polling. +```python +import time +. . . . . + + +id = solver.send(file='path/to/captcha.jpg') +time.sleep(20) + +code = solver.get_result(id) +``` + +### balance +Use this method to get your account's balance +```python +balance = solver.balance() +``` + +### report +Use this method to report good or bad captcha answer. +```python +solver.report(id, True) # captcha solved correctly +solver.report(id, False) # captcha solved incorrectly +``` + +### Error handling +In case of an error, the captcha solver throws an exception. It's important to properly handle these cases. We recommend using `try except` to handle exceptions. +```python +try: + result = solver.text('If tomorrow is Saturday, what day is today?') +except ValidationException as e: + # invalid parameters passed + print(e) +except NetworkException as e: + # network error occurred + print(e) +except ApiException as e: + # api respond with error + print(e) +except TimeoutException as e: + # captcha is not solved so far + print(e) +``` + + +### Proxies + +You can pass your proxy as an additional argument for methods: recaptcha, funcaptcha and geetest. The proxy will be forwarded to the API to solve the captcha. + +```python +proxy={ + 'type': 'HTTPS', + 'uri': 'login:password@IP_address:PORT' +} +``` + +### Async calls +You can also make async calls with [asyncio], for example: + +```python +import asyncio +import concurrent.futures +from twocaptcha import TwoCaptcha + +captcha_result = await captchaSolver(image) + +async def captchaSolver(image): + loop = asyncio.get_running_loop() + with concurrent.future.ThreadPoolExecutor() as pool: + result = await loop.run_in_executor(pool, lambda: TwoCaptcha(API_KEY).normal(image)) + return result +``` + + +[2Captcha]: https://2captcha.com/ +[2captcha sofware catalog]: https://2captcha.com/software +[pingback settings]: https://2captcha.com/setting/pingback +[post options]: https://2captcha.com/2captcha-api#normal_post +[list of supported languages]: https://2captcha.com/2captcha-api#language +[examples directory]: /examples +[asyncio]: https://docs.python.org/3/library/asyncio.html + + +%package help +Summary: Development documents and examples for 2captcha-python +Provides: python3-2captcha-python-doc +%description help +# Python Module for 2Captcha API +The easiest way to quickly integrate [2Captcha] captcha solving service into your code to automate solving of any types of captcha. + +- [Python Module for 2Captcha API](#python-module-for-2captcha-api) + - [Installation](#installation) + - [Configuration](#configuration) + - [TwoCaptcha instance options](#twocaptcha-instance-options) + - [Solve captcha](#solve-captcha) + - [Captcha options](#captcha-options) + - [Normal Captcha](#normal-captcha) + - [Text Captcha](#text-captcha) + - [ReCaptcha v2](#recaptcha-v2) + - [ReCaptcha v3](#recaptcha-v3) + - [FunCaptcha](#funcaptcha) + - [GeeTest](#geetest) + - [hCaptcha](#hcaptcha) + - [GeeTest v4](#geetest-v4) + - [Lemin Cropped Captcha](#lemin-cropped-captcha) + - [Cloudflare Turnstile](#cloudflare-turnstile) + - [Amazon WAF](#amazon-waf) + - [KeyCaptcha](#keycaptcha) + - [Capy](#capy) + - [Grid](#grid) + - [Canvas](#canvas) + - [ClickCaptcha](#clickcaptcha) + - [Rotate](#rotate) + - [Other methods](#other-methods) + - [send / getResult](#send--getresult) + - [balance](#balance) + - [report](#report) + - [Error handling](#error-handling) + - [Proxies](#proxies) + - [Async calls](#async-calls) + +## Installation + +This package can be installed with Pip: + +```pip3 install 2captcha-python``` + + +## Configuration + +TwoCaptcha instance can be created like this: + +```python +from twocaptcha import TwoCaptcha + +solver = TwoCaptcha('YOUR_API_KEY') +``` +Also there are few options that can be configured: + +```python +config = { + 'server': '2captcha.com', + 'apiKey': 'YOUR_API_KEY', + 'softId': 123, + 'callback': 'https://your.site/result-receiver', + 'defaultTimeout': 120, + 'recaptchaTimeout': 600, + 'pollingInterval': 10, + } +solver = TwoCaptcha(**config) +``` + +### TwoCaptcha instance options + +| Option | Default value | Description | +| ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| server | `2captcha.com` | API server. You can set it to `rucaptcha.com` if your account is registered there | +| softId | - | your software ID obtained after publishing in [2captcha sofware catalog] | +| callback | - | URL of your web-sever that receives the captcha recognition result. The URl should be first registered in [pingback settings] of your account | +| defaultTimeout | 120 | Polling timeout in seconds for all captcha types except ReCaptcha. Defines how long the module tries to get the answer from `res.php` API endpoint | +| recaptchaTimeout | 600 | Polling timeout for ReCaptcha in seconds. Defines how long the module tries to get the answer from `res.php` API endpoint | +| pollingInterval | 10 | Interval in seconds between requests to `res.php` API endpoint, setting values less than 5 seconds is not recommended | + +> **IMPORTANT:** once `callback` is defined for `TwoCaptcha` instance, all methods return only the captcha ID and DO NOT poll the API to get the result. The result will be sent to the callback URL. +To get the answer manually use [getResult method](#send--getresult) + +## Solve captcha +When you submit any image-based captcha use can provide additional options to help 2captcha workers to solve it properly. + +### Captcha options +| Option | Default Value | Description | +| ------------- | ------------- | -------------------------------------------------------------------------------------------------- | +| numeric | 0 | Defines if captcha contains numeric or other symbols [see more info in the API docs][post options] | +| minLength | 0 | minimal answer lenght | +| maxLength | 0 | maximum answer length | +| phrase | 0 | defines if the answer contains multiple words or not | +| caseSensitive | 0 | defines if the answer is case sensitive | +| calc | 0 | defines captcha requires calculation | +| lang | - | defines the captcha language, see the [list of supported languages] | +| hintImg | - | an image with hint shown to workers with the captcha | +| hintText | - | hint or task text shown to workers with the captcha | + +Below you can find basic examples for every captcha type. Check out [examples directory] to find more examples with all available options. + +### Normal Captcha +To bypass a normal captcha (distorted text on image) use the following method. This method also can be used to recognize any text on the image. +```python +result = solver.normal('path/to/captcha.jpg', param1=..., ...) +# OR +result = solver.normal('https://site-with-captcha.com/path/to/captcha.jpg', param1=..., ...) +``` + +### Text Captcha +This method can be used to bypass a captcha that requires to answer a question provided in clear text. +```python +result = solver.text('If tomorrow is Saturday, what day is today?', param1=..., ...) +``` + +### ReCaptcha v2 +Use this method to solve ReCaptcha V2 and obtain a token to bypass the protection. +```python +result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-', + url='https://mysite.com/page/with/recaptcha', + param1=..., ...) +``` + +### ReCaptcha v3 +This method provides ReCaptcha V3 solver and returns a token. +```python +result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-', + url='https://mysite.com/page/with/recaptcha', + version='v3', + param1=..., ...) +``` + +### FunCaptcha +FunCaptcha (Arkoselabs) solving method. Returns a token. +```python +result = solver.funcaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-', + url='https://mysite.com/page/with/funcaptcha', + param1=..., ...) + +``` + + +### GeeTest +Method to solve GeeTest puzzle captcha. Returns a set of tokens as JSON. +```python +result = solver.geetest(gt='f1ab2cdefa3456789012345b6c78d90e', + challenge='12345678abc90123d45678ef90123a456b', + url='https://www.site.com/page/', + param1=..., ...) + +``` + + +### hCaptcha +Use this method to solve hCaptcha challenge. Returns a token to bypass captcha. +```python +result = solver.hcaptcha(sitekey='10000000-ffff-ffff-ffff-000000000001', + url='https://www.site.com/page/', + param1=..., ...) + +``` + +### GeeTest v4 +Use this method to solve GeeTest v4. Returns the response in JSON. +```python +result = solver.geetest_v4(captcha_id='e392e1d7fd421dc63325744d5a2b9c73', + url='https://www.site.com/page/', + param1=..., ...) + +``` + + +### Lemin Cropped Captcha +Use this method to solve hCaptcha challenge. Returns JSON with answer containing the following values: answer, challenge_id. +```python +result = solver.lemin(captcha_id='CROPPED_1abcd2f_a1234b567c890d12ef3a456bc78d901d', + div_id='lemin-cropped-captcha', + url='https://www.site.com/page/', + param1=..., ...) + +``` + + +### Cloudflare Turnstile +Use this method to solve Cloudflare Turnstile. Returns JSON with the token. +```python +result = solver.turnstile(sitekey='0x1AAAAAAAAkg0s2VIOD34y5', + url='http://mysite.com/', + param1=..., ...) + +``` + +### Amazon WAF +Use this method to solve Amazon WAF Captcha also known as AWS WAF Captcha is a part of Intelligent threat mitigation for Amazon AWS. Returns JSON with the token. +```python +result = solver.amazon_waf(sitekey='0x1AAAAAAAAkg0s2VIOD34y5', + iv='CgAHbCe2GgAAAAAj', + context='9BUgmlm48F92WUoqv97a49ZuEJJ50TCk9MVr3C7WMtQ0X6flVbufM4n8mjFLmbLVAPgaQ1Jydeaja94iAS49ljb+sUNLoukWedAQZKrlY4RdbOOzvcFqmD/ZepQFS9N5w15Exr4VwnVq+HIxTsDJwRviElWCdzKDebN/mk8/eX2n7qJi5G3Riq0tdQw9+C4diFZU5E97RSeahejOAAJTDqduqW6uLw9NsjJBkDRBlRjxjn5CaMMo5pYOxYbGrM8Un1JH5DMOLeXbq1xWbC17YSEoM1cRFfTgOoc+VpCe36Ai9Kc=' + url='https://non-existent-example.execute-api.us-east-1.amazonaws.com/latest' + param1=..., ...) + +``` + + +### KeyCaptcha +Token-based method to solve KeyCaptcha. +```python +result = solver.keycaptcha(s_s_c_user_id=10, + s_s_c_session_id='493e52c37c10c2bcdf4a00cbc9ccd1e8', + s_s_c_web_server_sign='9006dc725760858e4c0715b835472f22-pz-', + s_s_c_web_server_sign2='2ca3abe86d90c6142d5571db98af6714', + url='https://www.keycaptcha.ru/demo-magnetic/', + param1=..., ...) + +``` + +### Capy +Token-based method to bypass Capy puzzle captcha. +```python +result = solver.capy(sitekey='PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v', + url='http://mysite.com/', + api_server='https://jp.api.capy.me/', + param1=..., ...) +``` +### Grid +Grid method is originally called Old ReCaptcha V2 method. The method can be used to bypass any type of captcha where you can apply a grid on image and need to click specific grid boxes. Returns numbers of boxes. +```python +result = solver.grid('path/to/captcha.jpg', param1=..., ...) +``` +### Canvas +Canvas method can be used when you need to draw a line around an object on image. Returns a set of points' coordinates to draw a polygon. +```python +result = solver.canvas('path/to/captcha.jpg', param1=..., ...) +``` +### ClickCaptcha +ClickCaptcha method returns coordinates of points on captcha image. Can be used if you need to click on particular points on the image. +```python +result = solver.coordinates('path/to/captcha.jpg', param1=..., ...) +``` + +### Rotate +This method can be used to solve a captcha that asks to rotate an object. Mostly used to bypass FunCaptcha. Returns the rotation angle. +```python +result = solver.rotate('path/to/captcha.jpg', param1=..., ...) +``` + +## Other methods + +### send / getResult +These methods can be used for manual captcha submission and answer polling. +```python +import time +. . . . . + + +id = solver.send(file='path/to/captcha.jpg') +time.sleep(20) + +code = solver.get_result(id) +``` + +### balance +Use this method to get your account's balance +```python +balance = solver.balance() +``` + +### report +Use this method to report good or bad captcha answer. +```python +solver.report(id, True) # captcha solved correctly +solver.report(id, False) # captcha solved incorrectly +``` + +### Error handling +In case of an error, the captcha solver throws an exception. It's important to properly handle these cases. We recommend using `try except` to handle exceptions. +```python +try: + result = solver.text('If tomorrow is Saturday, what day is today?') +except ValidationException as e: + # invalid parameters passed + print(e) +except NetworkException as e: + # network error occurred + print(e) +except ApiException as e: + # api respond with error + print(e) +except TimeoutException as e: + # captcha is not solved so far + print(e) +``` + + +### Proxies + +You can pass your proxy as an additional argument for methods: recaptcha, funcaptcha and geetest. The proxy will be forwarded to the API to solve the captcha. + +```python +proxy={ + 'type': 'HTTPS', + 'uri': 'login:password@IP_address:PORT' +} +``` + +### Async calls +You can also make async calls with [asyncio], for example: + +```python +import asyncio +import concurrent.futures +from twocaptcha import TwoCaptcha + +captcha_result = await captchaSolver(image) + +async def captchaSolver(image): + loop = asyncio.get_running_loop() + with concurrent.future.ThreadPoolExecutor() as pool: + result = await loop.run_in_executor(pool, lambda: TwoCaptcha(API_KEY).normal(image)) + return result +``` + + +[2Captcha]: https://2captcha.com/ +[2captcha sofware catalog]: https://2captcha.com/software +[pingback settings]: https://2captcha.com/setting/pingback +[post options]: https://2captcha.com/2captcha-api#normal_post +[list of supported languages]: https://2captcha.com/2captcha-api#language +[examples directory]: /examples +[asyncio]: https://docs.python.org/3/library/asyncio.html + + +%prep +%autosetup -n 2captcha-python-1.2.0 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-2captcha-python -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Mon Apr 10 2023 Python_Bot <Python_Bot@openeuler.org> - 1.2.0-1 +- Package Spec generated @@ -0,0 +1 @@ +8667c9129534e166845870a57b8c809c 2captcha-python-1.2.0.tar.gz |