# Friendly Captcha Python SDK
A Python client for the [Friendly Captcha](https://friendlycaptcha.com) service. This client allows for easy integration and verification of captcha responses with the Friendly Captcha API.
> This library is for [Friendly Captcha V2](https://developer.friendlycaptcha.com) only. If you are looking for V1, look [here](https://docs.friendlycaptcha.com)
## Installation
```bash
pip install friendly-captcha-client
```
## Usage
Below are some basic examples of how to use the client.
For a more detailed example, take a look at the [example](./example) directory.
### Initialization
To start using the client:
```python
from friendly_client import FriendlyCaptchaClient
client = FriendlyCaptchaClient(
api_key="YOUR_API_KEY",
sitekey="YOUR_SITEKEY"
)
```
### Verifying a Captcha Response
After calling `verify_captcha_response` with the captcha response there are two functions on the result object that you should check:
- `was_able_to_verify` indicates whether we were able to verify the captcha response. This will be `False` in case there was an issue with the network/our service or if there was a mistake in the configuration.
- `should_accept` indicates whether the captcha response was correct. If the client is running in non-strict mode (default) and `was_able_to_verify` returned `False`, this will be `True`.
Below are some examples of this behaviour.
#### Verifying a correct captcha response without issues when veryfing:
```python
result = client.verify_captcha_response("CORRECT?CAPTCHA_RESPONSE_HERE")
print(result.was_able_to_verify) # True
print(result.should_accept) # True
```
#### Verifying an incorrect captcha response without issues when veryfing:
```python
result = client.verify_captcha_response("INCORRECT_CAPTCHA_RESPONSE_HERE")
print(result.was_able_to_verify) # True
print(result.should_accept) # False
```
#### Verifying an incorrect captcha response with issues (network issues or bad configuration) when veryfing in non-strict mode (default):
```python
result = client.verify_captcha_response("INCORRECT_CAPTCHA_RESPONSE_HERE")
print(result.was_able_to_verify) # False
print(result.should_accept) # True
```
#### Verifying an incorrect captcha response with issues (network/service issues or bad configuration) when veryfing in strict mode:
```python
client.strict = True
result = client.verify_captcha_response("INCORRECT_CAPTCHA_RESPONSE_HERE")
print(result.should_accept) # False
print(result.was_able_to_verify) # False
```
### Configuration
The client offers several configuration options:
- **api_key**: Your Friendly Captcha API key.
- **sitekey**: Your Friendly Captcha sitekey.
- **strict**: (Optional) In case the client was not able to verify the captcha response at all (for example if there is a network failure or a mistake in configuration), by default the `verify_captcha_response` returns `True` regardless. By passing `strict=True`, it will return `False` instead: every response needs to be strictly verified.
- **siteverify_endpoint**: (Optional) The endpoint URL for the site verification API. Shorthands `eu` or `global` are also accepted. Default is `global`.
- **verbose**: (Optional) Default is False. Turn on basic logging.
- Error Handling: The client has built-in error handling mechanisms. In case of unexpected responses or errors from the Friendly Captcha API, the client will log the error and provide a default response.
## Development
To install it locally:
```bash
pip install -e .
pip install -r requirements-dev.txt
```
Run the tests:
```bash
# Run the unit tests
python -m pytest
# Run the SDK integration tests (requires that you have the SDK test mock server running)
docker run -p 1090:1090 friendlycaptcha/sdk-testserver:latest
python -m pytest integration_tests
```
## License
Open source under [MIT](./LICENSE).
Raw data
{
"_id": null,
"home_page": "https://developer.friendlycaptcha.com/",
"name": "friendly-captcha-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.6",
"maintainer_email": null,
"keywords": "Friendly Captcha Client, Captcha",
"author": "Antal Nagy",
"author_email": "dev@friendlycaptcha.com",
"download_url": "https://files.pythonhosted.org/packages/59/07/96ad48c17b6493becff80efe3d76b566746908325e50c9bcb35cbd008110/friendly_captcha_client-0.1.0.tar.gz",
"platform": null,
"description": "# Friendly Captcha Python SDK\n\nA Python client for the [Friendly Captcha](https://friendlycaptcha.com) service. This client allows for easy integration and verification of captcha responses with the Friendly Captcha API.\n\n> This library is for [Friendly Captcha V2](https://developer.friendlycaptcha.com) only. If you are looking for V1, look [here](https://docs.friendlycaptcha.com)\n\n## Installation\n\n```bash\npip install friendly-captcha-client\n```\n\n## Usage\n\nBelow are some basic examples of how to use the client.\n\nFor a more detailed example, take a look at the [example](./example) directory.\n\n### Initialization\n\nTo start using the client:\n\n```python\nfrom friendly_client import FriendlyCaptchaClient\n\nclient = FriendlyCaptchaClient(\n api_key=\"YOUR_API_KEY\",\n sitekey=\"YOUR_SITEKEY\"\n)\n```\n\n### Verifying a Captcha Response\n\nAfter calling `verify_captcha_response` with the captcha response there are two functions on the result object that you should check:\n\n- `was_able_to_verify` indicates whether we were able to verify the captcha response. This will be `False` in case there was an issue with the network/our service or if there was a mistake in the configuration.\n- `should_accept` indicates whether the captcha response was correct. If the client is running in non-strict mode (default) and `was_able_to_verify` returned `False`, this will be `True`.\n\nBelow are some examples of this behaviour.\n\n#### Verifying a correct captcha response without issues when veryfing:\n\n```python\nresult = client.verify_captcha_response(\"CORRECT?CAPTCHA_RESPONSE_HERE\")\nprint(result.was_able_to_verify) # True\nprint(result.should_accept) # True\n```\n\n#### Verifying an incorrect captcha response without issues when veryfing:\n\n```python\nresult = client.verify_captcha_response(\"INCORRECT_CAPTCHA_RESPONSE_HERE\")\nprint(result.was_able_to_verify) # True\nprint(result.should_accept) # False\n```\n\n#### Verifying an incorrect captcha response with issues (network issues or bad configuration) when veryfing in non-strict mode (default):\n\n```python\nresult = client.verify_captcha_response(\"INCORRECT_CAPTCHA_RESPONSE_HERE\")\nprint(result.was_able_to_verify) # False\nprint(result.should_accept) # True\n```\n\n#### Verifying an incorrect captcha response with issues (network/service issues or bad configuration) when veryfing in strict mode:\n\n```python\nclient.strict = True\nresult = client.verify_captcha_response(\"INCORRECT_CAPTCHA_RESPONSE_HERE\")\nprint(result.should_accept) # False\nprint(result.was_able_to_verify) # False\n```\n\n### Configuration\n\nThe client offers several configuration options:\n\n- **api_key**: Your Friendly Captcha API key.\n- **sitekey**: Your Friendly Captcha sitekey.\n- **strict**: (Optional) In case the client was not able to verify the captcha response at all (for example if there is a network failure or a mistake in configuration), by default the `verify_captcha_response` returns `True` regardless. By passing `strict=True`, it will return `False` instead: every response needs to be strictly verified.\n- **siteverify_endpoint**: (Optional) The endpoint URL for the site verification API. Shorthands `eu` or `global` are also accepted. Default is `global`.\n- **verbose**: (Optional) Default is False. Turn on basic logging.\n- Error Handling: The client has built-in error handling mechanisms. In case of unexpected responses or errors from the Friendly Captcha API, the client will log the error and provide a default response.\n\n## Development\n\nTo install it locally:\n\n```bash\npip install -e .\npip install -r requirements-dev.txt\n```\n\nRun the tests:\n\n```bash\n# Run the unit tests\npython -m pytest\n\n# Run the SDK integration tests (requires that you have the SDK test mock server running)\ndocker run -p 1090:1090 friendlycaptcha/sdk-testserver:latest\npython -m pytest integration_tests\n```\n\n## License\n\nOpen source under [MIT](./LICENSE).\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A client for Friendly Captcha.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://developer.friendlycaptcha.com/",
"Repository": "https://github.com/FriendlyCaptcha/friendly-captcha-python"
},
"split_keywords": [
"friendly captcha client",
" captcha"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3f1ab70893cdc7b1525570c5b473519e14c7d2422cff0db1fc7a61ef65e65d09",
"md5": "4bb57e445257c45569956fb8cf57dafd",
"sha256": "4a4a88d2cc91aa8ac7ca3cc2d2f0b51760fafdfc8dda5efa01cfe77c4afa2651"
},
"downloads": -1,
"filename": "friendly_captcha_client-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bb57e445257c45569956fb8cf57dafd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.6",
"size": 6410,
"upload_time": "2024-10-21T15:06:11",
"upload_time_iso_8601": "2024-10-21T15:06:11.277673Z",
"url": "https://files.pythonhosted.org/packages/3f/1a/b70893cdc7b1525570c5b473519e14c7d2422cff0db1fc7a61ef65e65d09/friendly_captcha_client-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "590796ad48c17b6493becff80efe3d76b566746908325e50c9bcb35cbd008110",
"md5": "f74b26ba22d4079648c3fa14195a37c9",
"sha256": "806f4086c00babe7adac1e298ca514ded545d4fd5dc9cb2fbddb9b7d934d04da"
},
"downloads": -1,
"filename": "friendly_captcha_client-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f74b26ba22d4079648c3fa14195a37c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.6",
"size": 5553,
"upload_time": "2024-10-21T15:06:12",
"upload_time_iso_8601": "2024-10-21T15:06:12.795799Z",
"url": "https://files.pythonhosted.org/packages/59/07/96ad48c17b6493becff80efe3d76b566746908325e50c9bcb35cbd008110/friendly_captcha_client-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-21 15:06:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FriendlyCaptcha",
"github_project": "friendly-captcha-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "friendly-captcha-client"
}
JSON
