captchaai 0.0.3
A package to enable interacting with the api of captchaai.com by python.
Requires Python: >=3.7

# Python Module for captchaAI API
The easiest way to quickly integrate [captchaAI] captcha solving service into your code to automate solving of any types of captcha.

- [Python Module for captchaAI API](#python-module-for-captchaAI-api)
  - [Installation](#installation)
  - [Configuration](#configuration)
    - [captchaAI instance options](#captchaAI-instance-options)
  - [Solve captcha](#solve-captcha)
    - [Captcha options](#captcha-options)
    - [Normal Captcha](#normal-captcha)
    - [ReCaptcha v2](#recaptcha-v2)
    - [ReCaptcha v3](#recaptcha-v3)
    - [hCaptcha](#hcaptcha)
  - [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 captchaAI```


## Configuration

captchaAI instance can be created like this:

```python 
from captchaAI import captchaAI

solver = captchaAI('YOUR_API_KEY')
```
Also there are few options that can be configured:

```python 
config = {
            'apiKey':           'YOUR_API_KEY',
            'defaultTimeout':    120,
            'recaptchaTimeout':  240,
            'pollingInterval':   10,
        }
solver = captchaAI(**config)
```

### captchaAI instance options

| Option           | Default value  | Description                                                                                                                                        |
| ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 | 240            | 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                              |


## Solve captcha
When you submit any image-based captcha use can provide additional options to help captchaAI 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=..., ...)
```


### 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=..., ...)
```

### 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=..., ...)

```

## 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.recaptcha(sitekey=site_key,url=url)
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 captchaAI import captchaAI

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: captchaAI(API_KEY).normal(image))
        return result
```


[captchaAI]: https://captchaAI.com/
[examples directory]: /examples
[asyncio]: https://docs.python.org/3/library/asyncio.html