Cum funcționează indiciile de tip și care sunt avantajele lor?

Question

Accepted Answer

**Indiciile de tip** (PEP 484+) vă permit să adnotați tipurile așteptate ale variabilelor, parametrilor funcțiilor și valorilor returnate. Sunt **opționale** și **nu sunt aplicate în timp de execuție** — Python le ignoră atunci când rulează — dar ele activează analiza statică, o instrumentare mai bună și un cod mai clar.

## Sintaxa de bază

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

Caracterul `: type` adnotează parametri/variabile și `-> type` returnarea. Acestea documentează intenția și sunt verificate de instrumente, dar Python **nu** le aplică în timp de execuție (trecerea unui tip greșit nu va declanșa o eroare de la sine).

## Construcții tipice de tip

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

## Verificarea tipurilor statice depistează bug-uri înainte de execuție

```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 verificator de tip ca **mypy** sau **pyright** analizează indiciile și raportează erori de tip *înainte* de a rula codul — depistând o întreagă clasă de bug-uri (tipuri de argumente greșite, utilizare necorespunzătoare a None) din vreme, așa cum ar face un compilator.

## Avantajele

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

## Sunt opționale și graduale

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

## Cadrul de lucru le folosește în timp de execuție

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

Unele biblioteci (Pydantic, FastAPI) citesc indiciile de tip pentru a valida datele și genera documentația — făcându-le semnificative din punct de vedere funcțional în timp de execuție.

## De ce conteaza

Indiciile de tip aduc numeroase avantaje ale tipării statice în Python fără a sacrifica flexibilitatea sa dinamică: depistează bug-uri legate de tip din vreme (via mypy/pyright), îmbunătățesc dramatic instrumentarea IDE și refactorizarea, servesc ca documentație vie și alimentează cadre moderne (FastAPI, Pydantic) care le folosesc pentru validare și documente generate automat.

Deși opționale și nu aplicate în timp de execuție de Python în sine, au devenit standard în bazele de cod Python profesionale și la scară largă deoarece fac codul mai fiabil, mai ușor de menținut și autodocumentat — din ce în ce mai mult o practică așteptată, mai ales pe măsură ce proiectele cresc.