Metadata-Version: 2.4
Name: django-arcaptcha
Version: 1.0.0
Summary: Arcaptcha integration for Django REST Framework — field, mixin, and validator.
License: MIT
Project-URL: Homepage, https://github.com/rassoulshah/django-arcaptcha
Project-URL: Issues, https://github.com/rassoulshah/django-arcaptcha/issues
Keywords: django,arcaptcha,captcha,drf,rest-framework
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: djangorestframework>=3.14
Requires-Dist: arcaptcha-python>=0.1.2
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-django>=4; extra == "dev"
Dynamic: license-file

# django-arcaptcha

Arcaptcha integration for Django REST Framework.
Works exactly like `django-recaptcha` — add one line to any serializer.

[![PyPI](https://img.shields.io/pypi/v/django-arcaptcha)](https://pypi.org/project/django-arcaptcha/)
[![CI](https://github.com/yourname/django-arcaptcha/actions/workflows/ci.yml/badge.svg)](https://github.com/yourname/django-arcaptcha/actions)

---

## Requirements

- Python 3.10+
- Django 4.2+
- Django REST Framework 3.14+
- arcaptcha-python 0.1.2+

---

## Installation

```bash
pip install django-arcaptcha
```

**`settings.py`**
```python
INSTALLED_APPS = [
    ...
    "arcaptcha",
]

# Get your keys at https://arcaptcha.ir
ARCAPTCHA_SITE_KEY   = "your_site_key"
ARCAPTCHA_SECRET_KEY = "your_secret_key"
```

Verify your setup:
```bash
python manage.py check --deploy
```

---

## Usage

### Option 1 — Field (explicit, one line)

```python
from arcaptcha import ArcaptchaField

class LoginSerializer(serializers.Serializer):
    email    = serializers.EmailField()
    password = serializers.CharField(write_only=True)
    captcha  = ArcaptchaField()
```

### Option 2 — Mixin (automatic injection)

```python
from arcaptcha import ArcaptchaMixin

class LoginSerializer(ArcaptchaMixin, serializers.Serializer):
    email    = serializers.EmailField()
    password = serializers.CharField(write_only=True)
    # `captcha` field is injected automatically
```

### Option 3 — Validator (anywhere outside a serializer)

```python
from arcaptcha import ArcaptchaValidator

# in a view, task, or any callable
ArcaptchaValidator()(request.data["captcha"])
```

---

## What the client sends

```json
POST /api/auth/login/
{
    "email":    "alice@example.com",
    "password": "secret",
    "captcha":  "<token-from-arcaptcha-widget>"
}
```

### Error responses

```json
// Invalid token → HTTP 400
{"captcha": ["Invalid or expired captcha. Please try again."]}

// Service down → HTTP 400
{"captcha": ["Captcha verification is temporarily unavailable. Please try again later."]}
```

---

## All settings

| Setting | Default | Description |
|---|---|---|
| `ARCAPTCHA_SITE_KEY` | — | **Required.** Your site key from arcaptcha.ir |
| `ARCAPTCHA_SECRET_KEY` | — | **Required.** Your secret key from arcaptcha.ir |
| `ARCAPTCHA_DISABLE` | `False` | Skip verification — **test/local only** |
| `ARCAPTCHA_LANG` | `"en"` | Widget language: `"en"` or `"fa"` |
| `ARCAPTCHA_THEME` | `"light"` | Widget theme: `"light"` or `"dark"` |
| `ARCAPTCHA_SIZE` | `"normal"` | Widget size: `"normal"` or `"compact"` |

---

## Testing in your project

**Option A — disable in test settings (simplest)**
```python
# settings/test.py
ARCAPTCHA_DISABLE = True
```

**Option B — mock the verify call per test**
```python
from unittest.mock import patch

@patch("arcaptcha.validators.verify_arcaptcha", return_value=True)
def test_login(mock_verify, api_client):
    res = api_client.post("/api/auth/login/", {
        "email": "a@b.com", "password": "secret", "captcha": "any"
    })
    assert res.status_code == 200
```

---

## Contributing

```bash
git clone https://github.com/rassoulshah/django-arcaptcha
cd django-arcaptcha
pip install -e ".[dev]"
pytest
```

## License

MIT
