0
# Constants and Configuration
1
2
QR code error correction levels, encoding modes, and configuration constants that control QR code generation parameters and behavior.
3
4
## Capabilities
5
6
### Error Correction Constants
7
8
QR codes support four levels of error correction, allowing different amounts of the code to be damaged while still remaining readable.
9
10
```python { .api }
11
from qrcode import constants
12
13
ERROR_CORRECT_L = 1 # Low error correction (~7%)
14
ERROR_CORRECT_M = 0 # Medium error correction (~15%, default)
15
ERROR_CORRECT_Q = 3 # Quartile error correction (~25%)
16
ERROR_CORRECT_H = 2 # High error correction (~30%)
17
```
18
19
**Error Correction Level Details:**
20
21
- **ERROR_CORRECT_L**: ~7% of code words can be restored. Suitable for clean environments.
22
- **ERROR_CORRECT_M**: ~15% of code words can be restored. Default and most common choice.
23
- **ERROR_CORRECT_Q**: ~25% of code words can be restored. Good for environments with some damage risk.
24
- **ERROR_CORRECT_H**: ~30% of code words can be restored. Best for harsh environments or when embedding images.
25
26
**Usage Example:**
27
28
```python
29
import qrcode
30
from qrcode import constants
31
32
# Low error correction (smaller QR code)
33
qr_low = qrcode.QRCode(error_correction=constants.ERROR_CORRECT_L)
34
35
# High error correction (more robust, larger QR code)
36
qr_high = qrcode.QRCode(error_correction=constants.ERROR_CORRECT_H)
37
38
# Default (medium error correction)
39
qr_default = qrcode.QRCode() # Uses ERROR_CORRECT_M by default
40
```
41
42
### Encoding Mode Constants
43
44
Internal constants for QR code data encoding modes. These are typically used internally but may be relevant for advanced usage.
45
46
```python { .api }
47
from qrcode import util
48
49
MODE_NUMBER = 1 # Numeric mode (0-9)
50
MODE_ALPHA_NUM = 2 # Alphanumeric mode (0-9, A-Z, space, $%*+-./:)
51
MODE_8BIT_BYTE = 4 # Byte mode (any 8-bit data)
52
MODE_KANJI = 8 # Kanji mode (Japanese characters)
53
```
54
55
**Mode Characteristics:**
56
57
- **MODE_NUMBER**: Most efficient for numeric data (10 bits per 3 digits)
58
- **MODE_ALPHA_NUM**: Efficient for uppercase alphanumeric data (11 bits per 2 characters)
59
- **MODE_8BIT_BYTE**: Standard mode for any binary data (8 bits per byte)
60
- **MODE_KANJI**: Efficient for Japanese Kanji characters (13 bits per character)
61
62
**Usage Example:**
63
64
```python
65
import qrcode
66
from qrcode import util
67
68
# The library automatically selects optimal encoding modes
69
# But you can create custom QRData objects for specific modes
70
71
# Numeric data (automatically uses MODE_NUMBER)
72
qr = qrcode.QRCode()
73
qr.add_data('1234567890')
74
75
# Mixed data (automatically uses optimal combination)
76
qr = qrcode.QRCode()
77
qr.add_data('Order #123: $45.67') # Uses different modes for different parts
78
79
# Force specific encoding (advanced usage)
80
numeric_data = util.QRData('1234567890', mode=util.MODE_NUMBER)
81
qr = qrcode.QRCode()
82
qr.add_data(numeric_data)
83
```
84
85
### Version and Size Constants
86
87
QR code versions (sizes) range from 1 to 40, with each version having specific dimensions and data capacities.
88
89
```python { .api }
90
# Version ranges
91
MIN_VERSION = 1 # Smallest QR code (21x21 modules)
92
MAX_VERSION = 40 # Largest QR code (177x177 modules)
93
94
# Version calculation:
95
# Size = (version * 4) + 17 modules per side
96
# Version 1: 21x21 modules
97
# Version 2: 25x25 modules
98
# ...
99
# Version 40: 177x177 modules
100
```
101
102
**Version Selection:**
103
104
```python
105
import qrcode
106
107
# Auto-version (recommended)
108
qr = qrcode.QRCode(version=None) # Will auto-size
109
qr.add_data('Some data')
110
qr.make(fit=True) # Determines optimal version
111
print(f"Selected version: {qr.version}")
112
113
# Fixed version
114
qr = qrcode.QRCode(version=5) # Always 37x37 modules
115
qr.add_data('Data')
116
qr.make()
117
118
# Check version capacity
119
try:
120
qr = qrcode.QRCode(version=1) # Very small
121
qr.add_data('Too much data for version 1' * 100)
122
qr.make()
123
except qrcode.exceptions.DataOverflowError:
124
print("Data too large for specified version")
125
```
126
127
### Configuration Parameters
128
129
Default and recommended values for QR code configuration parameters.
130
131
```python { .api }
132
# Default QRCode parameters
133
DEFAULT_VERSION = None # Auto-size
134
DEFAULT_ERROR_CORRECTION = 0 # ERROR_CORRECT_M
135
DEFAULT_BOX_SIZE = 10 # Pixels per module
136
DEFAULT_BORDER = 4 # Border thickness in modules (minimum per spec)
137
138
# Border constraints
139
MIN_BORDER = 4 # Minimum border per QR code specification
140
```
141
142
**Parameter Guidelines:**
143
144
- **version**: Use `None` for auto-sizing unless you need a specific size
145
- **error_correction**: Use `ERROR_CORRECT_M` for general use, `ERROR_CORRECT_H` for embedded images
146
- **box_size**: 10 pixels is good for most displays, adjust for print resolution
147
- **border**: 4 is the minimum per specification, don't go below this
148
149
**Usage Example:**
150
151
```python
152
import qrcode
153
154
# Recommended configuration for most uses
155
qr = qrcode.QRCode(
156
version=None, # Auto-size
157
error_correction=qrcode.constants.ERROR_CORRECT_M, # Standard error correction
158
box_size=10, # Standard pixel size
159
border=4, # Minimum border
160
)
161
162
# High-quality print configuration
163
qr_print = qrcode.QRCode(
164
version=None,
165
error_correction=qrcode.constants.ERROR_CORRECT_Q, # Higher error correction
166
box_size=20, # Larger pixels for print
167
border=6, # Extra border for safety
168
)
169
170
# Compact configuration (use with caution)
171
qr_compact = qrcode.QRCode(
172
version=None,
173
error_correction=qrcode.constants.ERROR_CORRECT_L, # Lower error correction
174
box_size=5, # Smaller pixels
175
border=4, # Minimum border
176
)
177
```
178
179
### Mask Pattern Constants
180
181
QR codes use mask patterns to avoid problematic patterns in the final matrix. Usually auto-selected.
182
183
```python { .api }
184
# Mask patterns (0-7)
185
MASK_PATTERN_AUTO = None # Automatic selection (recommended)
186
MASK_PATTERNS = list(range(8)) # [0, 1, 2, 3, 4, 5, 6, 7]
187
```
188
189
**Usage Example:**
190
191
```python
192
import qrcode
193
194
# Automatic mask selection (recommended)
195
qr = qrcode.QRCode(mask_pattern=None)
196
197
# Manual mask selection (advanced usage)
198
qr = qrcode.QRCode(mask_pattern=3) # Use specific pattern
199
200
# Test different masks
201
for pattern in range(8):
202
qr = qrcode.QRCode(mask_pattern=pattern)
203
qr.add_data('Test data')
204
qr.make()
205
img = qr.make_image()
206
img.save(f'qr_mask_{pattern}.png')
207
```
208
209
## Configuration Best Practices
210
211
### General Purpose QR Codes
212
213
```python
214
qr = qrcode.QRCode(
215
version=None, # Auto-size
216
error_correction=qrcode.constants.ERROR_CORRECT_M, # Standard
217
box_size=10, # Standard
218
border=4 # Minimum safe border
219
)
220
```
221
222
### QR Codes with Embedded Images
223
224
```python
225
qr = qrcode.QRCode(
226
version=None,
227
error_correction=qrcode.constants.ERROR_CORRECT_H, # High for logo coverage
228
box_size=10,
229
border=4
230
)
231
```
232
233
### High-Density Data
234
235
```python
236
qr = qrcode.QRCode(
237
version=None, # Let it auto-size large
238
error_correction=qrcode.constants.ERROR_CORRECT_L, # Lower for more data
239
box_size=8, # Smaller for dense display
240
border=4
241
)
242
```
243
244
### Print Applications
245
246
```python
247
qr = qrcode.QRCode(
248
version=None,
249
error_correction=qrcode.constants.ERROR_CORRECT_Q, # Higher for print quality
250
box_size=20, # Larger for print resolution
251
border=6 # Extra border for print tolerance
252
)
253
```