From 0794bdbcd6dff3577eacad79aa2efba5fc537219 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rok=20Su=C5=A1nik?= Date: Wed, 28 Feb 2024 10:17:07 +0100 Subject: [PATCH 1/3] improve readme --- README.md | 94 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 63 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index f046711..cae00be 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,109 @@ -# Friendly Captcha SDK -A Python client for the Friendly Captcha service. This client allows for easy integration and verification of captcha responses with the Friendly Captcha API. +# 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) + +**This is the library you use in your backend code**. For the code that you use in your frontend, see [@friendlycaptcha/sdk](https://github.com/FriendlyCaptcha/friendly-captcha-sdk). + +## Installation -# Installation ```bash pip install friendly-captcha-client ``` -# Usage +## 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", + api_key="YOUR_API_KEY", sitekey="YOUR_SITEKEY" - ) +) ``` ### Verifying a Captcha Response -- To verify a captcha response: -``` -result: FriendlyCaptchaResult = client.verify_captcha_response("CAPTCHA_RESPONSE_HERE") -print(result.should_accept) # True + +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 ``` -- Verify with bad configuration in non-strict (default) mode -``` -client.set_siteverify_endpoint("https://incorrect.endpoint.com") -result: FriendlyCaptchaResult = client.verify_captcha_response("CAPTCHA_RESPONSE_HERE") -print(result.should_accept) # True -print(result.was_able_to_verify) # False +#### 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 ``` -- Verify with bad configuration in strict (default) mode +#### 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 -client.set_siteverify_endpoint("https://incorrect.endpoint.com") -result: FriendlyCaptchaResult = client.verify_captcha_response("CAPTCHA_RESPONSE_HERE") +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 site key. -- **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 be false instead: every response needs to be strictly verified. +- **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. -- **verbose**: (Optional) Default is False. Turn on basic logging. +- **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 +## Development + To install it locally: + ```bash pip install -e . -pip install requests_mock +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 -## Contributing -Contributions are welcome! If you'd like to contribute to this project, please submit a pull request with your changes. - - +Open source under [MIT](./LICENSE). From 608441332167c6844ca27e4b1428c20f5a6e58d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rok=20Su=C5=A1nik?= Date: Wed, 28 Feb 2024 10:31:44 +0100 Subject: [PATCH 2/3] document url shorthands --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cae00be..909985c 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ 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. +- **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. From 5250855b59b123ceb0db5d5fab231e939c7c2741 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rok=20Su=C5=A1nik?= Date: Wed, 28 Feb 2024 12:36:03 +0100 Subject: [PATCH 3/3] remove frontend lib reference --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 909985c..9a87cc9 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,6 @@ A Python client for the [Friendly Captcha](https://friendlycaptcha.com) service. > This library is for [Friendly Captcha V2](https://developer.friendlycaptcha.com) only. If you are looking for V1, look [here](https://docs.friendlycaptcha.com) -**This is the library you use in your backend code**. For the code that you use in your frontend, see [@friendlycaptcha/sdk](https://github.com/FriendlyCaptcha/friendly-captcha-sdk). - ## Installation ```bash