Quando desenvolvemos aplicações em Python, uma das tarefas mais importantes e frequentemente negligenciadas é a validação de dados. Sem uma validação adequada, nossos sistemas ficam vulneráveis a erros, inconsistências e possíveis brechas de segurança. É exatamente aí que o Pydantic entra em cena como uma ferramenta indispensável para qualquer desenvolvedor Python.
O Pydantic é uma biblioteca que define como os dados devem ser estruturados usando tipos Python nativos, oferecendo validação automática, serialização e documentação de modelos de dados. Desde sua criação, tornou-se o padrão de facto para validação de dados em frameworks como o FastAPI, e sua adoção cresce exponencialmente na comunidade Python.
🎯 Por Que Usar Pydantic?
Antes de mergulharmos nos detalhes técnicos, é fundamental entender por que o Pydantic se tornou tão popular no ecossistema Python. Imagine a situação comum onde você recebe dados de uma API externa, de um formulário web, ou de qualquer outra fonte externa ao seu sistema. Tradicionalmente, você teria que escrever manualmente múltiplos checks e validações para garantir que os dados estão no formato esperado.
Com o Pydantic, você define simplesmente a estrutura esperada usando classes Python com type hints, e a biblioteca faz todo o trabalho pesado automaticamente. Segundo a documentação oficial do Pydantic, a biblioteca "valida dados automaticamente contra os tipos e restrições definidas, gerando erros claros e úteis quando os dados são inválidos".
Além da validação automática, o Pydantic oferece serialização e deserialização automáticas, converting objetos Python para e a partir de JSON, dicionários e outros formatos. Isso elimina uma quantidade significativa de código boilerplate que tradicionalmente precisamos escrever.
📦 Instalação e Configuração
Instalar o Pydantic é extremamente simples. Como é uma biblioteca pure Python, você pode instalá-la via pip:
pip install pydanticPara projetos que utilizam recursos avançados como validação de configurações de ambiente, você pode instalar a extensão pydantic-settings:
pip install pydantic-settingsO Pydantic é compatível com Python 3.8 e versões posteriores. Para verificar a versão instalada, você pode executar:
import pydantic
print(pydantic.__version__)A Real Python oferece um excelente tutorial inicial sobre Pydantic que complementa muito bem este guia.
🏗️ Criando Seu Primeiro Modelo
A base do Pydantic são os modelos, definidos através de classes que herdam de BaseModel. Vamos criar um exemplo simples para entender como funciona:
from pydantic import BaseModel
class Usuario(BaseModel):
nome: str
email: str
idade: int
# Criando uma instância
usuario = Usuario(nome="João Silva", email="[email protected]", idade=30)
print(usuario)Perceba que não precisamos especificar os tipos entre aspas ou usar sintaxe especial. O Pydantic usa os type hints nativos do Python para definir a estrutura dos dados.
Quando você tenta criar um modelo com dados inválidos, o Pydantic gera uma exceção ValidationError com mensagens claras e descritivas:
try:
usuario_invalido = Usuario(nome="João", email="email-invalido", idade=-5)
except Exception as e:
print(e)Este código vai gerar erros indicando que o email está em formato inválido e que a idade não pode ser negativa.
🔧 Tipos de Campo Avançados
O Pydantic suporta uma ampla variedade de tipos além dos básicos. Vamos explorar alguns dos mais úteis:
1. Tipos Opcionais e com Valor Padrão
from pydantic import BaseModel
from typing import Optional
class Produto(BaseModel):
nome: str
preco: float
descricao: Optional[str] = None
em_estoque: bool = TrueNeste exemplo, descricao é um campo opcional (pode ser None), e em_estoque tem um valor padrão de True.
2. Validação com Field
O Pydantic permite自定义izar ainda mais a validação usando a função Field:
from pydantic import BaseModel, Field
from typing import Annotated
class UsuarioRegistro(BaseModel):
username: Annotated[str, Field(min_length=3, max_length=20)]
password: Annotated[str, Field(min_length=8)]
email: str
idade: int = Field(ge=18, le=120)Aqui, definimos validações específicas: username deve ter entre 3 e 20 caracteres, password no mínimo 8, e idade deve estar entre 18 e 120 anos.
3. Tipos de Email e URL
O Pydantic incluye tipos especiais para validação de formatos específicos:
from pydantic import BaseModel, EmailStr, HttpUrl
class Contato(BaseModel):
email: EmailStr
website: HttpUrl
telefone: strEmailStr valida automaticamente que a string está em formato válido de email, e HttpUrl valida URLs.
4. Listas e Tipos Genéricos
from pydantic import BaseModel
from typing import List, Dict
class Pedido(BaseModel):
itens: List[str]
precos: List[float]
atributos: Dict[str, str]🔄 Validadores Personalizados
Por vezes, as validações built-in não são suficientes para suas necessidades específicas. O Pydantic permite criar validadores personalizados usando o decorador @field_validator:
from pydantic import BaseModel, field_validator
import re
class UsuarioAdvanced(BaseModel):
nome: str
cpf: str
senha: str
@field_validator('cpf')
@classmethod
def validar_cpf(cls, v):
# Remove caracteres não numéricos
cpf = re.sub(r'\D', '', v)
if len(cpf) != 11:
raise ValueError('CPF deve ter 11 dígitos')
return cpf
@field_validator('senha')
@classmethod
def validar_senha(cls, v):
if len(v) < 8:
raise ValueError('Senha deve ter pelo menos 8 caracteres')
if not re.search(r'[A-Z]', v):
raise ValueError('Senha deve conter pelo menos uma letra maiúscula')
return vEste exemplo mostra como criar validadores para CPF e senha com regras específicas do seu negócio.
Validadores de Modelo Completo
Além de validadores de campo, você pode criar validadores que funcionam com o modelo inteiro:
from pydantic import BaseModel, model_validator
from datetime import date
class Reserva(BaseModel):
data_inicio: date
data_fim: date
hospedes: int
@model_validator(mode='after')
def validar_periodo(self):
if self.data_fim <= self.data_inicio:
raise ValueError('Data de fim deve ser posterior ao início')
if self.hospedes < 1:
raise ValueError('Deve haver pelo menos 1 hóspede')
return self📋 Modelos com Herança
O Pydantic suporta herança de modelos, permitindo criar hierarquias de dados organizadas:
from pydantic import BaseModel
from typing import Optional
class Pessoa(BaseModel):
nome: str
email: str
class Funcionario(Pessoa):
cargo: str
salario: float
departamento: Optional[str] = None
class Gerente(Funcionario):
equipe_gestao: list[str] = []
bonus: float = 0.0Funcionario herda todos os campos de Pessoa e adiciona seus próprios campos específicos.
🔄 Serialização e Desserialização
Uma das funcionalidades mais poderosas do Pydantic é a capacidade de converter modelos para diferentes formatos:
from pydantic import BaseModel
class Produto(BaseModel):
nome: str
preco: float
categoria: str
# Criar instância
produto = Produto(nome="Notebook", preco=3500.00, categoria="Eletrônicos")
# Converter para dicionário
dicionario = produto.model_dump()
print(dicionario)
# {'nome': 'Notebook', 'preco': 3500.0, 'categoria': 'Eletrônicos'}
# Converter para JSON
json_str = produto.model_dump_json()
print(json_str)
# {"nome": "Notebook", "preco": 3500.0, "categoria": "Eletrônicos"}
# Criar instância a partir de dicionário
produto2 = Produto.model_validate(dicionario)O Pydantic também permite excluir campos, incluir apenas alguns campos, ou transformar nomes durante a serialização usando o parâmetro mode:
# Excluir campos sensíveis
seguro = produto.model_dump(exclude={'preco'})
# Incluir apenas campos específicos
resumo = produto.model_dump(include={'nome', 'categoria'})
# Usar alias para serialização
class ProdutoAlias(BaseModel):
nome_produto: str = Field(alias='nome')
preco_unitario: float = Field(alias='preco')
model_config = {'populate_by_name': True}⚙️ Configurações de Modelo
Cada modelo Pydantic pode ter configurações específicas através da classe Config:
from pydantic import BaseModel, ConfigDict
class UsuarioConfig(BaseModel):
nome: str
email: str
senha: str
model_config = ConfigDict(
str_to_lower=True, # Converte strings para minúsculas
str_strip_whitespace=True, # Remove espaços em branco
frozen=True, # Torna o modelo imutável
extra='forbid' # Proíbe campos extras
)Algumas das configurações mais úteis incluem:
- str_to_lower: Converte automaticamente todas as strings para minúsculas
- str_strip_whitespace: Remove espaços em branco do início e fim
- frozen: Torna o modelo imutável após criação
- extra: Controla o comportamento para campos extras ('allow', 'forbid', 'ignore')
- populate_by_name: Permite популяция por nome do campo ou alias
🌐 Integração com FastAPI
O FastAPI é um dos frameworks web mais populares do Python moderno, e sua integração com o Pydantic é absolutamente perfeita. Na verdade, o FastAPI usa o Pydantic como base para validação de dados em requisições:
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UsuarioCreate(BaseModel):
username: str
email: EmailStr
senha: str
@app.post("/usuarios")
async def criar_usuario(usuario: UsuarioCreate):
return {"mensagem": "Usuário criado", "dados": usuario}A documentação oficial do FastAPI demonstra como essa integração simplifica drasticamente a criação de APIs robustas.
Quando você define seus modelos Pydantic como parâmetros de endpoint, o FastAPI automaticamente:
- Valida os dados recebidos
- Gera documentação automática
- Converte os dados para o tipo correto
- Retorna erros claros se a validação falhar
💾 Pydantic Settings
Para aplicações que precisam de configurações de ambiente, o pydantic-settings é a solução ideal:
from pydantic_settings import BaseSettings
from typing import Optional
class Configuracoes(BaseSettings):
nome_app: str = "Minha Aplicação"
debug: bool = False
banco_dados_url: str
secret_key: str
class Config:
env_file = ".env"
env_file_encoding = "utf-8"
# Uso
config = Configuracoes()
print(config.banco_dados_url)A documentação do pydantic-settings detalha todas as opções disponíveis.
🚀 Boas Práticas
Para usar o Pydantic de forma eficaz em seus projetos, considere estas boas práticas:
1. Organize seus modelos em módulos separados
Para projetos grandes, crie arquivos dedicados para seus modelos. Isso facilita a manutenção e o reaproveitamento.
2. Use nomes descritivos
Nomes como UsuarioCreate, UsuarioResponse, ProdutoUpdate são muito mais claros do que apenas Usuario ou Produto.
3. Documente seus modelos
Use docstrings para explicar o propósito de cada modelo e campo:
class Pedido(BaseModel):
"""Representa um pedido de compra."""
itens: list[str]
"""Lista de itens do pedido."""
total: float
"""Valor total do pedido em reais."""4. Valide apenas o necessário
Não exagerar nas validações. Valide o suficiente para garantir integridade, mas deixe flexibilidade para mudanças.
5. Use Tipos Customizados
Crie seus próprios tipos para validações específicas do domínio:
from pydantic import AfterValidator
from typing import Annotated
CPF = Annotated[str, AfterValidator(validar_cpf_formatado)]
CNPJ = Annotated[str, AfterValidator(validar_cnpj_formatado)]📚 Conclusão
O Pydantic transformou fundamentalmente a forma como lidamos com validação de dados em Python. Sua sintaxe intuitiva baseada em type hints, validação automática robusta, e capacidades de serialização o tornam uma ferramenta indispensável para desenvolvedores que buscam código mais seguro e mantenível.
Se você está trabalhando com FastAPI, criando APIs, processando dados externos, ou qualquer aplicação que receba dados não confiáveis, o Pydantic deve ser sua primeira escolha. A curva de aprendizado é suave para quem já conhece type hints do Python, e os benefícios em termos de qualidade de código e redução de bugs são imediatos.
Para continuar aprendendo, explore a documentação oficial do Pydantic, que contém exemplos avançados e casos de uso específicos. Você também pode conferir recursos adicionais como o tutorial do Podcast __init__ sobre Pydantic e FastAPI.
Dominar Pydantic é um investimento que vai se pagar rapidamente em projetos mais robustos e com menos bugs relacionados a dados inválidos.