Como funcionam as anotações de tipo e quais são seus benefícios?

Question

Accepted Answer

**Anotações de tipo** (PEP 484+) permitem anotar os tipos esperados de variáveis, parâmetros de função e valores de retorno. Elas são **opcionais** e **não são aplicadas em tempo de execução** — Python as ignora durante a execução — mas permitem análise estática, melhor suporte de ferramentas e código mais claro.

## Sintaxe básica

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

O `: type` anota parâmetros/variáveis e `-> type` o retorno. Elas documentam a intenção e são verificadas por ferramentas, mas Python **não** as aplica em tempo de execução (passar um tipo errado não vai gerar erro por si só).

## Construtos comuns de tipagem

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

## Verificação de tipos estática detecta bugs antes da execução

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

Um verificador de tipos como **mypy** ou **pyright** analisa as anotações e relata erros de tipo *antes* de você executar o código — detectando uma classe inteira de bugs (tipos de argumento errados, uso incorreto de None) cedo, como um compilador faria.

## Os benefícios

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

## Elas são opcionais e gradativas

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

## Frameworks as aproveitam em tempo de execução

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

Algumas bibliotecas (Pydantic, FastAPI) leem anotações de tipo para validar dados e gerar documentação — tornando-as funcionalmente significativas em tempo de execução.

## Por que isso importa

Anotações de tipo trazem muitos benefícios da tipagem estática para Python sem sacrificar sua flexibilidade dinâmica: elas detectam bugs relacionados a tipos cedo (via mypy/pyright), melhoram dramaticamente as ferramentas de IDE e refatoração, servem como documentação viva e alimentam frameworks modernos (FastAPI, Pydantic) que as usam para validação e documentação auto-gerada.

Embora opcionais e não aplicadas em tempo de execução pelo próprio Python, elas se tornaram padrão em codebases Python profissionais e em larga escala porque tornam o código mais confiável, mantível e auto-documentado — cada vez mais uma prática esperada, especialmente conforme os projetos crescem.