Lidsky řečeno
Ve spíži stojí krabice bez popisku. Je v ní sůl, nebo cukr? Zjistíš to až ochutnáním, možná rovnou v dortu. Docstring je návod nalepený na krabici: co v ní je a k čemu slouží. Typová anotace je štítek „jen sypké“. Nikdo ti nezabrání nalít dovnitř polévku, ale každý hned vidí, že je to špatně, a kontrolor si toho všimne dřív, než se něco stane.
Kód, kterému za měsíc nerozumíš
Tahle funkce funguje. Co dělá, je ale hádanka: co je d, v jakých je jednotkách k a co vrací?
def zpracuj(d, k=21):
return round(sum(d) * (1 + k / 100), 2)
print(zpracuj([100, 50]))
181.5
Stejný kód s dobrým jménem, typy a popisem nepotřebuje žádné čtení těla.
def cena_s_dph(ceny_bez_dph: list[float], sazba_procent: float = 21) -> float:
"""Vrátí součet cen včetně DPH, zaokrouhlený na haléře."""
return round(sum(ceny_bez_dph) * (1 + sazba_procent / 100), 2)
print(cena_s_dph([100, 50]))
print(cena_s_dph([100, 50], sazba_procent=12))
181.5 168.0
Chování je úplně stejné. Rozdíl je v tom, kolik musí příští čtenář zjišťovat. Tím čtenářem budeš nejčastěji ty.
Docstring: návod přímo ve funkci
Docstring je text v trojitých uvozovkách na úplně prvním řádku těla funkce. Není to komentář. Python ho uloží k funkci do atributu __doc__, takže je dostupný i za běhu.
def plocha_obdelniku(sirka, vyska):
"""Vrátí plochu obdélníku."""
return sirka * vyska
print(plocha_obdelniku.__doc__)
print(plocha_obdelniku.__name__)
Vrátí plochu obdélníku. plocha_obdelniku
Funkce help ho umí hezky zobrazit a čerpají z něj i editory. Když najedeš myší na název funkce, uvidíš právě docstring.
help(plocha_obdelniku)Delší docstring začíná jednou souhrnnou větou, následuje prázdný řádek a podrobnosti. Odsazení z kódu zůstává v __doc__, a proto se hodí inspect.getdoc, který ho odstraní.
import inspect
import math
def rozdel_ucet(castka, lidi, spropitne=0):
"""Rozdělí účet rovným dílem mezi lidi.
Args:
castka: Celková částka v korunách.
lidi: Počet platících, aspoň 1.
spropitne: Spropitné v procentech z částky.
Returns:
Částka na osobu zaokrouhlená na koruny nahoru.
"""
celkem = castka * (1 + spropitne / 100)
return math.ceil(celkem / lidi)
print(rozdel_ucet(1000, 3, spropitne=10))
print(inspect.getdoc(rozdel_ucet))
367
Rozdělí účet rovným dílem mezi lidi.
Args:
castka: Celková částka v korunách.
lidi: Počet platících, aspoň 1.
spropitne: Spropitné v procentech z částky.
Returns:
Částka na osobu zaokrouhlená na koruny nahoru.Co do docstringu patří:
- Co funkce dělá, ne jak to dělá. Postup je vidět v kódu.
- Co v názvech vidět není: jednotky, povolené hodnoty, zaokrouhlování.
- Co se stane v okrajových případech, třeba kdy se vrací
None. - Vedlejší účinky: zápis do souboru, změna předaného seznamu, odeslání e-mailu.
Komentář # je pro toho, kdo čte kód a ptá se proč je to takhle. Docstring je pro toho, kdo funkci jen používá. Docstring """Sečte a a b.""" u funkce secti(a, b) nepřináší nic a klidně ho vynech.
Do docstringu můžeš dát i ukázku použití. Modul doctest ji umí spustit a ověřit, takže dokumentace nezastará bez povšimnutí.
import doctest
def sleva(cena, procenta):
"""Vrátí cenu po slevě, zaokrouhlenou na dvě místa.
>>> sleva(200, 10)
180.0
>>> sleva(99.9, 0)
99.9
"""
return round(cena * (1 - procenta / 100), 2)
doctest.run_docstring_examples(sleva, {"sleva": sleva})
print("Když nad tímhle řádkem nic není, příklady sedí.")
Když nad tímhle řádkem nic není, příklady sedí.
Typové anotace: štítek, ne zámek
Anotace říká, jaký typ se čeká. Za parametr patří dvojtečka a typ, za závorku šipka -> a typ výsledku. Výchozí hodnota jde až za typ.
def opakuj(text: str, kolikrat: int = 2) -> str:
return text * kolikrat
pocet: int = 3
print(opakuj("na", pocet))
print(opakuj.__annotations__)
nanana
{'text': <class 'str'>, 'kolikrat': <class 'int'>, 'return': <class 'str'>}A teď to nejdůležitější: Python anotace při běhu nekontroluje. Uloží si je a dál se o ně nestará. Špatný typ program sám nezastaví.
def secti(a: int, b: int) -> int:
return a + b
print(secti(2, 3))
print(secti("ko", "lo"))
5 kolo
K čemu tedy jsou? Čte je člověk, čte je editor, který díky nim napovídá a podtrhává chyby, a čtou je kontrolní nástroje, které najdou chybu ještě před spuštěním.
Co udělá Python při secti("ko", "lo"), když je funkce označená a: int, b: int?
Anotace jsou informace pro lidi a nástroje. Běh neovlivňují, takže + spojí dva texty.
Doplň popis a typy
Funkci prumerna_cena nech fungovat stejně. Přidej jí docstring a typové anotace parametru i návratové hodnoty.
def prumerna_cena(ceny):
if not ceny:
return 0.0
return sum(ceny) / len(ceny)
print(prumerna_cena([10, 20]))
Typy, které potkáš nejčastěji
U kolekcí napíšeš do hranatých závorek, co obsahují. Svislítko znamená „nebo“. Tato ukázka je zároveň přehled, který si můžeš nechat po ruce.
from collections.abc import Callable, Iterable
def celkem(ceny: list[float]) -> float:
return sum(ceny)
def sklad(zasoby: dict[str, int], nazev: str) -> int:
return zasoby.get(nazev, 0)
def prvni_a_pocet(jmena: list[str]) -> tuple[str, int]:
return jmena[0], len(jmena)
def unikatni(slova: Iterable[str]) -> set[str]:
return set(slova)
def najdi(jmena: list[str], hledane: str) -> int | None:
return jmena.index(hledane) if hledane in jmena else None
def pouzij(funkce: Callable[[int], int], cislo: int) -> int:
return funkce(cislo)
def pozdrav(jmeno: str) -> None:
print("Ahoj", jmeno)
print(celkem([1.5, 2.5]), sklad({"káva": 3}, "čaj"))
print(prvni_a_pocet(["Eva", "Jan"]), sorted(unikatni(["a", "b", "a"])))
print(najdi(["Eva"], "Jan"), pouzij(abs, -4))
pozdrav("Evo")
4.0 0
('Eva', 2) ['a', 'b']
None 4
Ahoj Evolist[float]je seznam desetinných čísel. Celá čísla jsou tam také v pořádku, kontrolní nástrojeintpřijímají všude, kde se čekáfloat.dict[str, int]jsou klíče a hodnoty,tuple[str, int]dvojice s konkrétními typy na pozicích.int | Noneznamená číslo, nebo nic.Iterable[str]je cokoli, co jde projít cyklem: seznam, množina, generátor.Callable[[int], int]je funkce, která bereinta vracíint.-> Noneříká, že funkce nic užitečného nevrací.
Složitý typ si můžeš pojmenovat. Od Pythonu 3.12 na to slouží slovo type.
type Cenik = dict[str, float]
def nejdrazsi(cenik: Cenik) -> str:
return max(cenik, key=lambda nazev: cenik[nazev])
print(nejdrazsi({"káva": 65, "dort": 95}))
dort
None: chyba, kterou typy chytí nejčastěji
Funkce, která něco hledá, občas nenajde nic. Typ float | None to říká nahlas a nutí tě ten případ ošetřit. Bez ošetření program spadne, ale až když ta situace opravdu nastane, klidně měsíc po nasazení.
def najdi_cenu(cenik: dict[str, float], nazev: str) -> float | None:
return cenik.get(nazev)
cenik = {"káva": 65}
print(najdi_cenu(cenik, "káva") * 2)
print(najdi_cenu(cenik, "čaj") * 2)
130
Kontrolní nástroj jako mypy kód nespouští, jen ho čte. Tuhle chybu proto najde hned, i když žádný test ten případ nezkusil. Nainstaluješ a nastavíš ho v lekci Ruff, mypy a pre-commit. Výstup vypadá zhruba takto.
obchod.py:5: error: Unsupported operand types for * ("None" and "int") [operator]
obchod.py:5: note: Left operand is of type "float | None"
obchod.py:6: error: Unsupported operand types for * ("None" and "int") [operator]
obchod.py:6: note: Left operand is of type "float | None"
Found 2 errors in 1 file (checked 1 source file)Oprava je podmínka is None. Po ní už nástroj i čtenář vědí, že dál pracuješ s číslem.
def najdi_cenu(cenik: dict[str, float], nazev: str) -> float | None:
return cenik.get(nazev)
def dvojita_cena(cenik: dict[str, float], nazev: str) -> float:
cena = najdi_cenu(cenik, nazev)
if cena is None:
return 0.0
return cena * 2
print(dvojita_cena({"káva": 65}, "káva"))
print(dvojita_cena({"káva": 65}, "čaj"))
130 0.0
Cenovka s None
Napiš popis_ceny(cenik, nazev) s anotacemi. Použij připravenou najdi_cenu. Když zboží existuje, vrať text káva: 65 Kč. Když ne, vrať čaj: není v nabídce. Pozor, zboží zdarma s cenou 0 v nabídce je.
def najdi_cenu(cenik: dict[str, float], nazev: str) -> float | None:
return cenik.get(nazev)
def popis_ceny(cenik, nazev):
pass # doplň
print(popis_ceny({"káva": 65, "voda": 0}, "voda"))
Anotace jsou za běhu dostupné, takže s nimi může pracovat i tvůj kód. Na tom stojí knihovny jako pydantic nebo FastAPI, které podle nich kontrolují a převádějí data.
Vlastní malý kontrolor
Napiš spatne_argumenty(funkce, hodnoty). V hodnoty je slovník {nazev_parametru: hodnota}. Vrať seznam názvů parametrů, které mají v funkce.__annotations__ typ a hodnota mu neodpovídá. Parametry bez anotace přeskoč. Stačí jednoduché typy jako str nebo int, ověříš je přes isinstance.
def spatne_argumenty(funkce, hodnoty):
pass # doplň
def objednej(nazev: str, kusy: int, poznamka=""):
pass
print(spatne_argumenty(objednej, {"nazev": "káva", "kusy": "2"}))
Pod kapotou · docstringy: co o nich kurzy neříkají
Docstring vzniká jen z prostého řetězcového literálu na začátku těla. F-string se za docstring nepočítá a __doc__ zůstane None.
verze = "1.0"
def a():
f"Verze {verze}"
def b():
"Obyčejný text"
print(a.__doc__)
print(b.__doc__)
None Obyčejný text
Spuštění s python -OO docstringy z bajtkódu odstraní a __doc__ je None. Kód, který z nich za běhu něco čte, například CLI nápověda nebo generátor schémat, se tím rozbije. Ve 3.12 zůstává v __doc__ původní odsazení, od 3.13 ho odstraňuje už překladač. inspect.getdoc dá stejný výsledek v obou případech.
Konvence popisuje PEP 257: první věta shrnuje, pak prázdný řádek. Pro sekce se používají styly Google, NumPy nebo reST. Důležitější než volba je jednotnost, protože z ní čerpají generátory dokumentace. Typy do docstringu neopisuj, když už jsou v signatuře. Rozejdou se.
Pod kapotou · anotace pod kapotou a typové pasti
Ve 3.12 se anotace parametrů vyhodnotí při def, takže odkaz na dosud nedefinovanou třídu skončí NameError. Řeší se to řetězcem "Uzel" nebo from __future__ import annotations (PEP 563), kdy se ukládají jako text a k vyhodnocení slouží typing.get_type_hints. Python 3.14 přinesl odložené vyhodnocení podle PEP 649 a 749. Pro knihovny čtoucí anotace za běhu jde o podstatný rozdíl.
Anotace lokálních proměnných se naopak nevyhodnocují vůbec (PEP 526), na úrovni modulu ano.
def f():
x: NeexistujiciTyp = 1
return x
print(f())
print(f.__annotations__)
1
{}Generika v seznamu jsou invariantní. list[int] není list[float], přestože int se za float považuje (číselná výjimka z PEP 484). Volaný kód by totiž mohl do seznamu přidat 1.5 a volajícímu by zůstal seznam „celých čísel“ s desetinným číslem. Řešení je přijímat Sequence[float] nebo Iterable[float], které jsou jen ke čtení a kovariantní. Za touto chybou stojí většina překvapivých hlášek mypy.
from collections.abc import Sequence
def prumer_a(x: list[float]) -> float: return sum(x) / len(x)
def prumer_b(x: Sequence[float]) -> float: return sum(x) / len(x)
cisla: list[int] = [1, 2]
prumer_a(cisla) # mypy: incompatible type "list[int]"; expected "list[float]"
prumer_b(cisla) # v pořádkuAny kontrolu vypíná v obou směrech a nákaza se šíří dál, object přijme vše, ale nedovolí nic bez zúžení typu. bool je podtřída int, takže isinstance(True, int) platí a tvůj kontrolor ho propustí. Parametrizované typy do isinstance nesmějí: isinstance(x, list[int]) je TypeError. Jednotlivé milníky syntaxe: list[int] PEP 585, X | Y PEP 604, type a generika v hranatých závorkách PEP 695. Víc v lekci Pokročilé typy.