0 dní v řadě · 0 bodů

Funkce · 22 min

Docstringy a typové anotace

Naučíš funkce říct, co dělají a co čekají. Docstringy, typové anotace, práce s None a kontrola chyb ještě před spuštěním.

Hloubka
Úkoly
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]))
Výstup
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))
Výstup
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__)
Výstup
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.

python
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))
Výstup
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í.")
Výstup
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__)
Výstup
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"))
Výstup
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.

Kvíz

Co udělá Python při secti("ko", "lo"), když je funkce označená a: int, b: int?

Úkol

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

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")
Výstup
4.0 0
('Eva', 2) ['a', 'b']
None 4
Ahoj Evo
  • list[float] je seznam desetinných čísel. Celá čísla jsou tam také v pořádku, kontrolní nástroje int př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 | None znamená číslo, nebo nic.
  • Iterable[str] je cokoli, co jde projít cyklem: seznam, množina, generátor.
  • Callable[[int], int] je funkce, která bere int a 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}))
Výstup
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)
Výstup
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.

text
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"))
Výstup
130
0.0
Úkol

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

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.

Úkol

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"}))
Výstup
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__)
Výstup
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__)
Výstup
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.

python
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řádku

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