Metadata-Version: 2.4
Name: django-generic-contact
Version: 1.2.2
Summary: Django module to store contact request in a structured yet generic manner.
Author-email: Alexandra Bruckner <abruckner@anexia-it.com>
License: MIT License
Project-URL: Homepage, https://github.com/anexia/django-generic-contact
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django<6.1,>=4.2
Requires-Dist: jsonschema<4.24,>=4.23.0
Provides-Extra: dev
Requires-Dist: build<1.3,>=1.2.2; extra == "dev"
Requires-Dist: coverage<7.7,>=7.6.2; extra == "dev"
Requires-Dist: pre-commit<4.2,>=4.0.1; extra == "dev"
Requires-Dist: setuptools<76.2,>=75.1.0; extra == "dev"
Requires-Dist: setuptools-scm<8.2,>=8.1; extra == "dev"
Requires-Dist: twine<5.2,>=5.1.1; extra == "dev"
Requires-Dist: wheel<0.45,>=0.44.0; extra == "dev"
Dynamic: license-file

## Django Generic Contact

[![PyPI version](https://img.shields.io/pypi/v/django-generic-contact.svg)](https://pypi.org/project/django-generic-contact/)
[![Run linter and tests](https://github.com/anexia/django-generic-contact/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/anexia/django-generic-contact/actions/workflows/test.yml)
[![Codecov](https://img.shields.io/codecov/c/gh/anexia/django-generic-contact)](https://codecov.io/gh/anexia/django-generic-contact)

Django module to store contact request in a structured yet generic manner within the database.

Supported versions (from endoflife.date):
- Python: 3.10, 3.11, 3.12, 3.13, 3.14
- Django: 4.2 (LTS), 5.2 (LTS), 6.0

### Installation

1. Install using pip:

```shell
pip install django-generic-contact
```

2. Integrate `django_generic_contact` into your `settings.py`

```python
INSTALLED_APPS = [
    # ...
    'django_generic_contact',
    # ...
]
```

### Usage

The package provides you with a `Contact` model which expects `data` (dict) and the `name` of the requester,
an optional `message` can be added:

```
from django_generic_contact.models import Contact

contact = Contact.objects.create(
    name="Mr. Tester",
    message="Please contact me via email or phone.",
    data={
        "email": "mr@tester.com",
        "phone": "123456",
    }
)
```

#### JSON Schema validation

The contents of `data` will be validated against a [json schema](https://json-schema.org/) defined in your project's
`settings.py` (if provided). If needed you can define `GENERIC_CONTACT_DATA_SCHEMA` to check all relevant input
according to the expected structure, e.g.:

```
GENERIC_CONTACT_DATA_SCHEMA = {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "email": {"type": "string", "format": "email"},
        "phone": {"type": "integer"},
    },
}
```

See more examples of `GENERIC_CONTACT_DATA_SCHEMA` in `tests/testapp/tests/test_model.py`.

#### Customizing the Contact model
The base model `GenericContact` only requires the `data`. Thus, you can let your own models inherit from this and extend
it according to your project's needs, e.g.:

```
from django_generic_contact.models import GenericContact

class CustomContact(GenericContact):
    birth_date = models.Datetime(_("birth date"))
    zip = models.CharField(_("zip"))
```

## Unit Tests

See folder [tests/](tests/). The provided tests cover these criteria:
* success:
  * Contact model instance creation
  * project's jsonschema validation
* failure:
  * project's jsonschema validation
  * exemplary custom jsonschema validation

Follow below instructions to run the tests.
You may exchange the installed Django and DRF versions according to your requirements.
:warning: Depending on your local environment settings you might need to explicitly call `python3` instead of `python`.
```bash
# install dependencies
python -m pip install --upgrade pip
pip install -e .[dev]

# run tests
cd tests && python manage.py test
```

### Contributing

Contributions are welcomed! Read the [Contributing Guide](CONTRIBUTING.md) for more information.

### Licensing

See [LICENSE](LICENSE) for more information.
