Lidsky řečeno
Než kniha vyjde, projde několika rukama. Korektor hledá překlepy. Sazeč sjednotí vzhled, aby každá stránka vypadala stejně. Redaktor si všimne, že hrdina měl v první kapitole modré oči a v páté hnědé. A tiskárna nepřijme rukopis bez razítka. U kódu tyhle role dělají programy: linter je korektor, formátovač sazeč, typová kontrola redaktor a pre-commit vrátný u tiskárny.
Chyby, které testem neprojdou
Následující program běží bez jediné chyby. Přesto v něm jsou dva zbytečné importy a jedna opravdová past.
import json
import os
def pridej_do_kosiku(polozka, kosik=[]):
kosik.append(polozka)
return kosik
print(pridej_do_kosiku("chleba"))
print(pridej_do_kosiku("máslo"))
['chleba'] ['chleba', 'máslo']
Druhý zákazník dostal i chleba prvního zákazníka. Výchozí seznam vznikne jednou, při definici funkce, a všechna volání ho sdílejí. Tuhle chybu nemusíš hledat v noci v logu. Nástroj ji najde za zlomek sekundy, aniž by program spustil.
Profesionální projekt obvykle používá čtyři vrstvy:
| Nástroj | Co dělá | Co najde |
|---|---|---|
Linter (ruff check) | čte kód a hledá podezřelé vzory | nepoužité importy, pasti, zastaralé zápisy |
Formátovač (ruff format) | přepíše kód do jednotné podoby | mezery, závorky, délku řádků |
Typová kontrola (mypy) | ověří, že typy k sobě sedí | None tam, kde čekáš objekt, špatné argumenty |
Hook (pre-commit) | spustí to všechno před commitem | zapomnětlivost |
Žádný z nich nenahrazuje testy z lekce Testování. Testy ověřují, že program dělá správnou věc. Tyhle nástroje levně vyřadí celé skupiny chyb, na které bys testy psát nechtěl.
Jak linter vidí kód
Linter kód nespouští. Přečte ho a převede na strom, kterému se říká AST (abstract syntax tree, abstraktní syntaktický strom). Každý uzel je jeden kousek programu: přiřazení, volání funkce, číslo. Python má pro tohle vestavěný modul ast.
import ast
strom = ast.parse("cena = 100 * pocet")
print(ast.dump(strom.body[0], indent=2))
Assign(
targets=[
Name(id='cena', ctx=Store())],
value=BinOp(
left=Constant(value=100),
op=Mult(),
right=Name(id='pocet', ctx=Load())))Když máš strom, stačí v něm hledat vzory. Tady je malý linter, který umí čtyři pravidla. Kódy pravidel jsou stejné, jaké používá Ruff.
import ast
KOD = """
import json
import os
def pridej(polozka, kosik=[]):
try:
kosik.append(polozka)
except:
pass
if polozka == None:
print(os.getcwd())
return kosik
"""
class MiniLinter(ast.NodeVisitor):
def __init__(self):
self.importy = {}
self.pouzita_jmena = set()
self.nalezy = []
def nahlas(self, uzel, kod, zprava):
self.nalezy.append((uzel.lineno, uzel.col_offset + 1, kod, zprava))
def visit_Import(self, uzel):
for alias in uzel.names:
jmeno = alias.asname or alias.name.split(".")[0]
self.importy[jmeno] = uzel
def visit_Name(self, uzel):
self.pouzita_jmena.add(uzel.id)
def visit_FunctionDef(self, uzel):
for vychozi in uzel.args.defaults + uzel.args.kw_defaults:
if isinstance(vychozi, (ast.List, ast.Dict, ast.Set)):
self.nahlas(vychozi, "B006", "měnitelná výchozí hodnota")
self.generic_visit(uzel)
def visit_ExceptHandler(self, uzel):
if uzel.type is None:
self.nahlas(uzel, "E722", "holé except chytá úplně všechno")
self.generic_visit(uzel)
def visit_Compare(self, uzel):
for operator, vpravo in zip(uzel.ops, uzel.comparators):
je_none = isinstance(vpravo, ast.Constant) and vpravo.value is None
if je_none and isinstance(operator, (ast.Eq, ast.NotEq)):
self.nahlas(uzel, "E711", "s None porovnávej přes is")
self.generic_visit(uzel)
def vysledek(self):
for jmeno, uzel in self.importy.items():
if jmeno not in self.pouzita_jmena:
self.nahlas(uzel, "F401", f"import {jmeno} se nepoužívá")
return sorted(self.nalezy)
linter = MiniLinter()
linter.visit(ast.parse(KOD))
for radek, sloupec, kod, zprava in linter.vysledek():
print(f"{radek}:{sloupec}: {kod} {zprava}")
2:1: F401 import json se nepoužívá 5:27: B006 měnitelná výchozí hodnota 8:5: E722 holé except chytá úplně všechno 10:8: E711 s None porovnávej přes is
os linter nenahlásil, protože ho funkce opravdu používá. A všimni si, že print(os.getcwd()) se nikdy neprovedl. Celá analýza proběhla nad textem.
Pravidlo proti zapomenutým printům
Napiš funkci najdi_print(kod), která vrátí seřazený seznam čísel řádků, na kterých se volá vestavěný print(...). Slovo print v komentáři nebo v textu se nepočítá a stejně tak metoda tiskarna.print(...).
import ast
def najdi_print(kod):
strom = ast.parse(kod)
# projdi strom a hledej volání funkce se jménem print
return []
Ruff: kontrola a formátování
Ruff je linter a formátovač v jednom. Je napsaný v Rustu a nahrazuje dřívější sestavu nástrojů Flake8, isort, pyupgrade a Black. Instaluje se jako vývojová závislost do virtuálního prostředí z lekce Virtuální prostředí.
python -m pip install ruff
ruff check . # najdi problémy
ruff check . --fix # oprav ty, které jdou opravit bezpečně
ruff format . # přeformátuj kód
ruff format . --check # jen ověř, nic neměň (pro CI)
ruff rule B006 # vysvětli konkrétní pravidloNa první ukázce z téhle lekce by Ruff se zapnutou sadou B hlásil tohle (stručný výstup přes --output-format=concise):
kosik.py:1:8: F401 [*] `json` imported but unused
kosik.py:2:8: F401 [*] `os` imported but unused
kosik.py:4:37: B006 Do not use mutable data structures for argument defaults
Found 3 errors.Hvězdička [*] značí, že oprava je bezpečná a provede ji --fix. Nastavení patří do pyproject.toml, o kterém mluví lekce Struktura projektu.
[tool.ruff]
line-length = 88
target-version = "py312"
src = ["src", "tests"]
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM", "C4", "S", "RUF"]
ignore = ["E501"] # délku řádků řeší formátovač
[tool.ruff.lint.per-file-ignores]
"tests/**" = ["S101"] # v testech je assert v pořádku
"__init__.py" = ["F401"] # importy tu slouží k re-exportuVždy uveď select výslovně. Výchozí sada pravidel je úzká a takhle je v repozitáři vidět, co přesně se hlídá.
| Sada | Odkud pochází | Co hlídá |
|---|---|---|
F | Pyflakes | nepoužité importy, nedefinovaná jména |
E, W | pycodestyle | styl podle PEP 8 |
I | isort | pořadí importů |
UP | pyupgrade | zastaralé zápisy, třeba List[int] místo list[int] |
B | flake8-bugbear | pravděpodobné chyby v logice |
SIM | flake8-simplify | kód, který jde napsat jednodušeji |
C4 | flake8-comprehensions | zbytečně složité comprehensions |
S | flake8-bandit | bezpečnostní rizika |
RUF | vlastní pravidla Ruffu | různé, včetně zbytečných noqa |
Formátovač se o správnost nestará, jen o vzhled. Výsledek je vždy stejný, takže v code review odpadnou debaty o mezerách.
-def soucet( a,b ):
- return a+b
+def soucet(a, b):
+ return a + bKdyž je pravidlo v jednom místě opravdu zbytečné, vypni ho jen tam a řekni proč.
# Fiktivní hodnota, používá ji jen testovací databáze.
password = "tajne123" # noqa: S105Co udělá příkaz ruff format .?
Formátovač řeší jen podobu kódu. Nepoužité importy a jejich pořadí patří linteru, tedy ruff check.
Pod kapotou · Ruff v existujícím projektu
Rychlost pochází z Rustu, z jednoho průchodu nad společným AST pro všechna pravidla a z cache v .ruff_cache. Cena za to je omezený pohled: Ruff pracuje hlavně v rámci jednotlivých souborů a neodvozuje typy. Na hlubší analýzu přes moduly je dál potřeba typová kontrola.
Opravy mají dvě úrovně. --fix provede jen bezpečné, --unsafe-fixes i ty, které mohou změnit chování. Oprava B006 je nebezpečná právem: někdo se na sdílený seznam mohl (nešťastně) spolehnout.
Velký starý projekt nezavírej na týden do jedné obří opravy. Použitelný postup:
- Zapni
FaE9, oprav je, slouč. - Přidej další sadu v samostatném PR. Mechanické změny neslučuj s funkčními, jinak nejde dělat review.
- Hromadné formátování zapiš do
.git-blame-ignore-revs, abygit blamezůstal použitelný. - Na zbytek použij
ruff check --add-noqaa pravidlemRUF100pak hlídej, aby výjimky mizely spolu s problémem.
Verzi Ruffu připni přesně. Nová verze může přidat pravidla do existující sady a formátovač jednou za čas mění styl, takže by se ti CI rozbilo bez jediné změny v kódu.
mypy: redaktor přes typy
Typové anotace z lekce Docstringy a typy Python za běhu nekontroluje. Uloží je a dál si jich nevšímá.
def opakuj(text: str, kolikrat: int) -> str:
return text * kolikrat
print(opakuj("ha", 3))
print(opakuj(3, 4))
print(opakuj.__annotations__)
hahaha
12
{'text': <class 'str'>, 'kolikrat': <class 'int'>, 'return': <class 'str'>}Volání opakuj(3, 4) vrátilo číslo 12, ačkoli funkce slibuje text. Žádná chyba, žádné varování. Hodnota poputuje programem dál a spadne někde úplně jinde. mypy soubor přečte, ověří, že typy sedí, a kód přitom nespustí.
python -m pip install mypy
mypy opakovani.pyopakovani.py:5: error: Argument 1 to "opakuj" has incompatible type "int"; expected "str" [arg-type]
Found 1 error in 1 file (checked 1 source file)Nejcennější úlovek typové kontroly je None. Funkce, která něco hledá, často nemusí nic najít. Za běhu na to přijdeš až ve chvíli, kdy někdo zadá neexistující číslo.
from dataclasses import dataclass
@dataclass
class Zakaznik:
jmeno: str
ZAKAZNICI = {1: Zakaznik("Eva")}
def najdi(cislo: int) -> Zakaznik | None:
return ZAKAZNICI.get(cislo)
print(najdi(1).jmeno)
print(najdi(2).jmeno)
Eva
mypy nepotřebuje, aby ta situace nastala. Stačí mu návratový typ.
zakaznici.py:12: error: Item "None" of "Zakaznik | None" has no attribute "jmeno" [union-attr]
zakaznici.py:13: error: Item "None" of "Zakaznik | None" has no attribute "jmeno" [union-attr]Opravou je ověřit, že hodnota existuje. mypy podmínku pochopí a v další větvi už ví, že None to být nemůže. Tomu se říká zúžení typu (narrowing).
from dataclasses import dataclass
@dataclass
class Zakaznik:
jmeno: str
ZAKAZNICI = {1: Zakaznik("Eva")}
def najdi(cislo: int) -> Zakaznik | None:
return ZAKAZNICI.get(cislo)
def pozdrav(cislo: int) -> str:
zakaznik = najdi(cislo)
if zakaznik is None:
return "Ahoj, neznámý."
return f"Ahoj, {zakaznik.jmeno}."
print(pozdrav(1))
print(pozdrav(2))
Ahoj, Eva. Ahoj, neznámý.
Typy pomáhají i s větvením. Když přidáš nový stav a zapomeneš ho někde obsloužit, assert_never na to upozorní mypy předem a za běhu vyhodí chybu.
from enum import Enum
from typing import assert_never
class Stav(Enum):
NOVA = "nova"
ZAPLACENA = "zaplacena"
ZRUSENA = "zrusena"
def popis(stav: Stav) -> str:
match stav:
case Stav.NOVA:
return "čeká na platbu"
case Stav.ZAPLACENA:
return "připravujeme"
case _:
assert_never(stav)
print(popis(Stav.ZAPLACENA))
print(popis(Stav.ZRUSENA))
připravujeme
stavy.py:16: error: Argument 1 to "assert_never" has incompatible type "Literal[Stav.ZRUSENA]"; expected "Never" [arg-type]Nastavení opět patří do pyproject.toml. U nového projektu rovnou zapni strict.
[tool.mypy]
python_version = "3.12"
strict = true
files = ["src", "tests"]
warn_unreachable = true
enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
[[tool.mypy.overrides]]
module = "stary_kod.*" # dočasná výjimka pro nepřepsanou část
ignore_errors = trueMalá kontrola typů za běhu
Napiš funkci spatne_argumenty(funkce, **argumenty). Vrátí seznam jmen argumentů, jejichž hodnota neodpovídá anotaci funkce. Argumenty bez anotace přeskoč. Stačí jednoduché typy jako int, str a float.
from typing import get_type_hints
def spatne_argumenty(funkce, **argumenty):
typy = get_type_hints(funkce)
# porovnej každou hodnotu s anotací
return []
Co se stane, když zavoláš funkci s anotací x: int a předáš text, a mypy jsi nespustil?
Anotace jsou za běhu jen uložené informace v __annotations__. Kontrolu dělá až externí nástroj.
Pod kapotou · kde typová kontrola klame
Any se šíří potichu. Hodnota typu Any projde čímkoli a všechno z ní odvozené je také Any. Jeden nezatypovaný json.loads může vypnout kontrolu v celé větvi programu. Hranici systému proto ošetři validací a dál pracuj s konkrétním typem. object je opak: přijme cokoli, ale nedovolí nic bez zúžení.
list je invariantní. Vypadá to jako puntičkářství, dokud nevidíš důvod:
def pridej_polovinu(cisla: list[float]) -> None:
cisla.append(0.5)
cela: list[int] = [1, 2]
pridej_polovinu(cela) # mypy: list[int] není list[float]
print(cela)
[1, 2, 0.5]
Pokud funkce jen čte, napiš Sequence[float], ta je kovariantní a list[int] přijme. Obecně: na vstupu chtěj co nejobecnější protokol (Iterable, Mapping), na výstupu vracej konkrétní typ.
Další praktické věci:
- Knihovny bez typů hlásí
import-untyped. Hledej balík se stuby (types-requests, princip popisuje PEP 561). Globálníignore_missing_imports = trueje past, dávej ho jen dooverridespro konkrétní modul. # type: ignorepiš vždy s kódem:# type: ignore[arg-type]. Swarn_unused_ignores(je vestrict) se ozve, až výjimka přestane být potřeba.reveal_type(x)ti při kontrole vypíše, co si oxnástroj myslí. Je to nejrychlejší ladění typů.cast()za běhu nic neověřuje. Je to tvoje slovo proti slovu nástroje.- Importy jen pro typy dej pod
if TYPE_CHECKING:, vyhneš se tím kruhovým importům. - Pyright se liší: odvozuje návratové typy a kontroluje i nezatypovaná těla. Jeden projekt tak může v každém nástroji hlásit něco jiného, takže si vyber jeden jako závazný.
pre-commit: vrátný před commitem
Nástroje jsou k ničemu, když je zapomeneš spustit. Git umí před commitem spustit skript, kterému se říká hook. O commitech víc v lekci Git a práce v týmu. Program pre-commit tyhle skripty spravuje: nainstaluje nástroje v přesných verzích a pouští je jen na soubory, které jdou do commitu.
Konfigurace leží v kořeni projektu v souboru .pre-commit-config.yaml:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v6.0.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-merge-conflict
- id: check-added-large-files
- id: detect-private-key
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.14.0
hooks:
- id: ruff-check
args: [--fix]
- id: ruff-format
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.18.2
hooks:
- id: mypy
additional_dependencies: [pydantic]Čísla verzí jsou ukázková. Aktuální doplní pre-commit autoupdate.
python -m pip install pre-commit
pre-commit install # zapojí hook do tohoto repozitáře
pre-commit run --all-files # první kontrola celého projektu
pre-commit autoupdate # zvedne verze nástrojůJedna věc překvapí každého. Když hook soubor opraví, commit přesto selže. Oprava totiž ještě není v tom, co jsi chtěl commitnout, a ty ji máš vidět. Soubor znovu přidáš přes git add a commit zopakuješ. Rozhoduje jediná věc: návratový kód. Nula znamená pokračuj, cokoli jiného stop. Tady je celý princip v malém.
def serad_importy(text):
radky = text.split("\n")
importy = [r for r in radky if r.startswith("import ")]
ostatni = [r for r in radky if not r.startswith("import ")]
return "\n".join(sorted(importy) + ostatni), []
def zakaz_breakpoint(text):
chyby = [f"řádek {i}: zapomenutý breakpoint()"
for i, radek in enumerate(text.split("\n"), 1)
if "breakpoint()" in radek]
return text, chyby
HOOKY = {"seřazení importů": serad_importy, "zákaz breakpointu": zakaz_breakpoint}
def spust_hooky(soubory):
navratovy_kod = 0
for nazev, hook in HOOKY.items():
for cesta, obsah in soubory.items():
novy, chyby = hook(obsah)
if novy != obsah:
soubory[cesta] = novy
print(f" {nazev}: opraveno {cesta}")
navratovy_kod = 1
for chyba in chyby:
print(f" {nazev}: {cesta}, {chyba}")
navratovy_kod = 1
return navratovy_kod
soubory = {"app.py": "import os\nimport json\nx = 1", "ladeni.py": "y = 2\nbreakpoint()"}
print("kód:", spust_hooky(soubory))
print("kód:", spust_hooky(soubory))
soubory["ladeni.py"] = "y = 2"
print("kód:", spust_hooky(soubory))
seřazení importů: opraveno app.py zákaz breakpointu: ladeni.py, řádek 2: zapomenutý breakpoint() kód: 1 zákaz breakpointu: ladeni.py, řádek 2: zapomenutý breakpoint() kód: 1 kód: 0
První běh opravil importy a našel breakpoint(). Druhý už má jen problém, který musí vyřešit člověk. Třetí je čistý a commit by prošel.
Hook na konce řádků
Napiš funkci oprav_text(text), která se chová jako dvojice hooků trailing-whitespace a end-of-file-fixer:
- z konce každého řádku odstraní mezery a tabulátory,
- neprázdný soubor končí právě jedním znakem nového řádku,
- soubor bez obsahu je prázdný text.
Druhé použití už nesmí nic změnit.
def oprav_text(text):
return text
Hook ruff-format při commitu upravil soubor a commit skončil neúspěchem. Co uděláš?
Oprava je zatím jen v pracovní složce, ne v připravovaném commitu. Po git add projde druhý pokus bez problémů.
Pod kapotou · mypy v pre-commitu a co se děje při běhu
Každý hook běží ve vlastním izolovaném prostředí. U Ruffu to nevadí, u mypy ano: nevidí tvoje závislosti, takže typy z nich degradují na Any a kontrola je mělčí, než se zdá. Mirror navíc ve výchozím stavu předává --ignore-missing-imports, proto si toho nevšimneš. Máš dvě cesty. Buď závislosti vyjmenuješ v additional_dependencies a budeš je udržovat dvakrát, nebo použiješ lokální hook nad projektovým prostředím:
repos:
- repo: local
hooks:
- id: mypy
name: mypy
entry: mypy
language: system
types: [python]
pass_filenames: falsepass_filenames: false je důležité. mypy potřebuje vidět celý projekt, jinak změna podpisu funkce v jednom souboru neodhalí rozbitá volání v souborech, které do commitu nejdou. Pomalost řeší inkrementální cache v .mypy_cache a démon dmypy.
Před během pre-commit dočasně odloží nepřidané změny, aby nástroje viděly přesně to, co jde do commitu. Proto git add -p a částečné commity fungují správně. Pořadí hooků je daný kontrakt: ruff-check --fix patří před ruff-format, protože oprava může po sobě nechat kód, který je potřeba znovu naformátovat.
Hooky drž pod několika sekundami. Pomalý hook lidé obcházejí, a pak nechrání nic. Testy a těžkou analýzu nech v CI, případně je přesuň do fáze pre-push přes stages: [pre-push].