Beschrijf waarden met typehints

De vorige les gebruikte een docstring om de belofte van een functie in volledige zinnen te beschrijven. Soms heeft een lezer ook een kort overzicht nodig van de soorten waarden die een functie in- en uitgaan.

Python laat je die aanwijzingen direct aan de functiedefinitie toevoegen. Ze heten typehints.

Geef een aanwijzing voor het type van een parameter

Begin met een gewone functie:

def repeat(text, times):
    return text * times

Schrijf een dubbele punt en de typenaam na de parameter om te zeggen dat text een string moet zijn:

def repeat(text: str, times):
    return text * times

De : str is een typehint. Die zegt dat de functie voor text een string verwacht.

Je kunt elke parameter een eigen hint geven:

def repeat(text: str, times: int):
    return text * times

Lees deze definitie als: “repeat verwacht een string met de naam text en een geheel getal met de naam times.”

De hint gebruikt een typenaam zoals str, int, float of bool. Die gebruikt geen voorbeeldwaarde, dus schrijf text: str, niet text: "hello".

Geef een aanwijzing voor het teruggegeven type

Een hint na een pijl beschrijft de waarde die de functie teruggeeft:

def repeat(text: str, times: int) -> str:
    return text * times

De -> str zegt dat repeat belooft een string terug te geven. De pijl hoort na het sluitende ronde haakje en vóór de dubbele punt die de regel met def afsluit.

Hier is een gemiddeldefunctie met alle drie de hints:

def average(total: int, count: int) -> float:
    return total / count

Je kunt die van links naar rechts lezen:

• total: int zegt dat total een geheel getal moet zijn;

• count: int zegt dat count een geheel getal moet zijn;

• -> float zegt dat de functie een getal met drijvende komma moet teruggeven.

De aanroep van de functie verandert niet:

result = average(21, 3)

De hints horen bij de definitie, niet bij elke aanroep.

Bekijk typehints met help()

In de vorige les gebruikte je help() om de docstring van een functie te lezen. Dezelfde uitvoer toont ook de typehints.

Voer dit voorbeeld uit:

help() vat de functie zo samen:

average(total: int, count: int) -> float

De hints voor parameters en de teruggegeven waarde komen uit de functiedefinitie. De zin eronder komt uit de docstring. Samen tonen ze beide soorten documentatie zonder dat iemand het functieblok hoeft te lezen.

Hints beschrijven, maar dwingen niet af

Python wijst een waarde niet automatisch af alleen omdat die niet bij een typehint past:

De tweede aanroep geeft een string mee, hoewel de hint int zegt. Python voert het functieblok nog steeds uit en het vermenigvuldigen van de string levert "haha" op.

Het functieblok bepaalt nog steeds wat er gebeurt terwijl het programma draait.

Dit verschilt van veel andere programmeertalen. In statisch getypeerde talen zoals Java, C# en Rust horen gedeclareerde typen bij de regels van de taal. Een verkeerd type meegeven wordt normaal afgewezen voordat het programma draait. De typehints van Python bieden nuttige informatie, maar Python dwingt ze niet automatisch af.

Help automatische controles

Typehints zijn vooral nuttig voor hulpmiddelen die code op waarschijnlijke fouten onderzoeken. Een linter is een algemene automatische codecontroleur. Een typechecker richt zich op de vraag of waarden bij typehints passen.

Een typechecker kan bijvoorbeeld deze aanroep met de bovenstaande definitie vergelijken:

double("ha")

Die kan waarschuwen dat double een int verwacht, terwijl de aanroep een str meegeeft. De controleur kan dat verschil vinden zonder het programma uit te voeren. Code-editors kunnen dezelfde soort waarschuwing tonen terwijl je typt.

De waarschuwing verandert het gedrag van Python tijdens het uitvoeren niet: zoals het uitvoerbare voorbeeld liet zien, voert Python zelf de aanroep nog steeds uit. Typehints geven mensen en automatische controleurs meer informatie om een waarschijnlijke fout eerder te ontdekken.

Dat maakt kloppende hints belangrijk. Een verkeerde hint kan de volgende gebruiker van de functie misleiden.

Voeg hints toe aan een bestaande functie

De percentagefunctie berekent het juiste resultaat al. Voeg alleen de typehints toe die de twee parameters en teruggegeven waarde beschrijven. De volgende les gebruikt die teruggegeven waarde om pure functies met neveneffecten te vergelijken.