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())
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__)
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.
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]))
(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__)
cíl ~T TypeVar
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
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__)
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)
tohle není číslo True
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
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__)
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"))
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__)
5 Json dict[str, Json] | list[Json] | str | int | float | bool | None
Funkce má hlavičku def f[T](x: T) -> list[T]. Co kontrolor usoudí o výsledku f("a")?
Kontrolor dosadí za T typ argumentu, tedy str. Any by informaci zahodil a za běhu se neověřuje nic.
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__))
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.
spatne: Objednavka = {"id": 18}
o["cena"] = 100
print(o["zakznik"])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))
{'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__))
['mesto', 'psc', 'stat', 'ulice'] ['mesto', 'stat'] ['psc', 'ulice']
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))
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"))
('nova', 'placena', 'odeslana')
balímeoverload: 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__)
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))
čaj b'\xc4\x8daj'
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
Kolik kódu z funkcí označených @overload se provede při volání?
Podpisy existují pro kontrolor. Python za běhu nevybírá podle typů, větvení musíš napsat v implementaci.
Co je za běhu hodnota typu Objednavka, když jde o TypedDict?
TypedDict existuje pro kontrolor. Za běhu vznikne běžný slovník, takže isinstance nefunguje a klíče se neověřují.
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))
[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 __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__))
['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__)
volám secti (2,) {'b': 3}
5
TestKlient
TrueUnpack[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.