<h1 align="center">
KzCaptcha - Python API Client
</h1>
<p align="center">
This library offers the API client to communicate with kuantaz to verify a submission.
</p>
---
## Description
This Python library lets you connect to a kuantaz installation and verify the submitted data.
## Installation
### Install using pip
Install this library by using pip:
```text
pip install kuantaz-api-client
```
## Usage
1. Create a project in your kuantaz installation
2. Include the kuantaz script in your form
```html
<div id="kuantaz-box"></div>
<script src="https://[URL]/build/kuantaz-frontend.js" defer></script>
<script>
var kz;
window.onload = function () {
kz = new kzCaptcha("kuantaz-box", "https://[URL]", "[UUID]", "[PUBLIC_KEY]");
};
</script>
```
3. Include the library in your project
```text
pip install kuantaz-api-client
```
4. After the form is submitted, verify the data before processing it
```python
from kuantaz_api_client import Client
api_client = Client(host, public_key, private_key)
your_post_data = {} # This needs to be filled with the post data
kuantaz_submit_token = your_post_data['_kuantaz_submitToken']
kuantaz_validation_token = your_post_data['_kuantaz_validationToken']
result = api_client.verify_submission(your_post_data, kuantaz_submit_token, kuantaz_validation_token)
if result.is_submittable():
# Send the email or process the data
pass
else:
# Show error message
pass
```
## API Documentation
### Client
#### Client initialization
Create a new client object to use the API client.
```python
from kuantaz_api_client import Client
api_client = Client(host, public_key, private_key, verify_ssl)
```
| Parameter | Type | Description |
| ----------- | ---- | ----------------------------------------------------------- |
| host | str | The host of the kuantaz installation |
| public_key | str | The public key of the kuantaz project |
| private_key | str | The private key of the kuantaz project |
| verify_ssl | bool | Set to False if the SSL certificate should not be verified. |
#### Verify form data
To verify the form data, call `verify_submission` with the form data in an array and the submit and validation tokens, which kuantaz generated on the form initialization and the form data validation. The method will return a `VerificationResult` object.
```python
result = api_client.verify_submission(form_data, kuantaz_submit_token, kuantaz_validation_token)
```
| Parameter | Type | Description |
| ------------------------ | ---- | ------------------------------------------------------------------------------------------------------------ |
| form_data | dict | The dictionary with all the submitted form data. |
| kuantaz_submit_token | str | The submit token which was generated by kuantaz and submitted with the form data |
| kuantaz_validation_token | str | The validation token which kuantaz generated after the validation and which was submitted with the form data |
### VerificationResult
#### Constants
- `FIELD_NOT_VERIFIED`: 'not-verified'
- `FIELD_VALID`: 'valid'
- `FIELD_INVALID`: 'invalid'
#### `is_submittable()`: bool
Returns `True` if the form is submittable. This means that the verification was successful and the
form data are valid.
#### `is_valid()`: bool
Returns `True` if kuantaz determined the form as valid. The difference to `is_submittable()` is, that this
is the original result from kuantaz, while `is_submittable()` also checks if the verification was done correctly.
#### `get_verified_fields()`: list (see [Constants](#constants))
Returns an array with all verified field keys.
#### `get_verified_field(key)`: string (see [Constants](#constants))
Returns the verification status of one field.
#### `has_issues()`: bool
Returns `True` if there were verification issues.
#### `get_issues()`: list
Returns an array with all verification issues.
#### Get the statistic data by date
To get the statistic data grouped by date, call `get_statistic_by_date`. The method accepts a time range in seconds for which the data should be returned (last x seconds). The method will return a `StatisticResult` object.
```python
result = api_client.get_statistic_by_date(range)
```
| Parameter | Type | Description |
| --------- | ---- | ------------------------------------------------------------------------------------- |
| range | int | The time range in seconds for which the statistic should be returned (last X seconds) |
### StatisticResult
#### `get_number_of_valid_submissions()`: int
Return the number of valid submissions in the requested time range.
#### `get_number_of_spam_submissions()`: int
Return the number of spam submissions in the requested time range.
#### `get_numbers_by_date()`: dict
Return the numbers grouped by date.
Raw data
{
"_id": null,
"home_page": "",
"name": "kuantaz-api-client",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "kuantaz,api-client,spam-protection,accessibility,captcha",
"author": "",
"author_email": "Kuantaz Core Developers <kuantaz@kuantaz.com>",
"download_url": "https://files.pythonhosted.org/packages/2f/ee/705691d04fddad999730e669907cf9768d55f340feac5447ed1e7c72d3b1/kuantaz_api_client-1.0.1.tar.gz",
"platform": null,
"description": " \n\n<h1 align=\"center\">\n KzCaptcha - Python API Client\n</h1>\n<p align=\"center\">\n This library offers the API client to communicate with kuantaz to verify a submission.\n</p>\n\n---\n\n## Description\n\nThis Python library lets you connect to a kuantaz installation and verify the submitted data.\n\n## Installation\n\n### Install using pip\n\nInstall this library by using pip:\n\n```text\npip install kuantaz-api-client\n```\n\n## Usage\n\n1. Create a project in your kuantaz installation\n2. Include the kuantaz script in your form\n\n```html\n<div id=\"kuantaz-box\"></div>\n\n<script src=\"https://[URL]/build/kuantaz-frontend.js\" defer></script>\n<script>\n var kz;\n window.onload = function () {\n kz = new kzCaptcha(\"kuantaz-box\", \"https://[URL]\", \"[UUID]\", \"[PUBLIC_KEY]\");\n };\n</script>\n```\n\n3. Include the library in your project\n\n```text\npip install kuantaz-api-client\n```\n\n4. After the form is submitted, verify the data before processing it\n\n```python\nfrom kuantaz_api_client import Client\n\napi_client = Client(host, public_key, private_key)\n\nyour_post_data = {} # This needs to be filled with the post data\n\nkuantaz_submit_token = your_post_data['_kuantaz_submitToken']\nkuantaz_validation_token = your_post_data['_kuantaz_validationToken']\n\nresult = api_client.verify_submission(your_post_data, kuantaz_submit_token, kuantaz_validation_token)\n\nif result.is_submittable():\n # Send the email or process the data\n pass\nelse:\n # Show error message\n pass\n```\n\n## API Documentation\n\n### Client\n\n#### Client initialization\n\nCreate a new client object to use the API client.\n\n```python\nfrom kuantaz_api_client import Client\n\napi_client = Client(host, public_key, private_key, verify_ssl)\n```\n\n| Parameter | Type | Description |\n| ----------- | ---- | ----------------------------------------------------------- |\n| host | str | The host of the kuantaz installation |\n| public_key | str | The public key of the kuantaz project |\n| private_key | str | The private key of the kuantaz project |\n| verify_ssl | bool | Set to False if the SSL certificate should not be verified. |\n\n#### Verify form data\n\nTo verify the form data, call `verify_submission` with the form data in an array and the submit and validation tokens, which kuantaz generated on the form initialization and the form data validation. The method will return a `VerificationResult` object.\n\n```python\nresult = api_client.verify_submission(form_data, kuantaz_submit_token, kuantaz_validation_token)\n```\n\n| Parameter | Type | Description |\n| ------------------------ | ---- | ------------------------------------------------------------------------------------------------------------ |\n| form_data | dict | The dictionary with all the submitted form data. |\n| kuantaz_submit_token | str | The submit token which was generated by kuantaz and submitted with the form data |\n| kuantaz_validation_token | str | The validation token which kuantaz generated after the validation and which was submitted with the form data |\n\n### VerificationResult\n\n#### Constants\n\n- `FIELD_NOT_VERIFIED`: 'not-verified'\n- `FIELD_VALID`: 'valid'\n- `FIELD_INVALID`: 'invalid'\n\n#### `is_submittable()`: bool\n\nReturns `True` if the form is submittable. This means that the verification was successful and the\nform data are valid.\n\n#### `is_valid()`: bool\n\nReturns `True` if kuantaz determined the form as valid. The difference to `is_submittable()` is, that this\nis the original result from kuantaz, while `is_submittable()` also checks if the verification was done correctly.\n\n#### `get_verified_fields()`: list (see [Constants](#constants))\n\nReturns an array with all verified field keys.\n\n#### `get_verified_field(key)`: string (see [Constants](#constants))\n\nReturns the verification status of one field.\n\n#### `has_issues()`: bool\n\nReturns `True` if there were verification issues.\n\n#### `get_issues()`: list\n\nReturns an array with all verification issues.\n\n#### Get the statistic data by date\n\nTo get the statistic data grouped by date, call `get_statistic_by_date`. The method accepts a time range in seconds for which the data should be returned (last x seconds). The method will return a `StatisticResult` object.\n\n```python\nresult = api_client.get_statistic_by_date(range)\n```\n\n| Parameter | Type | Description |\n| --------- | ---- | ------------------------------------------------------------------------------------- |\n| range | int | The time range in seconds for which the statistic should be returned (last X seconds) |\n\n### StatisticResult\n\n#### `get_number_of_valid_submissions()`: int\n\nReturn the number of valid submissions in the requested time range.\n\n#### `get_number_of_spam_submissions()`: int\n\nReturn the number of spam submissions in the requested time range.\n\n#### `get_numbers_by_date()`: dict\n\nReturn the numbers grouped by date.\n",
"bugtrack_url": null,
"license": "",
"summary": "Python API Client to communicate with kzCaptcha.",
"version": "1.0.1",
"project_urls": {
"Website": "https://kuantaz.com"
},
"split_keywords": [
"kuantaz",
"api-client",
"spam-protection",
"accessibility",
"captcha"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "692f66abe6634a51516361d02a05355b08d0b699e273bd0c5111cdcac8746395",
"md5": "1a379412481208b88a277eff2d7dfa09",
"sha256": "68b45cfdcc629d698b6994ea6adf3e019a31b12d1f6d7528c8cb36df762a3248"
},
"downloads": -1,
"filename": "kuantaz_api_client-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a379412481208b88a277eff2d7dfa09",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 8227,
"upload_time": "2023-07-10T05:07:48",
"upload_time_iso_8601": "2023-07-10T05:07:48.585036Z",
"url": "https://files.pythonhosted.org/packages/69/2f/66abe6634a51516361d02a05355b08d0b699e273bd0c5111cdcac8746395/kuantaz_api_client-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2fee705691d04fddad999730e669907cf9768d55f340feac5447ed1e7c72d3b1",
"md5": "4b1a634df0a7e61d773723d9d60b19eb",
"sha256": "188d229646e3caee7418cc30ea664cdffaeec6555dd14c363c7d169631019228"
},
"downloads": -1,
"filename": "kuantaz_api_client-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "4b1a634df0a7e61d773723d9d60b19eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 10111,
"upload_time": "2023-07-10T05:07:52",
"upload_time_iso_8601": "2023-07-10T05:07:52.091074Z",
"url": "https://files.pythonhosted.org/packages/2f/ee/705691d04fddad999730e669907cf9768d55f340feac5447ed1e7c72d3b1/kuantaz_api_client-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-10 05:07:52",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "kuantaz-api-client"
}
JSON