Risposta

Storia della questione

Le annotazioni delle funzioni sono state introdotte in Python 3.0 e il meccanismo type hints (suggerimenti di tipo) è descritto nel PEP 484, aggiunto con la versione 3.5. Questo strumento è stato creato per l'analisi statica del codice, il completamento automatico e per migliorare la leggibilità — la libreria standard di tipo (typing) consente di specificare esplicitamente i tipi attesi delle variabili, degli argomenti e dei valori di ritorno delle funzioni.

Problema

Python è un linguaggio dinamico, dove i tipi delle variabili possono cambiare durante l'esecuzione, il che può portare a errori solo al momento dell'esecuzione del programma. Le annotazioni non influenzano l'esecuzione del codice, ma se usate in modo errato possono dare ai programmatori una falsa sensazione di "tipizzazione rigida".

Soluzione

Le annotazioni di tipo sono utilizzate per la documentazione, il controllo automatico tramite mypy, pylance, pyright e strumenti simili, nonché per l'integrazione con l'IDE. Si implementano tramite i due punti dopo il nome dell'argomento e la freccia dopo l'elenco dei parametri:**

def greet(name: str, times: int = 1) -> None:
    for _ in range(times):
        print(f"Hello, {name}!")

# Annotazione corretta per la funzione di elaborazione di un dizionario
from typing import Dict, List

def transform(data: Dict[str, List[int]]) -> float:
    return sum(sum(lst) for lst in data.values()) / 10

Caratteristiche chiave:

Le annotazioni non sono verificate dall'interprete, rimangono durante l'esecuzione del codice, ma non modificano in alcun modo l'esecuzione
Sono rilevanti per progetti di grandi dimensioni, dove è importante comprendere le interfacce e l'interazione tra componenti
Per costruzioni complesse servono typing.List, typing.Dict, typing.Optional, typing.Union, ecc.

Domande trabocchetto.

Python può "verificare automaticamente" la corrispondenza ai tipi dichiarati nelle annotazioni?

No! Il controllo dei tipi avviene solo tramite strumenti esterni di analisi statica, come mypy. A runtime, Python ignora completamente il contenuto delle annotazioni.

def f(x: int):
    return x * 2

print(f('oops'))  # Tipo str, non ci sarà errore!

Dove vengono memorizzate le annotazioni e come ottenerle a runtime, a cosa può servire?

Vengono memorizzate in un attributo speciale annotations:

def add(x: int, y: int) -> int:
    return x + y

print(add.__annotations__)  # {'x': <class 'int'>, 'y': <class 'int'>, 'return': <class 'int'>}

Questo è utilizzato da librerie di terze parti per la validazione dei dati, la generazione automatica di documentazione, la serializzazione, ecc.

È possibile annotare qualsiasi variabile, solo funzioni, cosa succede nell'area globale?

È possibile annotare sia variabili locali che globali tramite i due punti, questo non influisce nemmeno sull'esecuzione:

index: int = 0

def func(x: 'User') -> None:
    ...

Errori comuni e anti-pattern

Pensare che i type hints siano parte di una tipizzazione rigorosa e di un controllo rigoroso dei tipi
Dimenticare che i valori predefiniti devono essere compatibili con il tipo dichiarato (anche se questo non è verificato al momento dell'esecuzione)
Uso errato di tipi complessi da typing (ad esempio, List<int> invece di List[int])

Esempio dalla vita reale

Caso negativo

In un progetto aziendale tutti gli sviluppatori hanno cominciato a implementare attivamente le annotazioni, ma i tipi reali degli argomenti delle funzioni spesso non corrispondevano a quelli dichiarati. Python tollerava questi errori e bug inaspettati apparivano solo nella profonda logica di business. Manca la configurazione di mypy.

Pro:

Miglioramento del completamento automatico e della documentazione

Contro:

Rimasero errori impliciti, portando la causa lontano dal luogo di annotazione

Caso positivo

Utilizzo di type hints e avvio obbligatorio di mypy in CI, così come la generazione automatica di documentazione tramite annotations: