0 dní v řadě · 0 bodů

Užitečné knihovny · 24 min

qrcode: vlastní QR kódy

Vyrobíš QR kód na web, Wi-Fi i platbu, pochopíš verze a odolnost proti poškození a kód prozkoumáš jako obyčejnou mřížku.

Hloubka
Úkoly
Lidsky řečeno

QR kód je vzkaz napsaný čtverečky. Telefon ho vyfotí, podle tří velkých rohů pozná, jak je otočený, a čtverečky přeloží zpátky na text. Část z nich přitom nenese vzkaz, ale jeho zálohu. Je to jako když kamarádovi nadiktuješ číslo a pro jistotu ho zopakuješ: i když něco přeslechne, zpráva dorazí. Proto se dá přečíst i poškrábaná nálepka na sloupu.

Instalace a první kód

Balíček se jmenuje qrcode. Aby uměl ukládat obrázky, potřebuje knihovnu Pillow, kterou si vyžádáš dodatkem v hranatých závorkách:

bash
python -m pip install "qrcode[pil]"

Uvozovky jsou tu kvůli některým terminálům, kterým hranaté závorky vadí. Doma pak stačí dva řádky a na disku máš hotový obrázek:

python
import qrcode

obrazek = qrcode.make("https://example.com")
obrazek.save("web.png")

V prohlížeči si kód vypíšeme jako text. Delší zápis přes třídu QRCode dává nad výsledkem kontrolu a postup je pořád stejný: vytvoř, vlož data, sestav, vypiš.

import qrcode

qr = qrcode.QRCode(border=1)
qr.add_data("Ahoj")
qr.make()
qr.print_ascii()
Výstup
 ▄▄▄▄▄▄▄    ▄  ▄▄▄▄▄▄▄
 █ ▄▄▄ █ █▄ ▄▀ █ ▄▄▄ █
 █ ███ █ ▀▄▀██ █ ███ █
 █▄▄▄▄▄█ ▄▀▄ █ █▄▄▄▄▄█
 ▄     ▄ █▀█▀█▄▄  ▄▄▄
 ▄ █▀▀▄▄█▀▀ ▄▀▄▀ █ ▄▄
 ▀  ▄▀▀▄▀ ▄▀   ▄ ▀█▀█▄
 ▄▄▄▄▄▄▄ ▀ █▀█▀██ █ ▄
 █ ▄▄▄ █  █▄▀█▀ █▀▀▀▄▀
 █ ███ █  ▄▄ ▀ ▄  ▄ ▄▄
 █▄▄▄▄▄█ ▄  ▄ ▄  █ █▄

Metoda print_ascii skládá kód z půlených znaků, takže se do jednoho řádku vejdou dva řádky čtverečků. V terminálu s tmavým pozadím vyjde kód opačně, tedy světlý na tmavém. Tomu pomůže print_ascii(invert=True).

Hlavní parametry třídy QRCode:

ParametrCo děláVýchozí hodnota
versionvelikost mřížky, 1 až 40None, určí se podle dat
error_correctionjak moc je kód odolný proti poškozeníERROR_CORRECT_M
box_sizekolik pixelů má jeden čtvereček v obrázku10
borderšířka bílého okraje ve čtverečcích4

Kód je jen mřížka

Jednomu čtverečku se říká modul. Po zavolání make() máš všechny moduly v qr.modules. Je to seznam řádků a každý řádek je seznam hodnot True (tmavý) a False (světlý).

import qrcode

qr = qrcode.QRCode()
qr.add_data("Ahoj")
qr.make()

print("verze:", qr.version)
print("modulů na stranu:", qr.modules_count)
print("řádků v mřížce:", len(qr.modules))

for radek in qr.modules[:8]:
    print("".join("##" if modul else ".." for modul in radek[:8]))
Výstup
verze: 1
modulů na stranu: 21
řádků v mřížce: 21
##############..
##..........##..
##..######..##..
##..######..##..
##..######..##..
##..........##..
##############..
................

Těch osm řádků je levý horní roh. Vidíš v něm hledací čtverec, tmavý rámeček s tmavým jádrem. Stejný je vpravo nahoře a vlevo dole. Právě podle těchto tří rohů telefon pozná polohu a natočení kódu. Čtvrtý roh zůstává volný, a tak je jasné, kde je nahoře.

Velikost mřížky je daná jednoduchým vzorcem:

text
moduly na stranu = 17 + 4 × verze
pixely obrázku   = (moduly na stranu + 2 × border) × box_size

Verze 1 má tedy 21 modulů na stranu, verze 40 jich má 177. qr.modules okraj neobsahuje. Když ho chceš, použij qr.get_matrix().

import qrcode

qr = qrcode.QRCode(border=2)
qr.add_data("Ahoj")
qr.make()

mrizka = qr.get_matrix()
print(len(mrizka) - len(qr.modules))
print(any(mrizka[0]))
Výstup
4
False

Mřížka je o dvojnásobek okraje vyšší, protože okraj je nahoře i dole. Její horní řádek je celý světlý, proto any vrátí False.

Úkol

Spočítej velikost obrázku

Napiš funkci pixely(verze, box_size=10, border=4), která vrátí šířku výsledného obrázku v pixelech. Vzorec je o kousek výš.

def pixely(verze, box_size=10, border=4):
    return 0
Výstup
Úkol

Nakresli mřížku

Napiš funkci nakresli(mrizka), která dostane seznam řádků s hodnotami True a False a vrátí jeden text. Tmavý modul je ##, světlý jsou dvě mezery, řádky odděl znakem nového řádku. Dva znaky na modul jsou tu proto, že znak v terminálu bývá zhruba dvakrát vyšší než široký a kód by jinak vyšel protáhlý.

def nakresli(mrizka):
    return ""
Výstup

Kolik se toho vejde

Čím víc dat, tím větší mřížka. Automatický výběr verze zajišťuje make(fit=True), což je výchozí chování. O velikosti ale rozhoduje ještě úroveň opravy chyb.

KonstantaObnoví přibližněKdy ji použít
ERROR_CORRECT_L7 % poškozených datčistý tisk, co nejmenší kód
ERROR_CORRECT_M15 %běžná volba
ERROR_CORRECT_Q25 %venku, na obalech
ERROR_CORRECT_H30 %hrubé prostředí nebo logo uprostřed

Vyšší odolnost není zadarmo. Záloha zabere místo, takže stejný text potřebuje větší mřížku.

import qrcode
from qrcode.constants import (
    ERROR_CORRECT_H, ERROR_CORRECT_L, ERROR_CORRECT_M, ERROR_CORRECT_Q,
)

adresa = "https://example.com/akce/jarni-slevy"
urovne = {"L": ERROR_CORRECT_L, "M": ERROR_CORRECT_M, "Q": ERROR_CORRECT_Q, "H": ERROR_CORRECT_H}

for nazev, uroven in urovne.items():
    qr = qrcode.QRCode(error_correction=uroven)
    qr.add_data(adresa)
    qr.make(fit=True)
    print(nazev, "verze", qr.version, "strana", qr.modules_count)
Výstup
L verze 3 strana 29
M verze 3 strana 29
Q verze 4 strana 33
H verze 5 strana 37

Záleží i na tom, jaké znaky kóduješ. QR má úsporné režimy: čísla se ukládají nejhustěji, potom velká písmena s několika symboly a nejvíc místa stojí obecné bajty. Tři texty stejné délky proto dopadnou různě:

import qrcode

texty = {
    "číslice": "1234567890" * 3,
    "velká písmena": "ABCDEFGHIJ" * 3,
    "malá písmena": "abcdefghij" * 3,
}

for nazev, text in texty.items():
    qr = qrcode.QRCode()
    qr.add_data(text)
    qr.make()
    print(f"{nazev}: {len(text)} znaků, verze {qr.version}")
Výstup
číslice: 30 znaků, verze 1
velká písmena: 30 znaků, verze 2
malá písmena: 30 znaků, verze 3

Česká písmena stojí ještě víc. Ukládají se v kódování UTF-8, kde č zabere dva bajty.

for text in ["cesta", "česta", "žluťoučký"]:
    print(text, "znaků:", len(text), "bajtů:", len(text.encode("utf-8")))
Výstup
cesta znaků: 5 bajtů: 5
česta znaků: 5 bajtů: 6
žluťoučký znaků: 9 bajtů: 13

Když verzi pevně nastavíš a vypneš přizpůsobení, příliš dlouhý text skončí výjimkou.

import qrcode
from qrcode.exceptions import DataOverflowError

qr = qrcode.QRCode(version=1)
qr.add_data("x" * 100)

try:
    qr.make(fit=False)
except DataOverflowError:
    print("Do verze 1 se to nevejde.")
Výstup
Do verze 1 se to nevejde.
Kvíz

Máš dlouhou adresu a kód na letáku je tak hustý, že ho starší telefony nepřečtou. Co pomůže nejvíc?

Kvíz

Kolik modulů na stranu má QR kód verze 3?

Úkol

Kód na plot

Vytvoř objekt qr s textem https://example.com/plot, s nejvyšší úrovní opravy chyb a okrajem 4. Kód sestav přes make.

import qrcode
from qrcode.constants import ERROR_CORRECT_H

qr = qrcode.QRCode()
qr.add_data("https://example.com/plot")
Výstup
Úkol

Kolik je tmy

Sestav kód z textu sudo_uceni a do proměnné podil ulož, jaká část modulů v qr.modules je tmavá, jako číslo od 0 do 1.

import qrcode

qr = qrcode.QRCode()
qr.add_data("sudo_uceni")
qr.make()

podil = 0
Výstup

Co do kódu napsat

QR kód nese jen text. Že telefon nabídne připojení k Wi-Fi nebo platbu, zařídí domluvený formát toho textu.

ÚčelObsah
webhttps://example.com
e-mailmailto:[email protected]
telefontel:+420123456789
Wi-FiWIFI:T:WPA;S:Kavarna;P:tajneheslo;;
česká platbaSPD*1.0*ACC:CZ...*AM:450.00*CC:CZK

U Wi-Fi mají znaky ;, :, ,, " a \ zvláštní význam, takže se v názvu i hesle musí uvodit zpětným lomítkem. Záleží na pořadí: zpětné lomítko se nahrazuje první, jinak bys zdvojil i ta, která jsi právě přidal.

def chran(text):
    for znak in ["\\", ";", ",", ":", '"']:
        text = text.replace(znak, "\\" + znak)
    return text

print(chran("Kavárna: host"))
print(chran("a;b\\c"))
Výstup
Kavárna\: host
a\;b\\c
Úkol

Wi-Fi pro hosty

Napiš funkci wifi_text(nazev, heslo), která vrátí text ve tvaru WIFI:T:WPA;S:nazev;P:heslo;;. V názvu i hesle uveď zvláštní znaky zpětným lomítkem.

def chran(text):
    for znak in ["\\", ";", ",", ":", '"']:
        text = text.replace(znak, "\\" + znak)
    return text

def wifi_text(nazev, heslo):
    return f"WIFI:T:WPA;S:{nazev};P:{heslo}"
Výstup

České bankovní aplikace umějí načíst QR platbu. Jde o formát SPD: hlavička SPD*1.0 a pole oddělená hvězdičkou. Účet se zadává jako IBAN, částka má tečku a dvě desetinná místa. Text zprávy se běžně píše velkými písmeny bez diakritiky, což je zároveň úsporný režim QR kódu.

import unicodedata

def bez_diakritiky(text):
    rozlozeny = unicodedata.normalize("NFKD", text)
    return rozlozeny.encode("ascii", "ignore").decode("ascii")

print(bez_diakritiky("Záloha na účet").upper())
print(f"{450:.2f}", f"{1299.5:.2f}")
Výstup
ZALOHA NA UCET
450.00 1299.50
Úkol

QR platba

Napiš funkci platba(iban, castka, zprava), která vrátí text SPD*1.0*ACC:<iban>*AM:<castka>*CC:CZK*MSG:<zprava>. Částka má dvě desetinná místa s tečkou. Zpráva je velkými písmeny, bez diakritiky a případné hvězdičky v ní nahraď mezerou, protože hvězdička odděluje pole.

import unicodedata

def bez_diakritiky(text):
    rozlozeny = unicodedata.normalize("NFKD", text)
    return rozlozeny.encode("ascii", "ignore").decode("ascii")

def platba(iban, castka, zprava):
    return f"SPD*1.0*ACC:{iban}*AM:{castka}*CC:CZK*MSG:{zprava}"
Výstup

Uložení do souboru

Na vlastním počítači vznikne obrázek metodou make_image. Barvy nastavíš, ale drž se tmavého kódu na světlém pozadí a výrazného kontrastu. Obrácené varianty některé čtečky nezvládnou.

python
import qrcode
import qrcode.image.svg
from qrcode.constants import ERROR_CORRECT_Q

qr = qrcode.QRCode(error_correction=ERROR_CORRECT_Q, box_size=12)
qr.add_data("https://example.com")
qr.make()

png = qr.make_image(fill_color="black", back_color="white")
png.save("kod.png")

svg = qr.make_image(image_factory=qrcode.image.svg.SvgPathImage)
svg.save("kod.svg")

Pro tisk je nejlepší SVG. Je to vektor, takže zůstane ostrý v jakékoli velikosti. Pro víc kódů stačí cyklus:

python
from pathlib import Path
import qrcode

folder = Path("vstupenky")
folder.mkdir(exist_ok=True)

for number in range(1, 51):
    image = qrcode.make(f"https://example.com/vstupenka/{number:03}")
    image.save(folder / f"vstupenka-{number:03}.png")

Balíček přidává i příkaz do terminálu: qr "Ahoj" vypíše kód rovnou na obrazovku.

Pod kapotou · co se děje uvnitř a na co dát pozor

Oprava chyb používá Reed-Solomonovy kódy nad GF(256). Data se u vyšších verzí dělí do bloků a jejich bajty se prokládají, takže souvislé poškození (škrábanec, logo) se rozloží mezi víc bloků. Procenta u L, M, Q, H jsou proto orientační horní mez pro obnovitelná kódová slova, ne záruka pro libovolnou část plochy. Logo přes hledací čtverce kód zničí i na úrovni H.

Maska. Data se XORují jedním z osmi vzorů, aby v kódu nevznikaly dlouhé stejnobarevné úseky a falešné hledací čtverce. Knihovna zkusí všech osm, ohodnotí je penalizačními pravidly a vybere nejlepší. Při hromadném generování ušetříš čas pevným mask_pattern=0 až 7, za cenu možná horší čitelnosti.

Režimy. add_data(text, optimize=20) hledá úseky aspoň 20 číslic nebo znaků z alfanumerické sady a kóduje je úsporně. Každý úsek ale stojí hlavičku, proto práh nejde bezhlavě snižovat. Hodnota optimize=0 celý vstup zakóduje jediným režimem. Bajtový režim zde nese UTF-8 bez značky ECI. Běžné čtečky si s tím poradí, přesto text s diakritikou na starých skenerech otestuj.

Velká písmena v URL. Schéma a doménu lze psát velkými písmeny, a dostat se tak do alfanumerického režimu, cesta ale bývá citlivá na velikost písmen. HTTPS://EXAMPLE.COM/A1 je úsporné, jen když server tuhle cestu opravdu zná.

Bezpečnost. Člověk obsah kódu nepřečte, a tak se kódy zneužívají k phishingu, třeba nálepkou přes originál na parkovacím automatu. Tiskni doménu i vedle kódu. Do QR pro Wi-Fi patří jen síť pro hosty, protože heslo je v něm jako čistý text. Když se cíl může změnit, zakóduj vlastní krátkou adresu s přesměrováním, ne přímo konečnou stránku.

QR platba. U IBAN si můžeš ověřit kontrolní číslice: první čtyři znaky přesuň na konec, písmena nahraď čísly (A=10 ... Z=35) a výsledek modulo 97 musí dát 1. Odhalí překlepy dřív, než se kód vytiskne na tisíc faktur.