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