0 dní v řadě · 0 bodů

Profesionální vývoj · 35 min

Ruff, mypy a pre-commit

Necháš stroj hlídat chyby, styl i typy. Ruff, mypy a pre-commit zachytí problém dřív, než kód opustí tvůj počítač.

Hloubka
Úkoly
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"))
Výstup
['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ástrojCo děláCo najde
Linter (ruff check)čte kód a hledá podezřelé vzorynepoužité importy, pasti, zastaralé zápisy
Formátovač (ruff format)přepíše kód do jednotné podobymezery, 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 commitemzapomně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))
Výstup
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}")
Výstup
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.

Úkol

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 []
Výstup

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í.

bash
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í pravidlo

Na 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):

text
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.

toml
[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-exportu

Vž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á.

SadaOdkud pocházíCo hlídá
FPyflakesnepoužité importy, nedefinovaná jména
E, Wpycodestylestyl podle PEP 8
Iisortpořadí importů
UPpyupgradezastaralé zápisy, třeba List[int] místo list[int]
Bflake8-bugbearpravděpodobné chyby v logice
SIMflake8-simplifykód, který jde napsat jednodušeji
C4flake8-comprehensionszbytečně složité comprehensions
Sflake8-banditbezpečnostní rizika
RUFvlastní pravidla Ruffurů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.

diff
-def soucet( a,b ):
-    return a+b
+def soucet(a, b):
+    return a + b

Když je pravidlo v jednom místě opravdu zbytečné, vypni ho jen tam a řekni proč.

python
# Fiktivní hodnota, používá ji jen testovací databáze.
password = "tajne123"  # noqa: S105
Kvíz

Co udělá příkaz ruff format .?

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:

  1. Zapni F a E9, oprav je, slouč.
  2. Přidej další sadu v samostatném PR. Mechanické změny neslučuj s funkčními, jinak nejde dělat review.
  3. Hromadné formátování zapiš do .git-blame-ignore-revs, aby git blame zůstal použitelný.
  4. Na zbytek použij ruff check --add-noqa a pravidlem RUF100 pak 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__)
Výstup
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í.

bash
python -m pip install mypy
mypy opakovani.py
text
opakovani.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)
Výstup
Eva

mypy nepotřebuje, aby ta situace nastala. Stačí mu návratový typ.

text
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))
Výstup
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))
Výstup
připravujeme
text
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.

toml
[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 = true
Úkol

Malá 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 []
Výstup
Kvíz

Co se stane, když zavoláš funkci s anotací x: int a předáš text, a mypy jsi nespustil?

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)
Výstup
[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 = true je past, dávej ho jen do overrides pro konkrétní modul.
  • # type: ignore piš vždy s kódem: # type: ignore[arg-type]. S warn_unused_ignores (je ve strict) se ozve, až výjimka přestane být potřeba.
  • reveal_type(x) ti při kontrole vypíše, co si o x ná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:

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.

bash
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))
Výstup
  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.

Úkol

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
Výstup
Kvíz

Hook ruff-format při commitu upravil soubor a commit skončil neúspěchem. Co uděláš?

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:

yaml
repos:
  - repo: local
    hooks:
      - id: mypy
        name: mypy
        entry: mypy
        language: system
        types: [python]
        pass_filenames: false

pass_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].