0 dní v řadě · 0 bodů

Python pod kapotou · 30 min

Pokročilé typy: generika, TypedDict, overload

Typy, které si pamatují: generické funkce a třídy, přesný tvar slovníku z API a funkce s několika podpisy.

Hloubka
Úkoly
Lidsky řečeno

Představ si šatnu. Odevzdáš kabát a dostaneš lístek, na kterém stojí jen „věc“. Při vyzvednutí nikdo neví, jestli ti má přinést kabát, nebo deštník. Lepší šatna napíše na lístek „to, co jsi odevzdal“. Přesně to dělají generika: funkce nemusí znát konkrétní typ, ale pamatuje si, že co přišlo dovnitř, to vyjde i ven.

Když Any zapomíná

Z lekce Docstringy a typové anotace znáš zápisy jako list[int] nebo str | None. Připomenutí: Python anotace za běhu nekontroluje. Čte je typový kontrolor, tedy program jako mypy nebo pyright, který projde kód bez spuštění a hledá nesrovnalosti. Čte je i editor, když ti nabízí doplňování.

Jak ale otypovat funkci, která vrátí první prvek libovolného seznamu? První nápad je Any, typ „cokoli“.

from typing import Any

def prvni(prvky: list[Any]) -> Any:
    return prvky[0]

jmeno = prvni(["Ada", "Linus"])
print(jmeno.upper())

cislo = prvni([10, 20])
print(cislo.upper())
Výstup
ADA

Program spadl až za běhu a kontrolor by mlčel. Any totiž neznamená „nějaký typ“, ale „tady nic nekontroluj“. Informace, že ze seznamu čísel vypadne číslo, se cestou ztratila.

Typová proměnná: zástupné jméno

Řešením je typová proměnná. Je to jméno, které zastupuje typ podobně, jako parametr funkce zastupuje hodnotu. Píše se do hranatých závorek za jméno funkce. Funkci nebo třídě s takovým parametrem se říká generická.

def prvni[T](prvky: list[T]) -> T:
    return prvky[0]

print(prvni(["Ada", "Linus"]).upper())
print(prvni([10, 20]) + 1)
print(prvni.__type_params__)
print(prvni.__annotations__)
Výstup
ADA
11
(T,)
{'prvky': list[T], 'return': T}

Zápis čti takto: „pro libovolný typ T beru seznam prvků typu T a vracím jeden T“. Při každém volání si kontrolor za T dosadí to, co vidí. U ["Ada", "Linus"] je to str, u [10, 20] je to int. Kdybys teď napsal prvni([10, 20]).upper(), ohlásí chybu ještě před spuštěním. Výstup vypadá zhruba takto.

text
ukazka.py:4: error: "int" has no attribute "upper"  [attr-defined]
Found 1 error in 1 file (checked 1 source file)

Typových proměnných může být víc a mohou se skládat do dalších typů.

def prohod[A, B](par: tuple[A, B]) -> tuple[B, A]:
    prvni, druhy = par
    return druhy, prvni

def do_slovniku[K, V](klice: list[K], hodnoty: list[V]) -> dict[K, V]:
    return dict(zip(klice, hodnoty))

print(prohod(("Praha", 1_300_000)))
print(do_slovniku(["a", "b"], [1.5, 2.5]))
Výstup
(1300000, 'Praha')
{'a': 1.5, 'b': 2.5}

Hranaté závorky za jménem funkce umí Python od verze 3.12. Ve starším kódu potkáš delší zápis se samostatnou proměnnou. Znamená totéž a pořád funguje.

from typing import TypeVar

T = TypeVar("T")

def posledni(prvky: list[T]) -> T:
    return prvky[-1]

print(posledni(["start", "cíl"]))
print(T, type(T).__name__)
Výstup
cíl
~T TypeVar
Úkol

První prvek, nebo náhrada

Napiš generickou funkci prvni_nebo(prvky, vychozi). Vrátí první prvek seznamu, a když je seznam prázdný, vrátí vychozi. Anotace musí používat typové proměnné: prvky jsou seznam typu T, náhrada je typu D a návratový typ je T | D.

def prvni_nebo(prvky, vychozi):
    pass
Výstup

Generická třída

Stejný trik funguje u tříd. Zásobník čísel a zásobník textů mají stejný kód, liší se jen tím, co v nich leží.

class Zasobnik[T]:
    def __init__(self) -> None:
        self._prvky: list[T] = []

    def vloz(self, prvek: T) -> None:
        self._prvky.append(prvek)

    def vyjmi(self) -> T:
        return self._prvky.pop()

    def __len__(self) -> int:
        return len(self._prvky)

knihy = Zasobnik[str]()
knihy.vloz("Saturnin")
knihy.vloz("Babička")
print(knihy.vyjmi())
print(len(knihy))
print(type(knihy).__name__, knihy.__orig_class__)
Výstup
Babička
1
Zasobnik __main__.Zasobnik[str]

Zasobnik[str] říká kontroloru, že uvnitř budou texty. Volání knihy.vloz(42) proto označí jako chybu a o výsledku knihy.vyjmi() ví, že je to str. Za běhu se ale nic nehlídá.

class Krabice[T]:
    def __init__(self, obsah: T) -> None:
        self.obsah = obsah

k = Krabice[int]("tohle není číslo")
print(k.obsah)
print(type(k) is Krabice)
Výstup
tohle není číslo
True
Úkol

Generická fronta

Napiš generickou třídu Fronta s metodami pridej(prvek) a vyjmi() a s podporou len(). Fronta vydává prvky v pořadí, v jakém přišly. Musí jít psát Fronta[int]().

class Fronta:
    def pridej(self, prvek):
        pass

    def vyjmi(self):
        pass
Výstup

Omezení typové proměnné

Někdy potřebuješ, aby T něco umělo. Funkce nejdelsi volá len, takže nepřijme cokoli. Proto T dostane horní mez, zapsanou za dvojtečku. Pořád platí, že funkce vrátí přesně ten typ, který dostala: u seznamu textů str, u seznamu seznamů list. S obyčejným Sized by se tahle informace ztratila.

from collections.abc import Iterable, Sized

def nejdelsi[T: Sized](prvky: Iterable[T]) -> T:
    return max(prvky, key=len)

print(nejdelsi(["kočka", "hroch", "krokodýl"]))
print(nejdelsi([[1], [1, 2, 3], [1, 2]]))
print(nejdelsi.__type_params__[0].__bound__)
Výstup
krokodýl
[1, 2, 3]
<class 'collections.abc.Sized'>

Druhá možnost je výčet povolených typů v závorce. Tady musí být oba argumenty stejného typu, buď oba str, nebo oba bytes. Míchat je nejde, a tak kontrolor zachytí přesně tu chybu, kterou by jinak ohlásil až běh.

def spoj[S: (str, bytes)](a: S, b: S) -> S:
    return a + b

print(spoj("ko", "čka"))
print(spoj(b"ab", b"cd"))
print(spoj.__type_params__[0].__constraints__)
print(spoj("text", b"bajty"))
Výstup
kočka
b'abcd'
(<class 'str'>, <class 'bytes'>)

Delší typ si můžeš pojmenovat příkazem type. Alias smí odkazovat sám na sebe, což se hodí pro stromová data, třeba JSON.

type Json = dict[str, Json] | list[Json] | str | int | float | bool | None
type Matice[T] = list[list[T]]

def stopa(m: Matice[int]) -> int:
    return sum(m[i][i] for i in range(len(m)))

data: Json = {"jmeno": "Ada", "znamky": [1, 2, {"poznamka": None}]}
print(stopa([[1, 2], [3, 4]]))
print(Json.__name__)
print(Json.__value__)
Výstup
5
Json
dict[str, Json] | list[Json] | str | int | float | bool | None
Kvíz

Funkce má hlavičku def f[T](x: T) -> list[T]. Co kontrolor usoudí o výsledku f("a")?

TypedDict: slovník s daným tvarem

Odpovědi z API a obsah JSON souborů jsou slovníky. Typ dict[str, Any] o nich neřekne skoro nic. TypedDict popíše, jaké klíče mají být a jakého typu jsou jejich hodnoty.

from typing import NotRequired, TypedDict

class Objednavka(TypedDict):
    id: int
    zakaznik: str
    poznamka: NotRequired[str]

o: Objednavka = {"id": 17, "zakaznik": "Jana"}

print(o["zakaznik"])
print(o.get("poznamka", "bez poznámky"))
print(type(o).__name__)
print(sorted(Objednavka.__required_keys__))
print(sorted(Objednavka.__optional_keys__))
Výstup
Jana
bez poznámky
dict
['id', 'zakaznik']
['poznamka']

Vypadá to jako třída, ale žádná instance nevzniká. Za běhu je o obyčejný dict, takže se dál bez úprav posílá do json.dumps a nestojí nic navíc. Přínos je v tom, co vidí kontrolor.

python
spatne: Objednavka = {"id": 18}
o["cena"] = 100
print(o["zakznik"])
text
ukazka.py:1: error: Missing key "zakaznik" for TypedDict "Objednavka"  [typeddict-item]
ukazka.py:2: error: TypedDict "Objednavka" has no key "cena"  [typeddict-item]
ukazka.py:3: error: TypedDict "Objednavka" has no key "zakznik"  [typeddict-item]

Třetí řádek je překlep, který by za běhu skončil KeyError, a to možná až u zákazníka. Protože jde o obyčejný slovník, isinstance tu nedává smysl a Python ho rovnou odmítne.

from typing import TypedDict

class Bod(TypedDict):
    x: int
    y: int

b: Bod = {"x": 1, "y": 2}
print(b)
print(isinstance(b, Bod))
Výstup
{'x': 1, 'y': 2}

TypedDict jde i dědit. Potomek převezme klíče předka a přidá své. Parametr total=False udělá všechny vlastní klíče třídy nepovinnými a Required[...] z nich zase jednotlivé vyjme.

from typing import Required, TypedDict

class Adresa(TypedDict):
    mesto: str

class Filtr(Adresa, total=False):
    ulice: str
    psc: str
    stat: Required[str]

print(sorted(Filtr.__annotations__))
print(sorted(Filtr.__required_keys__))
print(sorted(Filtr.__optional_keys__))
Výstup
['mesto', 'psc', 'stat', 'ulice']
['mesto', 'stat']
['psc', 'ulice']
Úkol

Kontrola tvaru za běhu

TypedDict za běhu nic nehlídá, ale zná své klíče. Napiš funkci zkontroluj(data, typ), která vrátí dvojici seznamů (chybi, navic). V chybi jsou povinné klíče, které v data nejsou. V navic jsou klíče z data, které typ vůbec nezná. Oba seznamy seřaď.

from typing import NotRequired, TypedDict

class Uzivatel(TypedDict):
    jmeno: str
    email: str
    vek: NotRequired[int]

def zkontroluj(data, typ):
    return [], []

print(zkontroluj({"jmeno": "Ada", "role": "admin"}, Uzivatel))
Výstup

Literal: jen tyhle hodnoty

Někdy nejde o typ, ale o konkrétní hodnoty. str přijme jakýkoli text, Literal["nova", "placena"] jen tyto dva. Když k tomu přidáš assert_never, kontrolor ohlídá, že jsi na žádnou možnost nezapomněl. Až někdo přidá nový stav, označí větev else jako chybu.

from typing import Literal, assert_never, get_args

Stav = Literal["nova", "placena", "odeslana"]

def popis(stav: Stav) -> str:
    if stav == "nova":
        return "čeká na platbu"
    elif stav == "placena":
        return "balíme"
    elif stav == "odeslana":
        return "je na cestě"
    else:
        assert_never(stav)

print(get_args(Stav))
print(popis("placena"))
print(popis("vracena"))
Výstup
('nova', 'placena', 'odeslana')
balíme

overload: jedna funkce, víc podpisů

Některé funkce vrací jiný typ podle toho, co dostanou. Tahle dá pro jeden název jednu cenu a pro seznam názvů seznam cen. Anotace -> float | list[float] by byla pravdivá, ale neužitečná: volající by musel po každém volání zjišťovat, co vlastně dostal.

@overload popíše každou kombinaci zvlášť. Vypisuješ jen podpisy s tělem ... a pod ně přijde jediná skutečná implementace bez dekorátoru.

from typing import get_overloads, overload

CENIK = {"káva": 65.0, "čaj": 45.0, "dort": 95.0}

@overload
def cena(polozka: str) -> float: ...
@overload
def cena(polozka: list[str]) -> list[float]: ...

def cena(polozka: str | list[str]) -> float | list[float]:
    if isinstance(polozka, str):
        return CENIK[polozka]
    return [CENIK[p] for p in polozka]

print(cena("káva"))
print(cena(["čaj", "dort"]))
for podpis in get_overloads(cena):
    print(podpis.__annotations__)
Výstup
65.0
[45.0, 95.0]
{'polozka': <class 'str'>, 'return': <class 'float'>}
{'polozka': list[str], 'return': list[float]}

Kontrolor teď ví, že cena("káva") je float, a cena([...]) je list[float]. Za běhu existuje jen poslední funkce, větvení v ní musíš napsat sám. Stejným způsobem popisují typové definice standardní knihovny třeba open, kde výsledek závisí na hodnotě mode. K tomu se hodí Literal.

from typing import Literal, overload

@overload
def nacti(obsah: str, jako_bajty: Literal[True]) -> bytes: ...
@overload
def nacti(obsah: str, jako_bajty: Literal[False] = False) -> str: ...

def nacti(obsah: str, jako_bajty: bool = False) -> str | bytes:
    return obsah.encode() if jako_bajty else obsah

print(nacti("čaj"))
print(nacti("čaj", True))
Výstup
čaj
b'\xc4\x8daj'
Úkol

Jedna cena, nebo víc

Napiš funkci naformatuj se dvěma podpisy přes @overload. Pro float vrátí text jako 12.50 Kč, pro list[float] vrátí seznam takových textů.

def naformatuj(cena):
    return cena
Výstup
Kvíz

Kolik kódu z funkcí označených @overload se provede při volání?

Kvíz

Co je za běhu hodnota typu Objednavka, když jde o TypedDict?

Pod kapotou · varianta: proč list[bool] není list[int]

bool je podtřída int, přesto kontrolor odmítne předat list[bool] tam, kde se čeká list[int]. Funkce totiž smí do seznamu zapsat jakýkoli int, a tím by rozbila předpoklad volajícího.

def pridej_limit(cisla: list[int]) -> None:
    cisla.append(1000)

priznaky: list[bool] = [True, False]
pridej_limit(priznaky)
print(priznaky)
print(all(isinstance(p, bool) for p in priznaky))
Výstup
[True, False, 1000]
False

Měnitelné kontejnery jsou proto invariantní. Rozhraní jen pro čtení, jako Sequence[int], jsou kovariantní, tedy Sequence[bool] jim vyhovuje, a pokud funkce nepotřebuje zápis, je Sequence nebo Iterable v parametru lepší volba. Parametry v Callable jsou kontravariantní: tam, kde se čeká Callable[[bool], str], projde Callable[[int], str].

U syntaxe z PEP 695 varianci neurčuješ, kontrolor ji odvodí z toho, jak třída T používá. Za běhu to prozradí T.__infer_variance__, které je u nové syntaxe True. U klasického TypeVar ji píšeš ručně (covariant=True, contravariant=True) a výchozí je invariance.

Pod kapotou · co z generik zbude za běhu

list[int] je types.GenericAlias, objekt s __origin__ a __args__, který vzniká přes __class_getitem__. Volání aliasu vyrobí běžnou instanci a isinstance s parametrizovaným typem skončí TypeError, protože argumenty se neukládají do instance. Vlastní generická třída dědí implicitně z typing.Generic, což je vidět v MRO. Alias Krabice[int] po vytvoření zkusí nastavit instance.__orig_class__, ale až po __init__. Kdo se na něj spolehne v konstruktoru, dostane AttributeError, a třída se __slots__ ho nedostane vůbec.

class Krabice[T]:
    def __init__(self) -> None:
        print("v __init__:", hasattr(self, "__orig_class__"))

class Usporna[T]:
    __slots__ = ()

k = Krabice[int]()
print("po __init__:", k.__orig_class__.__args__)
print(hasattr(Usporna[int](), "__orig_class__"))
print([t.__name__ for t in Krabice.__mro__])
print(Krabice.__parameters__, Krabice.__orig_bases__)
print(type(list[int]).__name__, list[int].__origin__, list[int].__args__)
Výstup
v __init__: False
po __init__: (<class 'int'>,)
False
['Krabice', 'Generic', 'object']
(T,) (typing.Generic[T],)
GenericAlias <class 'list'> (<class 'int'>,)

Meze i hodnoty aliasů z PEP 695 se vyhodnocují líně, až při přístupu k __bound__ nebo __value__. Proto type Json = ... Json ... funguje bez uvozovek a dopředné odkazy nic nestojí při importu. Pozor na from __future__ import annotations: anotace TypedDict pak zůstanou textem a __required_keys__ přestanou být spolehlivé, což dokumentace výslovně uvádí.

from __future__ import annotations
from typing import NotRequired, TypedDict

class Profil(TypedDict):
    jmeno: str
    vek: NotRequired[int]

print(sorted(Profil.__required_keys__))
print(sorted(Profil.__optional_keys__))
Výstup
['jmeno', 'vek']
[]

Runtime validátor nad TypedDict proto staví na typing.get_type_hints(T, include_extras=True), ne na těchto množinách.

Pod kapotou · ParamSpec, Self a typy pro **kwargs

Dekorátor typovaný jako Callable[..., R] smaže podpis obalené funkce. ParamSpec (v nové syntaxi **P) ho zachová, takže kontrolor dál hlídá argumenty. Concatenate[Spojeni, P] popíše dekorátor, který jeden argument přidává nebo odebírá. Podrobnosti o obalech jsou v lekci Dekorátory.

from collections.abc import Callable
from functools import wraps
from typing import Self, TypedDict, Unpack, override

def s_logem[**P, R](f: Callable[P, R]) -> Callable[P, R]:
    @wraps(f)
    def obal(*args: P.args, **kwargs: P.kwargs) -> R:
        print("volám", f.__name__, args, kwargs)
        return f(*args, **kwargs)
    return obal

@s_logem
def secti(a: int, b: int = 0) -> int:
    return a + b

class Volby(TypedDict, total=False):
    timeout: float
    pokusy: int

class Klient:
    def nastav(self, **volby: Unpack[Volby]) -> Self:
        self.volby = volby
        return self

class TestKlient(Klient):
    @override
    def nastav(self, **volby: Unpack[Volby]) -> Self:
        return super().nastav(pokusy=1, **volby)

print(secti(2, b=3))
print(type(TestKlient().nastav(timeout=1.5)).__name__)
print(TestKlient.nastav.__override__)
Výstup
volám secti (2,) {'b': 3}
5
TestKlient
True

Unpack[Volby] pro **kwargs a @override jsou novinky Pythonu 3.12 (PEP 692 a PEP 698). Self vrací skutečný typ potomka, a ne základní třídu. Pro vlastní zužování typů slouží TypeGuard. Přesnější TypeIs přišlo až ve 3.13, ve 3.12 ho dá balík typing_extensions.

U overload hlídej překryv: podpisy se zkoušejí shora dolů, takže bool musí být před int, jinak se nikdy neuplatní. Implementace musí přijmout všechny varianty. Mypy a pyright se v řešení nejednoznačných volání místy liší, takže knihovna určená pro obě skupiny uživatelů potřebuje typové testy pro oba nástroje.