0
# QRCode
1

2
A comprehensive Python library for generating QR codes with support for multiple image formats, error correction levels, customizable styling, and both command-line and programmatic interfaces. Provides publication-quality QR code images through various backends including PIL, pure Python, and SVG.
3

4
## Package Information
5

6
- **Package Name**: qrcode
7
- **Language**: Python
8
- **Installation**: `pip install qrcode` (basic) or `pip install "qrcode[pil]"` (with PIL support)
9

10
## Core Imports
11

12
```python
13
import qrcode
14
```
15

16
For specific functionality:
17

18
```python
19
from qrcode import QRCode, make
20
from qrcode import constants
21
from qrcode import exceptions
22
```
23

24
## Basic Usage
25

26
### Quick QR Code Generation
27

28
```python
29
import qrcode
30

31
# Simple QR code generation
32
img = qrcode.make('Hello, World!')
33
img.save('qrcode.png')
34

35
# The image type depends on available libraries:
36
# - PIL available: returns qrcode.image.pil.PilImage
37
# - PIL not available: returns qrcode.image.pure.PyPNGImage
38
```
39

40
### Advanced QR Code Generation
41

42
```python
43
import qrcode
44
from qrcode import constants
45

46
# Create QRCode instance with custom settings
47
qr = qrcode.QRCode(
48
    version=1,                              # Size (1-40, or None for auto)
49
    error_correction=constants.ERROR_CORRECT_M,  # Error correction level
50
    box_size=10,                           # Pixels per box
51
    border=4,                              # Border size in boxes
52
)
53

54
# Add data and generate
55
qr.add_data('Some data')
56
qr.make(fit=True)  # Auto-size if version=None
57

58
# Create image with custom colors
59
img = qr.make_image(fill_color="black", back_color="white")
60
img.save('custom_qrcode.png')
61
```
62

63
## Architecture
64

65
QRCode uses a layered architecture that separates QR code logic from image generation:
66

67
- **QRCode Class**: Core QR generation engine handling data encoding, version calculation, and matrix creation
68
- **Image Factories**: Pluggable image generation backends (PIL, PyPNG, SVG) with consistent interface
69
- **Module Drawers**: Customizable drawing components for individual QR code modules (squares, circles, etc.)
70
- **Color Masks**: Advanced coloring systems for styled QR codes with gradients and patterns
71
- **Console Interface**: Command-line tool supporting all image formats and ASCII terminal output
72

73
This design enables flexible output formats while maintaining QR code standard compliance.
74

75
## Capabilities
76

77
### Core QR Code Generation
78

79
Essential QR code creation functionality including the main QRCode class, quick generation function, version management, and data optimization features.
80

81
```python { .api }
82
def make(data=None, **kwargs):
83
    """Quick QR code generation shortcut function."""
84

85
class QRCode:
86
    """Main QR code generator with full control over all parameters."""
87
    def __init__(self, version=None, error_correction=constants.ERROR_CORRECT_M, 
88
                 box_size=10, border=4, image_factory=None, mask_pattern=None): ...
89
    def add_data(self, data, optimize=20): ...
90
    def make(self, fit=True): ...
91
    def make_image(self, image_factory=None, **kwargs): ...
92
```
93

94
[Core QR Code Generation](./core-generation.md)
95

96
### Image Formats and Factories
97

98
Multiple image output formats including PIL-based images, pure Python PNG, and various SVG formats. Each factory provides different capabilities and dependencies.
99

100
```python { .api }
101
class PilImage:
102
    """PIL-based image factory supporting PNG, JPEG, and other PIL formats."""
103

104
class PyPNGImage:
105
    """Pure Python PNG image factory with no external dependencies."""
106

107
class SvgImage:
108
    """Standalone SVG image factory."""
109

110
class StyledPilImage:
111
    """Advanced PIL image factory with custom module drawers and color masks."""
112
```
113

114
[Image Formats](./image-formats.md)
115

116
### Error Correction and Constants
117

118
QR code error correction levels and configuration constants for controlling QR code generation parameters.
119

120
```python { .api }
121
ERROR_CORRECT_L = 1    # ~7% error correction
122
ERROR_CORRECT_M = 0    # ~15% error correction (default)
123
ERROR_CORRECT_Q = 3    # ~25% error correction
124
ERROR_CORRECT_H = 2    # ~30% error correction
125
```
126

127
[Constants and Configuration](./constants.md)
128

129
### Console and Output Options
130

131
Command-line interface and various output methods including ASCII terminal output, TTY color output, and file generation.
132

133
```python { .api }
134
class QRCode:
135
    def print_ascii(self, out=None, tty=False, invert=False): ...
136
    def print_tty(self, out=None): ...
137
    def get_matrix(self): ...
138
```
139

140
[Console Interface](./console-interface.md)
141

142
### Styling and Customization
143

144
Advanced styling capabilities including custom module shapes, color masks, embedded images, and various drawing patterns.
145

146
```python { .api }
147
class StyledPilImage:
148
    """Styled PIL image with custom module drawers and color masks."""
149

150
class SquareModuleDrawer:
151
    """Square module drawer."""
152

153
class CircleModuleDrawer:
154
    """Circular module drawer."""
155

156
class QRColorMask:
157
    """Base class for color masking."""
158
```
159

160
[Styling and Customization](./styling.md)
161

162
## Utility Functions
163

164
```python { .api }
165
def run_example(data="http://www.lincolnloop.com", *args, **kwargs):
166
    """
167
    Build and display an example QR Code for demonstration purposes.
168
    
169
    Parameters:
170
    - data (str): Data to encode (default: demo URL)
171
    - *args, **kwargs: Arguments passed to QRCode constructor
172
    
173
    Notes:
174
    - Creates QRCode instance, adds data, generates image, and displays it
175
    - Mainly for testing and demonstration purposes
176
    """
177
```
178

179
## Types
180

181
```python { .api }
182
class DataOverflowError(Exception):
183
    """Raised when data exceeds QR code capacity."""
184

185
class ActiveWithNeighbors:
186
    """
187
    Named tuple containing module state with 3x3 neighborhood information.
188
    
189
    Attributes:
190
    - NW, N, NE: Northwest, North, Northeast neighbors (bool)
191
    - W, me, E: West, current module, East (bool)  
192
    - SW, S, SE: Southwest, South, Southeast neighbors (bool)
193
    
194
    Notes:
195
    - Used by advanced module drawers for context-aware rendering
196
    - Boolean evaluation returns the 'me' attribute value
197
    """
198
    NW: bool
199
    N: bool  
200
    NE: bool
201
    W: bool
202
    me: bool
203
    E: bool
204
    SW: bool
205
    S: bool
206
    SE: bool
207

208
# Type aliases for image factory parameters
209
from typing import Optional, Type, Union, Any, Dict, List
210
from qrcode.image.base import BaseImage
211

212
# Module matrix type
213
ModulesType = List[List[Optional[bool]]]
214
```