1pyqrcode
2================================
3
4The pyqrcode module is a QR code generator that is simple to use and written
5in pure python. The module can automates most of the building process for
6creating QR codes. Most codes can be created using only two lines of code!
7
8Unlike other generators, all of the helpers can be controlled manually. You are
9free to set any or all of the properties of your QR code.
10
11QR codes can be saved as SVG, XBM, EPS, PNG (by using the
12[pypng](https://pypi.python.org/pypi/pypng/) module), or plain text. They can
13also be displayed directly in most Linux terminal emulators and Tkinter. PIL
14is not used to render the image files.
15
16The pyqrcode module attempts to follow the QR code standard as closely as
17possible. The terminology and the encodings used in pyqrcode come directly
18from the standard. This module also follows the algorithm laid out in the
19standard.
20
21Requirements
22-------------------------
23
24The pyqrcode module only requires Python 2.6, Python 2.7, or Python 3. You may
25want to install pypng in order to render PNG files, but it is optional.
26
27Installation
28------------
29
30Installation is simple. It can be installed from pip using the following
31command:
32
33```bash
34$ pip install pyqrcode
35```
36
37Or from the code
38
39```bash
40$ python setup.py install
41```
42
43Usage
44-----
45
46This is the only import you need. The heart of the module is the QRCode class.
47You can construct the class normally, or use the *create* wrapper function.
48
49```python
50>>> import pyqrcode
51>>> qr = pyqrcode.create('Unladden swallow')
52>>> qr.png('famous-joke.png', scale=5)
53```
54
55PyPi
56----
57
58* _PyPi page_: https://pypi.python.org/pypi?name=PyQRCode&:action=display
59
60* _Documentation_: http://pythonhosted.org/PyQRCode/
61
62### Encoding Data ###
63
64This module supports all four encodings for data: numeric, alphanumeric, kanji,
65and binary.
66
67The numeric type is the most efficient way to encode digits. As the
68name implies it is designed to encode integers. Some numbers might be two
69large, the object can use a string containing only digits instead of an
70actual number.
71
72```python
73>>> number = pyqrcode.create(123456789012345)
74````
75
76The alphanumeric type is very limited in that it can only encode some ASCII
77characters. It encodes: uppercase letters, 0-9, the horizontal space, and eight
78punctuation characters. The available characters will let you encode a URL
79
80```python
81>>> url = pyqrcode.create('http://uca.edu')
82```
83
84When all else fails the data can be encoded in pure binary. The quotation below
85must be encoded in binary because of the lower-cased characters, the apostrophe
86and the new line character.
87
88```python
89>>> life = pyqrcode.create('''MR. CREOSOTE: Better get a bucket. I'm going to throw up.
90    MAITRE D: Uh, Gaston! A bucket for monsieur. There you are, monsieur.''')
91```
92The only unimplemented encoding is ECI mode which allows for multiple encodings in one QR
93code (this will be implemented in a future version).
94
95### Manually Setting The QR Code's Properties ###
96
97There are many situation where you might wish to have more fine grained control
98over how the QR Code is generated. You can specify all the properties of your
99QR code through the *create* function. There are three main properties to a
100QR code.
101
102The _error_ parameter sets the error correction level of the code. Each level
103has an associated name given by a letter: L, M, Q, or H; each level can
104correct up to 7, 15, 25, or 30 percent of the data respectively. There are
105several ways to specify the level, see pyqrcode.tables.modes for all the
106possible values. By default this parameter is set to 'H' which is the highest
107possible error correction, but it has the smallest available data
108capacity.
109
110The _version_ parameter specifies the size and data capacity of the
111code. Versions are any integer between 1 and 40, where version 1 is
112the smallest QR code, and version 40 is the largest. By default, the object
113uses the data's encoding and error correction level to calculate the smallest
114possible version. You may want to specify this parameter for consistency when
115generating several QR codes with varying amounts of data. That way all of the
116generated codes would have the same size.
117
118Finally, the _mode_ parameter sets how the contents will be encoded. As
119mentioned above, three of the five possible encodings have been written. By
120default the object uses the most efficient encoding for the contents. You can
121change this though. See qrcode.tables.modes for a list of possible values
122for this parameter.
123
124The code below constructs a QR code with 25% error correction, size 27, and
125forces the encoding to be binary (rather than numeric).
126
127```python
128>>> big_code = pyqrcode.create('0987654321', error='L', version=27, mode='binary')
129```
130
131### Rendering ###
132
133There are many possible formats for rendering the QR Code. The first is
134to render it as a string of 1's and 0's. This is method is used to help end
135users create their own renderer. It is also possible to print the
136code such that it is directly displayable in most Linux terminals.
137There are several image based renderers.
138
139The terminal renderer outputs a string of ASCII escape codes that when
140displayed in a compatible terminal, will display a valid QR code. The
141background and module colors are settable (although as with any time you display
142colors in the terminal, there are several caveats).
143
144```python
145>>> print(url.terminal())
146>>> print(url.terminal('red', 'white'))
147```
148
149The SVG renderer outputs the QR Code as a scalable vector graphic. This
150renderer does not require any external modules. Instead it hand draws the
151QR code as a set paths.
152
153```python
154>>> url.svg(sys.stdout, scale=1)
155>>> url.svg('uca.svg', scale=4, module_color="#7D007D")
156```
157
158Alternatively, if you install the pypng module, you can render the QR Code
159to a PNG file. Colors should be specified as RGB or RGBA if you want to
160take advantage of transparency.
161
162```python
163>>> number.png('big-number.png')
164>>> life.png('sketch.png', scale=6, module_color=(0, 0, 0, 128), background=(0xff, 0xff, 0xcc))
165```
166
167Finally, there is a text based renderer. This will output the QR code as a
168string of 1's and 0's, with each row of the code on a new line.
169
170```python
171>>> print(number.text())
172```
173