Python Jiří Znamenáček Anotace funkcí 2017-05-29

Anotace funkcí (myšleno tím jejich argumentů a návratových hodnot) se v Python'u objevily jako první (tlak externích projektů, které uvedené řešily, byl už asi příliš veliký) a obecné anotace proměnných byly pak už – o dva roky později – přidány podle jejich vzoru.

Nicméně tato přednáška se věnuje především specifikům anotací u funkcí, proto, pokud je ještě neznáte, se nejdříve seznamte s obecnými anotacemi proměnných.

Anotovat je u funkcí možno dvě věci:

Parametry, a to jak poziční, tak pojmenované (s výchozí hodnotou):

def fn(parametr_poziční: VÝRAZ): ... def fn(parametr_pojmenovaný: VÝRAZ = výchozí_hodnota): ...

Parametry se tedy anotují pomocí dvojtečky :, za níž následuje výraz, jehož použití a vyhodnocení je zcela mimo pythoní interpretr – co si s ním která externí knihovna, nástroj či uživatel provedou, je zcela na nich. Výrazem tudíž může být prakticky naprosto cokoliv (tedy samozřejmě pokud je to validní pythoní výraz).

Návratovou hodnotu funkce:

def fn() -> VÝRAZ: ...

Návratová hodnota funkce se tedy anotuje pomocí sekvence znaků ->, za níž následuje validní pythoní výraz, jehož interpretace je opět – stejně jako u anotací parametrů – zcela v rukou externího nástroje.

Přístup k anotacím funkcí se řeší úplně stejně jako pro objekty v globálním jmenném prostoru nebo ještě spíš jako pro atributy tříd, tj. pomocí atributu __annotations__ na příslušné funkci:

>>> def fn(arg1: int, arg2: "druhý argument", kwarg1: list = [1, 2, 3]) -> int: pass >>> fn.__annotations__ {'arg1': <class 'int'>, 'arg2': 'druhý argument', 'kwarg1': <class 'list'>, 'return': <class 'int'>}

Anotace jsou tedy dostupné ve slovníku pod jménem odpovídajících parametrů. Přitom případná návratová hodnota funkce je dostupná pod předdefinovaným jménem return (to totiž jako jméno parametru nejde pochopitelně použít, takže nemůže dojít ke kolizi názvů).

PS: Možnost spravovat anotace z vlastního pythoního kódu nabízí docela nečekané možnosti, jak si za chvíli ukážeme. Nejdříve však ještě pár příkladů zápisu anotací.

První typické použití, které asi napadne každého, bude označení typů parametrů a návratové hodnoty funkce, jak je zvykem (především) u staticky typovaných jazyků:

def fn(a: int, b: int) -> int: pass

Nicméně je třeba opět zdůraznit: Žádný pythoní interpretr nemá za povinnost tyto anotace nějak zpracovávat! Jejich jediným úkolem je příslušné anotace poskytnout jako vlastnosti funkce pro další použití, ale sami je (aspoň u většiny) nijak nepoužívají a dále nezpracovávají.

Anotací však může být libovolný pythoní výraz, kupříkladu tedy třebas obyčejný řetězec:

def fn(a: "parametr funkce") -> "návratová hodnota funkce": pass

Třeba je externí knihovna daného projektu použije pro tvorbu vylepšené dokumentace, kdo ví?

A asi je vidět, že se oboje dá snadno spojit dohromady – stačí použít všeobjímající n-tici:

>>> def fn(a: (int, 'parametr')) -> (int, 'návratová hodnota'): pass >>> fn.__annotations__ {'a': (<class 'int'>, 'parametr'), 'return': (<class 'int'>, 'návratová hodnota')}

Pokud si externí program, který anotace zpracovává, umí s uvedeným zápisem poradit, je vše v pořádku.

Důvodem, proč jsem původně tuto přednášku vůbec napsal (běžnému smrtelníkovi totiž zatím pořád ještě nejsou anotace moc platné), je sada úžasných dekorátorů od Roddyho MacSweenyho (zde hodně upravené):

Vidíme, že dekorátor @checkargs pomocí anotací a introspekce (funkce isinstance()) ověřuje, zda zadané parametry skutečně splňují předepsaný typ, zatímco dekorátor @coerceargs se dokonce snaží parametry na daný typ převést (přímou aplikací zadaného typového konstruktoru na daný parametr).

PS: Do dekorátorů jsem připsal ověření typu návratové hodnoty. Zde je úplnější alternativní implementace pomocí objektu Signature.

Nicméně je třeba říci, že použitím kontroly typů přijdeme o klasické pythoní duck typing, tedy zjednodušeně možnost zpracování různých typů, které však implementují stejné metody (zde možnost iterace po prvcích):

# a) sama o sobě se anotace k ničemu nepoužívá >>> def fn(xs: list): ... return [x**2 for x in xs] >>> fn([1, 2, 3, 4]) [1, 4, 9, 16] >>> fn((1, 2, 3, 4)) [1, 4, 9, 16] >>> fn({1, 2, 3, 4}) [1, 4, 9, 16] # b) anotace ve spojení s dekorátorem @checkargs >>> @checkargs ... def fn(xs: list): ... return [x**2 for x in xs] >>> fn([1, 2, 3, 4]) [1, 4, 9, 16] >>> fn((1, 2, 3, 4)) Traceback (most recent call last): File "<pyshell#49>", line 1, in <module> fn((1, 2, 3, 4)) File "<pyshell#43>", line 11, in _f check_type_error(arguments[index], annotations[argument]) File "<pyshell#43>", line 6, in check_type_error raise TypeError(f"{index} is not of type {argument}") TypeError: (1, 2, 3, 4) is not of type <class 'list'>

Ačkoli je následující poznámka v podstatě přímou kopií textu z povídání o anotacích v Python'u obecně, pokládám ji za natolik důležitou, že ji zde stejně zopakuji:

Je třeba pamatovat na to, že Python byl/je/zůstává dynamicky typovaným jazykem a žádný z jeho interpretrů nemá v popisu práce s anotacemi dělat cokoliv jiného, než je „cpát“ do atributu __annotations__. Anotace v Python'u jsou a dlouho (navěky?) budou pouze pro potřeby externích nástrojů (či editorů), které nemusí vůbec provádět typovou kontrolu, ale klidně něco úplně jiného (například budovat lepší nápovědu).

PS: Od Python'u 3.9, v kterém již jde použít pro anotace složených typů běžné typové konstruktory jazyka (např. list[int] apod.), již pro použití anotací znalost modulu typing není nezbytně nutná, ale občas se hodit může.