Introdução ao Pydantic: Validação e Modelagem de Dados Simplificada com Python

✅ Artigo atualizado em Setembro 2026 Todos os exemplos foram executados no Pydantic 2.13; o caso prático migrou de @validator (API V1, obsoleta) para @field_validator e as saídas de erro são as reais do V2.

Salve salve Pythonista

A validação e modelagem de dados são aspectos importantes no desenvolvimento de qualquer aplicação em Python.

O Pydantic surge como uma ferramenta poderosa para lidar com isso de maneira eficiente.

Neste artigo, exploraremos o que é o Pydantic, como ele pode ajudar na validação automática de tipos, na manipulação de dados válidos e inválidos, e como ele facilita a serialização e desserialização de dados em JSON.

Com seu foco na simplicidade e robustez, o Pydantic pode ser um diferencial no seu projeto.

Vá Direto ao Assunto…

• O que é o Pydantic e por que utilizá-lo?
• Instalação e configuração inicial
• Introdução aos modelos básicos (BaseModel)
• Validação automática de tipos com Pydantic
• Trabalhando com dados válidos e inválidos
• Serialização e desserialização de dados em JSON
• Caso Prático: Validação de API Request

O que é o Pydantic e por que utilizá-lo?

Pydantic é uma biblioteca de modelagem e validação de dados para Python.

Ao trabalhar com dados, é comum a necessidade de garantir que eles estejam no formato e tipo corretos.

Pydantic simplifica essa tarefa com uma sintaxe clara e intuitiva!

Seus principais benefícios incluem a validação automática de tipos, a capacidade de converter tipos complexos com facilidade e a possibilidade de gerar dados confiáveis de fontes não confiáveis, como entradas de usuário.

Quando usar o Pydantic?

Use o Pydantic quando precisar garantir que dados estejam consistentes e seguros, especialmente em APIs, configurações, ou qualquer situação em que entradas externas sejam processadas.

Instalação e configuração inicial

Para começar a usar o Pydantic, você precisa instalá-lo em seu ambiente Python. Isso pode ser feito facilmente com o gerenciador de pacotes pip:

1

pip install pydantic

Após a instalação, você pode importar suas funcionalidades em seu projeto e começar a aproveitar seus benefícios.

Criei o Ebookr.ai, uma plataforma que usa IA para gerar ebooks profissionais sobre qualquer tema - com capa gerada por IA, infográficos automáticos e exportação em PDF. Confere!

Introdução aos modelos básicos (BaseModel)

O coração do Pydantic é a classe BaseModel, que serve como ponto de partida para definir a estrutura dos seus dados. Vamos começar criando um exemplo básico de modelo:

1
2
3
4
5
6

from pydantic import BaseModel

class Usuario(BaseModel):
    nome: str
    idade: int
    email: str

Explicação do código:

1. Importação: Importamos a classe BaseModel do Pydantic.
2. Definição de Classe: Criamos a classe Usuario que herda de BaseModel.
3. Atributos do Modelo: Definimos os atributos nome, idade e email, especificando seus tipos.

Ao definir os tipos de dados, garantimos que o Pydantic valide automaticamente as entradas, reduzindo erros e melhorando a confiabilidade da aplicação.

Validação automática de tipos com Pydantic

A magia do Pydantic reside na sua capacidade de validar automaticamente o tipo de dados.

Vamos testar isso criando uma instância de Usuario com dados corretos e incorretos:

1
2
3
4
5
6
7
8
9

from pydantic import ValidationError

usuario_valido = Usuario(nome="João", idade=30, email="[email protected]")
print(usuario_valido)

try:
    usuario_invalido = Usuario(nome="Maria", idade="trinta", email="[email protected]")
except ValidationError as e:
    print(f"Erro de validação: {e}")

E a saída será:

1
2
3
4
5

nome='João' idade=30 email='[email protected]'
Erro de validação: 1 validation error for Usuario
idade
  Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='trinta', input_type=str]
    For further information visit https://errors.pydantic.dev/2.13/v/int_parsing

Explicação do código:

1. Instância Válida: Criamos um usuario_valido com os tipos corretos de dados para cada atributo.
2. Instância Inválida: Tentamos criar um usuario_invalido com um tipo de dado incorreto para idade.
3. Captura de Erro: O Pydantic lança um ValidationError (subclasse de ValueError, por isso except ValueError também funcionaria) ao encontrar um tipo incorreto, que capturamos e imprimimos.

A mensagem do V2 traz, para cada campo, o tipo do erro (int_parsing), o valor recebido e um link para a documentação do erro. O número no link (2.13) é a versão do Pydantic instalada, então ele muda conforme a sua versão.

A capacidade do Pydantic em lidar com erros automaticamente é uma de suas características mais poderosas, ajudando a manter a integridade dos dados em sua aplicação.

Trabalhando com dados válidos e inválidos

Quando trabalhamos com dados, é comum encontrar entradas inválidas. O Pydantic fornece ferramentas para facilitar a manipulação desses casos. Vamos ver como ele trata entradas válidas e inválidas.

Dados válidos

Com o Pydantic, você pode contar com a conversão automática de tipos quando possível. Veja como:

1
2

usuario = Usuario(nome="Ana", idade="25", email="[email protected]")
print(usuario)

E a saída será:

1

nome='Ana' idade=25 email='[email protected]'

Explicação do código:

1. Conversão de Tipos: Embora idade seja uma string, o Pydantic converte para int quando possível.

Dados inválidos

Quando a conversão automática falha, o Pydantic lança um erro. Vamos ilustrar isso:

1
2
3
4

try:
    usuario = Usuario(nome=123, idade=25.5, email=None)
except ValidationError as e:
    print(f"Erro de validação: {e}")

E a saída será:

1
2
3
4
5
6
7
8
9
10

Erro de validação: 3 validation errors for Usuario
nome
  Input should be a valid string [type=string_type, input_value=123, input_type=int]
    For further information visit https://errors.pydantic.dev/2.13/v/string_type
idade
  Input should be a valid integer, got a number with a fractional part [type=int_from_float, input_value=25.5, input_type=float]
    For further information visit https://errors.pydantic.dev/2.13/v/int_from_float
email
  Input should be a valid string [type=string_type, input_value=None, input_type=NoneType]
    For further information visit https://errors.pydantic.dev/2.13/v/string_type

Explicação do código:

1. Erro de Tipos: Passamos tipos errados que o Pydantic não pode converter automaticamente.
2. Exceção Capturada: Um único ValidationError é lançado listando os três erros de uma vez (o Pydantic não para no primeiro campo inválido).
3. Sem coerção “frouxa”: repare que o Pydantic V2 não converte 123 para "123" nem trunca 25.5 para 25; no modo padrão (lax) ele só converte quando não há perda de informação, como "25" para 25.

Antes de continuar… Está curtindo esse conteúdo?

Que tal receber 30 dias de conteúdo direto na sua Caixa de Entrada?

Sua assinatura não pôde ser validada.

Você fez sua assinatura com sucesso.

Assine as PyDicas e receba 30 dias do melhor conteúdo Python na sua Caixa de Entrada: direto e sem enrolação!

Seu nome

Seu e-mail

ASSINAR PYDICAS

Serialização e desserialização de dados em JSON

Uma das funcionalidades mais práticas do Pydantic é a fácil conversão entre modelos e JSON, essencial para aplicações web.

Serialização

A partir de um modelo Pydantic, podemos facilmente serializá-lo em JSON:

1
2
3

usuario = Usuario(nome="Carlos", idade=40, email="[email protected]")
usuario_json = usuario.model_dump_json()
print(usuario_json)

E a saída será:

1

{"nome":"Carlos","idade":40,"email":"[email protected]"}

Explicação do código:

1. Método JSON: Usamos o método model_dump_json() da instância Usuario para serializá-la.
2. Formato JSON: A saída é uma string JSON representando o modelo.

Desserialização

Da mesma forma, podemos criar um modelo a partir de uma string JSON:

1
2
3

dados_json = '{"nome": "Luiza", "idade": 22, "email": "[email protected]"}'
usuario = Usuario.model_validate_json(dados_json)
print(usuario)

E a saída será:

1

nome='Luiza' idade=22 email='[email protected]'

Explicação do código:

1. Método model_validate_json: model_validate_json() (que substitui o antigo parse_raw() do V1) desserializa a string JSON para uma instância de Usuario.
2. Objeto Python: usuario agora é um objeto Usuario com os dados do JSON.

Pydantic resolve validação, mas a base por trás - POO, tipos, tratamento de erro - é o que você constrói estudando Python a fundo. É exatamente essa fundação que a Jornada Python entrega, do básico ao Django:

Domine Python: A Linguagem da Inteligência Artificial, do Desenvolvimento Web e das Carreiras do Futuro.

A mais completa formação para você se tornar um especialista em Python, pronto para construir desde aplicações web robustas com Django até projetos de Inteligência Artificial e Ciência de Dados .

Quero conhecer!

Nota 4,9 de 5 na Hotmart O curso de Python mais bem avaliado da Hotmart!

Caso Prático: Validação de API Request

Este exemplo usa EmailStr, que depende do pacote email-validator, e o FastAPI. Instale com pip install "pydantic[email]" fastapi.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

from pydantic import BaseModel, EmailStr, Field, field_validator
from typing import Optional
import re

class CriarUsuarioRequest(BaseModel):
    nome: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    senha: str = Field(..., min_length=8)
    idade: int = Field(..., gt=0, lt=150)
    telefone: Optional[str] = None

    @field_validator('senha')
    @classmethod
    def validar_senha_forte(cls, v: str) -> str:
        if not re.search(r'[A-Z]', v):
            raise ValueError('Senha deve ter maiúscula')
        if not re.search(r'[0-9]', v):
            raise ValueError('Senha deve ter número')
        return v

    @field_validator('telefone')
    @classmethod
    def validar_telefone(cls, v: Optional[str]) -> Optional[str]:
        if v and not re.match(r'^\(\d{2}\) \d{5}-\d{4}$', v):
            raise ValueError('Formato: (11) 99999-9999')
        return v

# Uso em API FastAPI
from fastapi import FastAPI

app = FastAPI()

@app.post("/usuarios")
def criar_usuario(usuario: CriarUsuarioRequest):
    # Pydantic valida automaticamente!
    return {"mensagem": f"Usuário {usuario.nome} criado"}

No Pydantic V2, validadores de campo usam @field_validator junto com @classmethod. O antigo @validator do V1 ainda existe só por compatibilidade: gera um aviso de depreciação e será removido no V3.

Testando o modelo fora da API com uma senha sem maiúscula e um telefone fora do padrão:

1
2
3
4
5
6
7
8
9
10
11
12

from pydantic import ValidationError

try:
    CriarUsuarioRequest(
        nome="Ana",
        email="[email protected]",
        senha="senhafraca1",
        idade=28,
        telefone="11999999999",
    )
except ValidationError as e:
    print(e)

E a saída será:

1
2
3
4
5
6
7

2 validation errors for CriarUsuarioRequest
senha
  Value error, Senha deve ter maiúscula [type=value_error, input_value='senhafraca1', input_type=str]
    For further information visit https://errors.pydantic.dev/2.13/v/value_error
telefone
  Value error, Formato: (11) 99999-9999 [type=value_error, input_value='11999999999', input_type=str]
    For further information visit https://errors.pydantic.dev/2.13/v/value_error

Na rota do FastAPI, o mesmo erro vira automaticamente uma resposta HTTP 422 com a lista de erros no corpo, sem nenhum try/except no seu código.

Conclusão

Neste guia sobre Pydantic, você aprendeu:

✅ Instalação - Setup do Pydantic V2
✅ BaseModel - Criar modelos de dados tipados
✅ Validação automática - Tipos checados automaticamente
✅ Validators - Regras de validação customizadas
✅ JSON - Serialização e desserialização
✅ Caso prático - Validação de API request

Principais lições:

• Pydantic valida automaticamente tipos de dados
• Núcleo em Rust: segundo o anúncio oficial do V2, cerca de 17x mais rápido que o V1 ao validar um modelo com campos comuns (entre 4x e 50x, conforme o benchmark)
• Ideal para APIs (FastAPI usa Pydantic)
• Validators para regras complexas
• Serializa/desserializa JSON facilmente

Próximos passos:

• Aprenda sobre Modelos complexos
• Explore Tipos avançados
• Use com FastAPI para APIs robustas

Quer uma base de Python sólida, de POO a APIs REST com Django, em uma trilha completa do zero ao avançado? Conheça a Jornada Python, nosso curso de Python completo.

Por Vinícius Ramos em 18/01/2025

Engenheiro de Computação pela UnB com especialização em Inteligência Artificial. Sr. Software Engineer com 10+ anos de experiência desenvolvendo sistemas críticos em Python e Django. Atuei no Banco do Brasil liderando equipes para monitoramento de mainframe, trabalhei como desenvolvedor sênior em projetos forenses para a Polícia Federal, e atualmente sou engenheiro de software na Labcorp (Estados Unidos), desenvolvendo soluções escaláveis para testes genéticos. Fundador da Python Academy, compartilhando conhecimento técnico com a comunidade brasileira desde 2018.

Bora se conectar no LinkedIn! vinicius-aramos

Minhas redes:

• 
• 
•