0
# Models and Validation
1
2
Django Simple Captcha uses a database-backed storage system for managing captcha challenges and responses. The `CaptchaStore` model handles challenge generation, expiration management, and validation, while standalone validation functions provide programmatic access to captcha verification.
3
4
## Capabilities
5
6
### CaptchaStore Model
7
8
Core database model that stores captcha challenges, expected responses, and manages expiration lifecycle.
9
10
```python { .api }
11
class CaptchaStore(models.Model):
12
challenge = models.CharField(max_length=32)
13
response = models.CharField(max_length=32)
14
hashkey = models.CharField(max_length=40, unique=True)
15
expiration = models.DateTimeField()
16
17
def save(*args, **kwargs):
18
"""
19
Auto-generate hashkey and expiration timestamp on save.
20
21
Parameters:
22
- args: positional arguments passed to parent save()
23
- kwargs: keyword arguments passed to parent save()
24
"""
25
26
def __str__():
27
"""
28
String representation of captcha.
29
30
Returns:
31
str: Challenge text
32
"""
33
34
@classmethod
35
def remove_expired():
36
"""
37
Delete expired captcha records from database.
38
39
Returns:
40
None
41
"""
42
43
@classmethod
44
def generate_key(generator=None):
45
"""
46
Create new captcha challenge and store in database.
47
48
Parameters:
49
- generator: str/callable, challenge generator function (optional)
50
51
Returns:
52
str: Generated hashkey for the new captcha
53
"""
54
55
@classmethod
56
def pick():
57
"""
58
Get captcha from pre-generated pool or create new one.
59
60
Returns:
61
CaptchaStore: Captcha instance from pool or newly generated
62
"""
63
64
@classmethod
65
def create_pool(count=1000):
66
"""
67
Pre-generate pool of captcha challenges for performance.
68
69
Parameters:
70
- count: int, number of captchas to generate (default: 1000)
71
72
Returns:
73
None
74
"""
75
```
76
77
### Validation Functions
78
79
Direct validation functions for programmatic captcha verification outside of form processing.
80
81
```python { .api }
82
def captcha_validate(hashkey, response):
83
"""
84
Validate captcha response against stored challenge.
85
86
Parameters:
87
- hashkey: str, unique captcha identifier
88
- response: str, user-provided captcha response
89
90
Raises:
91
rest_framework.exceptions.ValidationError: If hashkey not found, expired, or response incorrect
92
"""
93
```
94
95
### URL Helper Functions
96
97
Utility functions for generating captcha-related URLs in templates and views.
98
99
```python { .api }
100
def captcha_image_url(key):
101
"""
102
Generate image URL for given captcha key.
103
104
Parameters:
105
- key: str, captcha hashkey
106
107
Returns:
108
str: URL path for captcha image
109
"""
110
111
def captcha_audio_url(key):
112
"""
113
Generate audio URL for given captcha key.
114
115
Parameters:
116
- key: str, captcha hashkey
117
118
Returns:
119
str: URL path for captcha audio file
120
"""
121
```
122
123
## Usage Examples
124
125
### Direct Model Usage
126
127
```python
128
from captcha.models import CaptchaStore
129
130
# Create new captcha
131
hashkey = CaptchaStore.generate_key()
132
captcha = CaptchaStore.objects.get(hashkey=hashkey)
133
print(f"Challenge: {captcha.challenge}")
134
print(f"Expected response: {captcha.response}")
135
136
# Clean up expired captchas
137
expired_count = CaptchaStore.remove_expired()
138
print(f"Removed {expired_count} expired captchas")
139
```
140
141
### Pool Management
142
143
```python
144
from captcha.models import CaptchaStore
145
146
# Create pool of 500 captchas for better performance
147
created_count = CaptchaStore.create_pool(count=500)
148
print(f"Created {created_count} captchas in pool")
149
150
# Get captcha from pool (or create new if pool empty)
151
captcha = CaptchaStore.pick()
152
```
153
154
### Direct Validation
155
156
```python
157
from captcha.validators import captcha_validate
158
from rest_framework.exceptions import ValidationError
159
160
try:
161
captcha_validate(hashkey='abc123def456', response='user_answer')
162
print("Captcha valid!")
163
except ValidationError as e:
164
print(f"Captcha validation failed: {e}")
165
```
166
167
### Custom Challenge Generation
168
169
```python
170
from captcha.models import CaptchaStore
171
172
# Use specific challenge generator
173
hashkey = CaptchaStore.generate_key(generator='captcha.helpers.math_challenge')
174
captcha = CaptchaStore.objects.get(hashkey=hashkey)
175
print(f"Math challenge: {captcha.challenge}")
176
```
177
178
### Template Integration
179
180
```python
181
from captcha.helpers import captcha_image_url, captcha_audio_url
182
183
# In a view
184
def custom_captcha_view(request):
185
hashkey = CaptchaStore.generate_key()
186
context = {
187
'captcha_key': hashkey,
188
'image_url': captcha_image_url(hashkey),
189
'audio_url': captcha_audio_url(hashkey),
190
}
191
return render(request, 'custom_captcha.html', context)
192
```
193
194
## Database Schema
195
196
The `CaptchaStore` model creates a table with the following structure:
197
198
- **id**: AutoField (Primary Key)
199
- **challenge**: CharField(32) - The challenge text shown to user
200
- **response**: CharField(32) - The expected correct response
201
- **hashkey**: CharField(40, unique=True) - Unique identifier for the captcha
202
- **expiration**: DateTimeField - When this captcha expires
203
204
## Performance Considerations
205
206
- Use `create_pool()` for high-traffic sites to pre-generate captchas
207
- Run `remove_expired()` regularly via cron job or management command
208
- Consider database indexing on `hashkey` and `expiration` fields for large deployments
209
- Pool-based captchas improve response time by avoiding real-time generation