django-arcaptcha

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

---

Requirements

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

---

Installation

pip install django-arcaptcha

settings.py

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:

python manage.py check --deploy

---

Usage

Option 1 — Field (explicit, one line)

from arcaptcha import ArcaptchaField

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

Option 2 — Mixin (automatic injection)

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)

from arcaptcha import ArcaptchaValidator

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

---

What the client sends

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

Error responses

// 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)

# settings/test.py
ARCAPTCHA_DISABLE = True

Option B — mock the verify call per test

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

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

License

MIT