0
# Django reCAPTCHA
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: django-recaptcha
7
- **Language**: Python
8
- **Framework**: Django
9
- **Installation**: `pip install django-recaptcha`
10

11
## Core Imports
12

13
```python
14
from django_recaptcha.fields import ReCaptchaField
15
from django_recaptcha.widgets import ReCaptchaV2Checkbox, ReCaptchaV2Invisible, ReCaptchaV3
16
from django_recaptcha.client import submit, RecaptchaResponse
17
from django_recaptcha.constants import TEST_PUBLIC_KEY, TEST_PRIVATE_KEY, DEFAULT_RECAPTCHA_DOMAIN
18
```
19

20
## Basic Usage
21

22
```python
23
from django import forms
24
from django_recaptcha.fields import ReCaptchaField
25

26
class ContactForm(forms.Form):
27
    name = forms.CharField(max_length=100)
28
    email = forms.EmailField()
29
    message = forms.CharField(widget=forms.Textarea)
30
    captcha = ReCaptchaField()
31

32
# In your view
33
def contact(request):
34
    if request.method == 'POST':
35
        form = ContactForm(request.POST)
36
        if form.is_valid():
37
            # Form is valid, reCAPTCHA validation passed
38
            process_form(form.cleaned_data)
39
    else:
40
        form = ContactForm()
41
    return render(request, 'contact.html', {'form': form})
42
```
43

44
## Architecture
45

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

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

53
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.
54

55
## Capabilities
56

57
### Form Fields
58

59
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.
60

61
```python { .api }
62
class ReCaptchaField(forms.CharField):
63
    def __init__(self, public_key=None, private_key=None, *args, **kwargs): ...
64
    def validate(self, value): ...
65
    def get_remote_ip(self): ...
66
```
67

68
[Form Fields](./form-fields.md)
69

70
### reCAPTCHA Widgets
71

72
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.
73

74
```python { .api }
75
class ReCaptchaV2Checkbox(ReCaptchaBase): ...
76
class ReCaptchaV2Invisible(ReCaptchaBase): ...
77
class ReCaptchaV3(ReCaptchaBase):
78
    def __init__(self, api_params=None, action=None, required_score=None, *args, **kwargs): ...
79
```
80

81
[reCAPTCHA Widgets](./widgets.md)
82

83
### Client API
84

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

87
```python { .api }
88
def submit(recaptcha_response, private_key, remoteip): ...
89
class RecaptchaResponse:
90
    def __init__(self, is_valid, error_codes=None, extra_data=None, action=None): ...
91
```
92

93
[Client API](./client-api.md)
94

95
### Configuration and Settings
96

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

99
```python { .api }
100
# Settings constants
101
TEST_PUBLIC_KEY: str
102
TEST_PRIVATE_KEY: str
103
DEFAULT_RECAPTCHA_DOMAIN: str
104
```
105

106
[Configuration](./configuration.md)
107

108
## Types
109

110
```python { .api }
111
class RecaptchaResponse:
112
    """Response from Google reCAPTCHA API"""
113
    is_valid: bool
114
    error_codes: list[str]
115
    extra_data: dict
116
    action: str | None
117
```