Come funzionano i type hints e quali sono i loro vantaggi?

Question

Accepted Answer

**Type hints** (PEP 484+) ti permettono di annotare i tipi attesi di variabili, parametri di funzione e valori di ritorno. Sono **opzionali** e **non applicati a runtime** — Python li ignora quando eseguito — ma abilitano analisi statica, migliori strumenti e codice più chiaro.

## Sintassi di base

```python
def greet(name: str, times: int = 1) -> str:
    return name * times

age: int = 30
names: list[str] = ["Ann", "Bob"]
scores: dict[str, int] = {"math": 90}
```

Il `: type` annota parametri/variabili e `-> type` il ritorno. Questi documentano l'intenzione e sono controllati dagli strumenti, ma Python **non** li applica a runtime (passare un tipo errato non solleverà un errore di per sé).

## Costrutti di typing comuni

```python
from typing import Optional, Union, Callable, Any

def find(id: int) -> Optional[str]:    # str OR None (= str | None in 3.10+)
    ...

x: int | str                           # Union (3.10+ syntax)
handler: Callable[[int], bool]         # a function taking int, returning bool
items: list[dict[str, int]]            # nested generics
```

## Il type checking statico cattura i bug prima del runtime

```python
def add(a: int, b: int) -> int:
    return a + b

add("hello", 3)   # ✅ Python runs it (and crashes); ❌ mypy/pyright flags it BEFORE running
```

Un type checker come **mypy** o **pyright** analizza gli hint e segnala errori di tipo *prima* di eseguire il codice — catturando un'intera classe di bug (tipi di argomenti errati, abuso di None) in anticipo, come farebbe un compilatore.

## I vantaggi

```text
✓ Catch type bugs early via static checkers (mypy, pyright) — before runtime
✓ IDE support — better autocomplete, refactoring, inline error detection
✓ Self-documenting code — signatures show exactly what's expected/returned
✓ Powers frameworks — FastAPI/Pydantic USE hints for validation & docs
✓ Easier maintenance of large codebases (catch breaking changes)
```

## Sono opzionali e graduali

```text
You can add hints incrementally — a few functions, or strictly everywhere.
Unannotated code still works. "Gradual typing" suits adopting them over time.
```

## I framework li sfruttano a runtime

```python
from pydantic import BaseModel
class User(BaseModel):
    name: str
    age: int            # Pydantic USES the hint to VALIDATE data at runtime
User(name="Ann", age="x")   # raises a validation error
```

Alcune librerie (Pydantic, FastAPI) leggono gli type hint per validare i dati e generare documenti — rendendoli funzionalmente significativi a runtime.

## Perché è importante

I type hint portano molti vantaggi del typing statico a Python senza sacrificare la sua flessibilità dinamica: catturano i bug relativi ai tipi in anticipo (tramite mypy/pyright), migliorano drasticamente gli strumenti dell'IDE e il refactoring, fungono da documentazione viva, e potenziano i framework moderni (FastAPI, Pydantic) che li utilizzano per la convalida e i documenti auto-generati. Sebbene opzionali e non applicati da Python stesso a runtime, sono diventati standard nelle codebase Python professionali e su larga scala perché rendono il codice più affidabile, manutenibile e autodocumentato — sempre più una pratica attesa, specialmente man mano che i progetti crescono.