Metadata-Version: 2.1
Name: mosparo_django
Version: 1.0.0b2
Summary: A Django app to integrate mosparo into your forms.
Author-email: mosparo Core Developers <info@mosparo.io>
License: The MIT License (MIT)
        
        Copyright 2023 mosparo Core Developers and contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
Project-URL: Website, https://mosparo.io
Project-URL: GitHub, https://github.com/mosparo/django-integration
Keywords: mosparo,spam-protection,accessibility,captcha,django,app
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Provides-Extra: dev
License-File: LICENSE

&nbsp;
<p align="center">
    <img src="https://github.com/mosparo/mosparo/blob/master/assets/images/mosparo-logo.svg?raw=true" alt="mosparo logo contains a bird with the name Mo and the mosparo text"/>
</p>

<h1 align="center">
    Integration for Django
</h1>
<p align="center">
    This Django app offers the needed form, field, and widget class to add mosparo to your Django form.
</p>

-----

## Description
With this Django app, you can protect your forms with mosparo. Install the app, configure it and add the field to your forms.

## Installation

### Install using pip

Install this app by using pip:

```commandline
pip install mosparo_django
```

### Build from source

You need the module `build` to build the module from source.

1. Clone the repository
2. Build the package
```commandline
python -m build
```
3. Install the package
```commandline
pip install dist/mosparo_django-1.0.0b1-py3-none-any.whl
```

## Usage
1. Create a project in your mosparo installation
2. Edit the `settings.py` file of your project
2. Add the mosparo integration to the list of enabled apps:
```python
INSTALLED_APPS = [
    # ...
    'mosparo_django',
]
```
3. Specify the configuration for mosparo:
```python
MOSPARO_HOST = 'https://...'
MOSPARO_UUID = '...'
MOSPARO_PUBLIC_KEY = '...'
MOSPARO_PRIVATE_KEY = '...'
MOSPARO_VERIFY_SSL = True
```
4. Add the mosparo field to your form:
```python
from mosparo_django.fields import MosparoField

class Form(forms.Form):
    # Your other fields...
    mosparo = MosparoField(label='Spam protection')
```
5. Add the verification (see [Verification](#verification))
6. Test your form and verify that everything works correctly and you see the submission in mosparo.

### Verification

After the user submits the form, the backend has to verify the form data before you can process them. Since we didn't find a good way to do this automatically, you have to implement one of the following options:

#### Use the mosparo Form class

Use the mosparo Form class to create your form instead of the `django.forms.Form` class:

```python
from mosparo_django.forms import MosparoForm
from mosparo_django.fields import MosparoField

class Form(MosparoForm):
    # Your other fields...
    mosparo = MosparoField(label='Spam protection')
```

#### Override the `clean` method

The other option is to override the method `clean` of the Form class:

```python
from mosparo_django.fields import MosparoField

class Form(forms.Form):
    # Your other fields...
    mosparo = MosparoField(label='Spam protection')

    def clean(self):
        self.mosparo.verify_data(self)
    
        return super().clean()
```

**Important: No spam protection will happen if you do not use one of these two things.**

### Specify the connection details on the field

You can also specify the connection details on the field. For that, please add the field to your form and specify the connection settings by setting the parameters `mosparo_host`, `mosparo_uuid`, `mosparo_public_key`, `mosparo_private_key`, and `mosparo_verify_ssl`. If you want to change the UUID, public or private key, you have to specify all these three values because these depend on the project and if you want to connect the field to a different project, all three values will be different.

```python
from mosparo_django.forms import MosparoForm
from mosparo_django.fields import MosparoField

class Form(MosparoForm):
    # Your other fields...
    mosparo = MosparoField(label='Spam protection', mosparo_uuid='123', mosparo_public_key='test_key', mosparo_private_key = 'private_key')
```

### Filter the field types and form data

The MosparoField offers some callback methods to adjust the behavior of the field.

```python
from mosparo_django.forms import MosparoForm
from mosparo_django.fields import MosparoField

class Form(MosparoForm):
    # Your other fields...
    mosparo = MosparoField(callback_ignored_field_types=None, callback_verifiable_field_types=None, callback_after_prepare_form_data=None)
```

| Argument name                      | Description                                                                                                                                          |
|------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| `callback_ignored_field_types`     | Gets and returns a list of class names of field types, which should be ignored (Example: `PasswordInput`)                                            |
| `callback_verifiable_field_types`  | Gets and returns a list of class names of field types, which are verifiable (Example: `TextInput`)                                                   |
| `callback_after_prepare_form_data` | Gets the dict with all prepared form data, the required field names, and the verifiable field names as argument and expects the same to be returned. |

## License

mosparo Integration for Django is open-sourced software licensed under the [MIT License](https://opensource.org/licenses/MIT).
Please see the [LICENSE](LICENSE) file for the full license.
