django-server-captcha 1.0.0

Fully server-side captcha for Django — math, image, and word challenges with zero external API calls.

django-server-captcha

Fully server-side captcha for Django — math, image, and word challenges with zero external API calls.

No third-party services, no API keys, no external requests. Everything runs on your own server.

Features

• Math Captcha — arithmetic expression the user must solve
• Image Captcha — 3x3 SVG shape grid; select images matching a color+shape criteria
• Word Captcha — reversed word the user must type correctly
• Refresh buttons — each captcha can be regenerated independently via AJAX
• Session-based — answers stored in Django's session framework (no database required)
• Fully server-side — no Google/reCAPTCHA keys, no external HTTP calls

Requirements

• Python 3.9+
• Django 4.2+

Installation

pip install django-server-captcha

Setup

1. Add 'captcha' to your INSTALLED_APPS:

# settings.py
INSTALLED_APPS = [
    ...
    'captcha',
]

2. Make sure django.contrib.sessions is in INSTALLED_APPS and SessionMiddleware is in MIDDLEWARE (both are enabled by default).

3. Run a migrate (for the sessions table if you haven't already):

python manage.py migrate

Usage

In a view

from captcha.views import CaptchaFormView

urlpatterns = [
    path('verify/', CaptchaFormView.as_view(), name='captcha_form'),
]

In your own view

from captcha.forms import MathCaptchaForm, ImageCaptchaForm, WordCaptchaForm

def my_view(request):
    math_form = MathCaptchaForm(request.POST or None, session=request.session)
    image_form = ImageCaptchaForm(request.POST or None, session=request.session)
    word_form = WordCaptchaForm(request.POST or None, session=request.session)

    if request.method == 'POST':
        if math_form.is_valid() and image_form.is_valid() and word_form.is_valid():
            # All captchas passed
            ...

In a template

<form method="post">
    {% csrf_token %}

    {{ math_form.answer }}
    {{ math_form.answer.errors }}

    {{ image_form.selected }}
    {{ image_form.selected.errors }}

    {{ word_form.word }}
    {{ word_form.word.errors }}

    <button type="submit">Verify</button>
</form>

Refresh endpoint

The package includes a JSON endpoint for refreshing captchas via AJAX:

# urls.py
path('captcha/refresh/', 'captcha.views.captcha_refresh', name='captcha_refresh'),

fetch("/captcha/refresh/", {
    method: "POST",
    headers: {"X-CSRFToken": csrfToken},
    body: new URLSearchParams({type: "math"})
})
.then(r => r.json())
.then(data => {
    document.getElementById("math-display").textContent = data.display;
});

Valid type values: "math", "image", "word".

License

MIT