0
# Configuration and Customization
1
2
Django Simple Captcha provides extensive configuration options for customizing captcha appearance, challenge generation, image processing, and behavior. All settings can be configured in Django's settings.py file using the `CAPTCHA_*` prefix.
3
4
## Capabilities
5
6
### Visual Appearance Settings
7
8
Configuration options for customizing the visual appearance of captcha images.
9
10
```python { .api }
11
# Font configuration
12
CAPTCHA_FONT_PATH = '/path/to/font.ttf' # str or list of font paths
13
CAPTCHA_FONT_SIZE = 22 # int, font size in points
14
15
# Image styling
16
CAPTCHA_BACKGROUND_COLOR = '#ffffff' # str, hex color for background
17
CAPTCHA_FOREGROUND_COLOR = '#001100' # str, hex color for text
18
CAPTCHA_LETTER_ROTATION = (-35, 35) # tuple, rotation range in degrees
19
CAPTCHA_IMAGE_SIZE = None # tuple, fixed (width, height) or None for auto
20
21
# High-resolution support
22
CAPTCHA_2X_IMAGE = True # bool, enable 2x resolution images
23
```
24
25
### Challenge Generation Settings
26
27
Configuration for different types of captcha challenges and their parameters.
28
29
```python { .api }
30
# Challenge type and length
31
CAPTCHA_CHALLENGE_FUNCT = 'captcha.helpers.random_char_challenge' # str or callable
32
CAPTCHA_LENGTH = 4 # int, challenge text length
33
34
# Dictionary-based challenges
35
CAPTCHA_WORDS_DICTIONARY = '/usr/share/dict/words' # str, path to word list file
36
CAPTCHA_DICTIONARY_MIN_LENGTH = 0 # int, minimum word length
37
CAPTCHA_DICTIONARY_MAX_LENGTH = 999 # int, maximum word length
38
CAPTCHA_PUNCTUATION = '.,;:' # str, punctuation for word challenges
39
40
# Math challenge customization
41
CAPTCHA_MATH_CHALLENGE_OPERATOR = '*' # str, display operator in math challenges
42
```
43
44
### Image Processing Settings
45
46
Configuration for noise functions, filters, and image processing effects.
47
48
```python { .api }
49
# Noise and filter functions
50
CAPTCHA_NOISE_FUNCTIONS = ( # tuple of noise function names/callables
51
'captcha.helpers.noise_arcs',
52
'captcha.helpers.noise_dots',
53
)
54
CAPTCHA_FILTER_FUNCTIONS = ( # tuple of filter function names/callables
55
'captcha.helpers.post_smooth',
56
)
57
58
# Custom color function
59
CAPTCHA_LETTER_COLOR_FUNCT = None # str or callable for custom letter coloring
60
```
61
62
### Performance and Behavior Settings
63
64
Configuration for captcha lifecycle, performance optimization, and operational behavior.
65
66
```python { .api }
67
# Expiration and lifecycle
68
CAPTCHA_TIMEOUT = 5 # int, expiration timeout in minutes
69
70
# Performance optimization
71
CAPTCHA_GET_FROM_POOL = False # bool, use pre-generated captcha pool
72
CAPTCHA_GET_FROM_POOL_TIMEOUT = 5 # int, pool timeout in minutes
73
74
# Testing and development
75
CAPTCHA_TEST_MODE = False # bool, disable validation for testing
76
```
77
78
### Audio Settings
79
80
Configuration for text-to-speech audio captcha functionality.
81
82
```python { .api }
83
# Audio generation paths
84
CAPTCHA_FLITE_PATH = '/usr/bin/flite' # str, path to flite text-to-speech binary
85
CAPTCHA_SOX_PATH = '/usr/bin/sox' # str, path to sox audio processing binary
86
```
87
88
### Challenge Generator Functions
89
90
Built-in challenge generator functions that can be used with `CAPTCHA_CHALLENGE_FUNCT`.
91
92
```python { .api }
93
def math_challenge():
94
"""
95
Generate simple arithmetic problems (addition, subtraction, multiplication).
96
97
Returns:
98
tuple: (challenge_text, expected_response)
99
100
Example: ('2 + 3 = ?', '5')
101
"""
102
103
def random_char_challenge():
104
"""
105
Generate random alphanumeric character string.
106
107
Returns:
108
tuple: (challenge_text, expected_response)
109
110
Example: ('AB3F', 'AB3F')
111
"""
112
113
def unicode_challenge():
114
"""
115
Generate challenge using unicode characters.
116
117
Returns:
118
tuple: (challenge_text, expected_response)
119
"""
120
121
def word_challenge():
122
"""
123
Generate challenge using dictionary words.
124
125
Returns:
126
tuple: (challenge_text, expected_response)
127
128
Requires: CAPTCHA_WORDS_DICTIONARY setting
129
"""
130
131
def huge_words_and_punctuation_challenge():
132
"""
133
Generate challenge with large words and punctuation.
134
135
Returns:
136
tuple: (challenge_text, expected_response)
137
"""
138
139
def random_letter_color_challenge(idx, plaintext_captcha):
140
"""
141
Generate random color for individual letters in captcha.
142
143
Parameters:
144
- idx: int, letter index in the captcha
145
- plaintext_captcha: str, the complete captcha text
146
147
Returns:
148
str: Hex color string (e.g., "#FF5733")
149
"""
150
```
151
152
### Noise and Filter Functions
153
154
Built-in functions for adding visual noise and post-processing effects to captcha images.
155
156
```python { .api }
157
def noise_arcs(draw, image):
158
"""
159
Add curved arc noise to captcha image.
160
161
Parameters:
162
- draw: PIL ImageDraw object
163
- image: PIL Image object
164
"""
165
166
def noise_dots(draw, image):
167
"""
168
Add random dot noise to captcha image.
169
170
Parameters:
171
- draw: PIL ImageDraw object
172
- image: PIL Image object
173
"""
174
175
def noise_null(draw, image):
176
"""
177
No-operation noise function (no visual noise added).
178
179
Parameters:
180
- draw: PIL ImageDraw object
181
- image: PIL Image object
182
"""
183
184
def post_smooth(image):
185
"""
186
Apply smoothing filter to reduce image harshness.
187
188
Parameters:
189
- image: PIL Image object
190
191
Returns:
192
PIL.Image: Filtered image
193
"""
194
```
195
196
### Configuration Helper Functions
197
198
Utility functions for loading and processing configuration settings.
199
200
```python { .api }
201
def _callable_from_string(string_or_callable):
202
"""
203
Import callable from string module path.
204
205
Parameters:
206
- string_or_callable: str or callable
207
208
Returns:
209
callable: Imported function or original callable
210
"""
211
212
def get_challenge(generator=None):
213
"""
214
Get challenge generator function from settings or parameter.
215
216
Parameters:
217
- generator: str or callable, override default generator (optional)
218
219
Returns:
220
callable: Challenge generator function
221
"""
222
223
def noise_functions():
224
"""
225
Get configured noise function generators.
226
227
Returns:
228
list: List of noise function callables
229
"""
230
231
def filter_functions():
232
"""
233
Get configured filter function generators.
234
235
Returns:
236
list: List of filter function callables
237
"""
238
239
def get_letter_color(index, challenge):
240
"""
241
Get color for specific letter in challenge.
242
243
Parameters:
244
- index: int, letter position in challenge
245
- challenge: str, complete challenge text
246
247
Returns:
248
str: Color value for the letter
249
"""
250
```
251
252
## Usage Examples
253
254
### Basic Configuration
255
256
```python
257
# In settings.py
258
CAPTCHA_FONT_SIZE = 24
259
CAPTCHA_LENGTH = 6
260
CAPTCHA_TIMEOUT = 10 # 10 minutes
261
CAPTCHA_BACKGROUND_COLOR = '#f0f0f0'
262
CAPTCHA_FOREGROUND_COLOR = '#333333'
263
```
264
265
### Math Challenge Configuration
266
267
```python
268
# Use math challenges instead of random text
269
CAPTCHA_CHALLENGE_FUNCT = 'captcha.helpers.math_challenge'
270
CAPTCHA_MATH_CHALLENGE_OPERATOR = '+'
271
CAPTCHA_LENGTH = 1 # Not used for math challenges
272
```
273
274
### Dictionary Word Challenges
275
276
```python
277
# Use dictionary words for challenges
278
CAPTCHA_CHALLENGE_FUNCT = 'captcha.helpers.word_challenge'
279
CAPTCHA_WORDS_DICTIONARY = '/usr/share/dict/words'
280
CAPTCHA_DICTIONARY_MIN_LENGTH = 4
281
CAPTCHA_DICTIONARY_MAX_LENGTH = 8
282
```
283
284
### Custom Noise Configuration
285
286
```python
287
# Add more visual noise
288
CAPTCHA_NOISE_FUNCTIONS = (
289
'captcha.helpers.noise_arcs',
290
'captcha.helpers.noise_dots',
291
'captcha.helpers.noise_dots', # Apply dots twice for more noise
292
)
293
294
# Apply smoothing filter
295
CAPTCHA_FILTER_FUNCTIONS = (
296
'captcha.helpers.post_smooth',
297
)
298
```
299
300
### Performance Optimization
301
302
```python
303
# Enable captcha pool for high-traffic sites
304
CAPTCHA_GET_FROM_POOL = True
305
CAPTCHA_GET_FROM_POOL_TIMEOUT = 10
306
307
# Longer expiration time
308
CAPTCHA_TIMEOUT = 15 # 15 minutes
309
```
310
311
### Audio Configuration
312
313
```python
314
# Enable audio captcha with custom paths
315
CAPTCHA_FLITE_PATH = '/opt/flite/bin/flite'
316
CAPTCHA_SOX_PATH = '/opt/sox/bin/sox'
317
```
318
319
### Custom Challenge Generator
320
321
```python
322
# Create custom challenge function
323
def custom_challenge():
324
import random
325
import string
326
327
# Generate uppercase letters only
328
chars = ''.join(random.choices(string.ascii_uppercase, k=5))
329
return chars, chars
330
331
# Use custom challenge
332
CAPTCHA_CHALLENGE_FUNCT = 'myapp.utils.custom_challenge'
333
```
334
335
### Test Mode Configuration
336
337
```python
338
# Disable captcha validation for testing
339
CAPTCHA_TEST_MODE = True # Only use in development/testing!
340
```
341
342
## Default Values
343
344
All configuration settings have sensible defaults:
345
346
- Font size: 22 points
347
- Challenge length: 4 characters
348
- Timeout: 5 minutes
349
- Background: white (#ffffff)
350
- Foreground: dark green (#001100)
351
- Challenge type: random characters
352
- Pool usage: disabled
353
- Test mode: disabled
354
- High-resolution images: enabled