Comment fonctionnent les type hints et quels sont leurs avantages ?

Question

Accepted Answer

**Les type hints** (PEP 484+) vous permettent d'annoter les types attendus des variables, des paramètres de fonction et des valeurs de retour. Ils sont **optionnels** et **non appliqués à l'exécution** — Python les ignore lors de l'exécution — mais ils permettent l'analyse statique, de meilleurs outils et du code plus clair.

## Syntaxe de 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}
```

`: type` annote les paramètres/variables et `-> type` le retour. Ceux-ci documentent l'intention et sont vérifiés par les outils, mais Python **ne les applique pas à l'exécution** (passer un type erroné ne lèvera pas d'erreur par lui-même).

## Constructions typing courantes

```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
```

## La vérification de type statique détecte les bugs avant l'exécution

```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 vérificateur de type comme **mypy** ou **pyright** analyse les hints et signale les erreurs de type *avant* l'exécution du code — en détectant toute une classe de bugs (mauvais types d'arguments, mauvaise utilisation de None) rapidement, comme le ferait un compilateur.

## Les avantages

```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)
```

## Ils sont optionnels et progressifs

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

## Les frameworks les exploitent à l'exécution

```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
```

Certaines bibliothèques (Pydantic, FastAPI) lisent les type hints pour valider les données et générer la documentation — les rendant fonctionnellement significatifs à l'exécution.

## Pourquoi c'est important

Les type hints apportent de nombreux avantages du typage statique à Python sans sacrifier sa flexibilité dynamique : ils détectent les bugs liés aux types tôt (via mypy/pyright), améliorent considérablement les outils IDE et la refactorisation, servent de documentation vivante et alimentent les frameworks modernes (FastAPI, Pydantic) qui les utilisent pour la validation et la documentation auto-générée.

Bien qu'optionnels et non appliqués par Python lui-même à l'exécution, ils sont devenus un standard dans les codebases Python professionnelles et à grande échelle car ils rendent le code plus fiable, maintenable et auto-documenté — une pratique de plus en plus attendue, surtout à mesure que les projets se développent.