TypedDict & NamedTuple

TypedDict adiciona forma estática a dicionários (dict) - perfeito para blobs JSON. NamedTuple fornece registros imutáveis mais leves que dataclasses para linhas somente leitura.

Receita

from typing import TypedDict
 
class UserRow(TypedDict):
    id: int
    email: str
 
def load(row: UserRow) -> str:
    return row["email"]

Quando usar isso:

• Para tipar estruturas de response.json()
• Linhas de pipeline CSV/JSON como dicionários (dict)
• Registros leves e imutáveis a partir de tuplas
• Tipagem gradual sem alterar tipos em tempo de execução

Exemplo de Trabalho

from typing import NamedTuple, NotRequired, TypedDict
 
class Address(TypedDict, total=False):
    street: str
    city: str
    zip: NotRequired[str]
 
class User(TypedDict):
    id: int
    name: str
    address: Address
 
class Point(NamedTuple):
    x: int
    y: int
 
def format_user(user: User) -> str:
    city = user.get("address", {}).get("city", "unknown")
    return f"{user['name']} ({city})"
 
def distance(a: Point, b: Point) -> float:
    return ((a.x - b.x) ** 2 + (a.y - b.y) ** 2) ** 0.5
 
if __name__ == "__main__":
    row: User = {"id": 1, "name": "Ada", "address": {"city": "London"}}
    print(format_user(row))
    print(distance(Point(0, 0), Point(3, 4)))

O que isso demonstra:

• total=False torna as chaves de Address opcionais estaticamente
• NotRequired marca chaves opcionais em TypedDict que, de outra forma, seria total (3.11+)
• TypedDict ainda é um dict em tempo de execução - acesso via user["name"]
• Campos NamedTuple acessados como atributos com desempacotamento de tupla

Mergulho Profundo

Como Funciona

• TypedDict - Construto puramente de tipagem; sem validação em tempo de execução por padrão.
• flag total - Todas as chaves são obrigatórias quando total=True (padrão).
• Herança - TypedDict pode estender outros TypedDict para formas de API aninhadas.
• NamedTuple - Subclasse de tuple; imutável; pode ter métodos com moderação.
• typing_extensions - Backports para Python mais antigo; 3.14 tem NotRequired em typing.

Escolha o Tipo de Registro

Notas de Python

# Chave obrigatória em TypedDict parcial (3.11+)
class Config(TypedDict, total=False):
    debug: NotRequired[bool]
    host: str  # obrigatório se usar Required[] em padrões parciais

Armadilhas

• TypedDict sem validação em tempo de execução - Tipos errados passam até serem usados. Correção: Pydantic nas fronteiras.
• Chaves extras permitidas - TypedDict não proíbe chaves desconhecidas, a menos que seja um TypedDict fechado (recursos do PEP 728+ variam). Correção: Valide externamente.
• Campos mutáveis em NamedTuple se não for cuidadoso - Campos são imutáveis, mas os campos do objeto podem conter mutáveis. Correção: Tupla de imutáveis.
• TypedDict vs JSON de dataclass - TypedDict permanece dict para APIs que esperam Mapping. Correção: Escolha com base no consumidor.
• Erros de digitação em chaves - mypy captura user["emial"]; o tempo de execução ainda gera KeyError. Correção: Verificação estática + testes.

Alternativas

FAQs

Relacionado

• Generics em Coleções e Embutidos - dict[str, T]
• dataclasses - registros mutáveis
• Optional, Union & o Operador | - campos opcionais
• Literal, Final & Annotated - valores de dict restritos

Versões das Pilhas: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.