Django reCAPTCHA

Django form field and widget integration for Google reCAPTCHA services, supporting reCAPTCHA V2 (both Checkbox and Invisible variants) and reCAPTCHA V3. This package provides seamless integration with Django forms through configurable fields and widgets, comprehensive validation capabilities, and built-in development support.

Package Information

• Package Name: django-recaptcha
• Language: Python
• Framework: Django
• Installation: pip install django-recaptcha

Core Imports

from django_recaptcha.fields import ReCaptchaField
from django_recaptcha.widgets import ReCaptchaV2Checkbox, ReCaptchaV2Invisible, ReCaptchaV3
from django_recaptcha.client import submit, RecaptchaResponse
from django_recaptcha.constants import TEST_PUBLIC_KEY, TEST_PRIVATE_KEY, DEFAULT_RECAPTCHA_DOMAIN

Basic Usage

from django import forms
from django_recaptcha.fields import ReCaptchaField

class ContactForm(forms.Form):
    name = forms.CharField(max_length=100)
    email = forms.EmailField()
    message = forms.CharField(widget=forms.Textarea)
    captcha = ReCaptchaField()

# In your view
def contact(request):
    if request.method == 'POST':
        form = ContactForm(request.POST)
        if form.is_valid():
            # Form is valid, reCAPTCHA validation passed
            process_form(form.cleaned_data)
    else:
        form = ContactForm()
    return render(request, 'contact.html', {'form': form})

Architecture

Django reCAPTCHA follows Django's form system architecture with three main components:

• ReCaptchaField: Django form field that handles validation and integrates with Google's API
• Widget Classes: Render different reCAPTCHA types (V2 Checkbox, V2 Invisible, V3) with appropriate templates
• Client Module: Handles HTTP communication with Google's verification API
• Configuration System: Integrates with Django settings for keys, domains, and proxy configuration

The package automatically detects client IP addresses, supports proxy configurations for enterprise environments, provides comprehensive error handling, and includes Django system checks for configuration validation.

Capabilities

Form Fields

Django form field integration providing the main ReCaptchaField for adding reCAPTCHA validation to forms. Supports runtime key specification, automatic validation with Google's API, and comprehensive error handling.

class ReCaptchaField(forms.CharField):
    def __init__(self, public_key=None, private_key=None, *args, **kwargs): ...
    def validate(self, value): ...
    def get_remote_ip(self): ...

Form Fields

reCAPTCHA Widgets

Widget implementations for reCAPTCHA V2 (Checkbox and Invisible) and V3, providing different user interaction patterns and security models. Supports extensive customization through data attributes and API parameters.

class ReCaptchaV2Checkbox(ReCaptchaBase): ...
class ReCaptchaV2Invisible(ReCaptchaBase): ...
class ReCaptchaV3(ReCaptchaBase):
    def __init__(self, api_params=None, action=None, required_score=None, *args, **kwargs): ...

reCAPTCHA Widgets

Client API

Low-level client for direct interaction with Google's reCAPTCHA verification API. Handles HTTP requests, proxy configuration, response parsing, and error handling.

def submit(recaptcha_response, private_key, remoteip): ...
class RecaptchaResponse:
    def __init__(self, is_valid, error_codes=None, extra_data=None, action=None): ...

Client API

Configuration and Settings

Django settings integration for reCAPTCHA keys, API domains, proxy configuration, and system checks. Includes development support with Google's test keys and comprehensive validation.

# Settings constants
TEST_PUBLIC_KEY: str
TEST_PRIVATE_KEY: str
DEFAULT_RECAPTCHA_DOMAIN: str

Configuration

Types

class RecaptchaResponse:
    """Response from Google reCAPTCHA API"""
    is_valid: bool
    error_codes: list[str]
    extra_data: dict
    action: str | None