Pandera com Python: Validação de Dados em Pipelines

Validar dados é uma das diferenças mais visíveis entre um script Python que funciona uma vez e um pipeline que aguenta uso real. Em projetos de análise, automação, BI, CRM, finanças, dados públicos ou engenharia de dados, o erro raramente aparece como uma exceção bonita. Ele costuma chegar como coluna ausente, data em formato estranho, valor negativo onde não deveria, categoria nova sem mapeamento, CPF vazio, preço como texto ou arquivo CSV exportado com separador diferente.

O problema é que muita gente só percebe isso no fim: o dashboard mostra número errado, o relatório fecha com total impossível, a automação envia mensagem para o cliente errado ou o notebook quebra em uma linha distante da causa original. Para evitar esse tipo de falha, vale tratar dados como contrato. Se a entrada prometeu ter determinadas colunas, tipos e regras, o código deve verificar isso cedo e falhar com mensagem útil.

É aí que entra o Pandera, uma biblioteca para validar DataFrames em Python. Ela funciona muito bem com Pandas, conversa com fluxos de ETL com Python, ajuda em projetos de APIs públicas brasileiras e deixa seu portfólio mais profissional porque mostra preocupação com qualidade, não apenas com gráfico bonito.

Neste guia, vamos criar contratos de dados com Pandera, validar CSVs, integrar com pytest, organizar erros e mostrar como usar isso em projetos brasileiros de dados. A ideia não é adicionar burocracia: é colocar uma proteção pequena no ponto em que ela economiza horas de investigação.

Quando usar Pandera

Use Pandera quando você tem DataFrames que precisam seguir regras explícitas. Alguns exemplos comuns:

Sem validação, você espalha if, dropna, conversões silenciosas e suposições pelo código. Com Pandera, essas regras ficam concentradas em um schema. Isso facilita revisão, testes e manutenção.

Pandera não substitui limpeza de dados. Ele diz se a tabela está dentro do contrato esperado. Se não estiver, você decide se corrige, rejeita, registra em quarentena ou pede nova exportação.

Preparando o ambiente

Crie um projeto pequeno:

python -m venv .venv
source .venv/bin/activate

pip install pandas pandera pytest

Com uv, o fluxo fica mais rápido:

uv init validacao-dados-python
cd validacao-dados-python
uv add pandas pandera
uv add --dev pytest

Se você ainda está organizando ambientes e dependências, veja também ambientes virtuais em Python e uv como gerenciador de pacotes. Para projetos de dados, reprodutibilidade é parte da qualidade: outra pessoa precisa conseguir rodar a validação sem adivinhar versões.

Um CSV de vendas com problemas reais

Imagine que uma área comercial exporta este arquivo vendas.csv toda manhã:

pedido_id,cliente,uf,data_pedido,valor,status
1001,Ana Silva,SP,2026-05-01,129.90,pago
1002,Bruno Lima,RJ,2026-05-02,0,cancelado
1003,Carla Souza,MG,2026-05-03,89.50,pago

O pipeline parece simples: ler o CSV, somar vendas pagas por UF e gerar um relatório. Mas quais regras estão implícitas?

• pedido_id deve existir e ser único;
• uf deve ter duas letras;
• data_pedido precisa virar data;
• valor não pode ser negativo;
• status só pode ter valores conhecidos.

Vamos escrever isso como contrato.

Criando o primeiro schema

Crie schemas.py:

import pandera as pa
from pandera import Check, Column, DataFrameSchema


schema_vendas = DataFrameSchema(
    {
        "pedido_id": Column(int, unique=True),
        "cliente": Column(str, nullable=False),
        "uf": Column(str, Check.str_length(2, 2)),
        "data_pedido": Column(pa.DateTime),
        "valor": Column(float, Check.ge(0)),
        "status": Column(str, Check.isin(["pago", "pendente", "cancelado"])),
    },
    strict=True,
    coerce=True,
)

Alguns detalhes importam:

• strict=True rejeita colunas inesperadas;
• coerce=True tenta converter tipos antes de validar;
• nullable=False impede valores ausentes em campos críticos;
• Check.ge(0) garante valor maior ou igual a zero;
• Check.isin(...) limita categorias aceitas.

Essa estrutura já documenta o formato da tabela melhor do que um comentário solto. Se alguém adicionar a coluna desconto sem combinar com o pipeline, a validação falha. Se um status novo aparecer, você descobre cedo e atualiza a regra conscientemente.

Validando um arquivo no pipeline

Agora crie pipeline.py:

import pandas as pd

from schemas import schema_vendas


def carregar_vendas(caminho: str) -> pd.DataFrame:
    df = pd.read_csv(caminho)
    return schema_vendas.validate(df)


def vendas_pagas_por_uf(df: pd.DataFrame) -> pd.DataFrame:
    pagas = df[df["status"] == "pago"]
    return (
        pagas.groupby("uf", as_index=False)["valor"]
        .sum()
        .sort_values("valor", ascending=False)
    )


if __name__ == "__main__":
    vendas = carregar_vendas("vendas.csv")
    relatorio = vendas_pagas_por_uf(vendas)
    print(relatorio)

O ponto principal é validar logo depois da leitura. Evite deixar a validação para o fim do pipeline, porque o dado ruim pode contaminar transformações intermediárias e gerar erro confuso.

Se o CSV vier com valor como texto numérico, coerce=True tenta converter para float. Se vier com valor como "cento e vinte", a validação falha. Isso é bom: continuar com dado impossível seria pior.

Entendendo erros de validação

Vamos simular um arquivo problemático:

pedido_id,cliente,uf,data_pedido,valor,status
1001,Ana Silva,SP,2026-05-01,129.90,pago
1001,Bruno Lima,Rio,2026-05-02,-20.00,reembolsado

Ele tem pedido_id duplicado, UF com três letras, valor negativo e status fora da lista. Ao validar, Pandera gera uma exceção com detalhes. Em pipelines de produção, você pode capturar essa exceção para registrar evidência:

import pandera as pa


def validar_arquivo(caminho: str):
    df = pd.read_csv(caminho)
    try:
        return schema_vendas.validate(df, lazy=True)
    except pa.errors.SchemaErrors as erro:
        print("Arquivo rejeitado pela validação")
        print(erro.failure_cases.head(20))
        raise

O argumento lazy=True é útil porque coleta várias falhas de uma vez. Sem ele, o Pandera pode parar na primeira regra quebrada. Para times de dados, mostrar todos os problemas encontrados costuma acelerar a correção do arquivo de origem.

Integrando com pytest

Validação de dados também merece teste automatizado. Crie tests/test_schemas.py:

import pandas as pd
import pandera as pa
import pytest

from schemas import schema_vendas


def test_schema_vendas_aceita_dados_validos():
    df = pd.DataFrame(
        {
            "pedido_id": [1, 2],
            "cliente": ["Ana", "Bruno"],
            "uf": ["SP", "RJ"],
            "data_pedido": ["2026-05-01", "2026-05-02"],
            "valor": [129.90, 59.00],
            "status": ["pago", "pendente"],
        }
    )

    validado = schema_vendas.validate(df)

    assert str(validado["data_pedido"].dtype).startswith("datetime64")


def test_schema_vendas_rejeita_valor_negativo():
    df = pd.DataFrame(
        {
            "pedido_id": [1],
            "cliente": ["Ana"],
            "uf": ["SP"],
            "data_pedido": ["2026-05-01"],
            "valor": [-10.0],
            "status": ["pago"],
        }
    )

    with pytest.raises(pa.errors.SchemaError):
        schema_vendas.validate(df)

Rode:

pytest -q

Esse teste parece pequeno, mas comunica maturidade em entrevista técnica. Você não está apenas dizendo “sei Pandas”; está mostrando que conhece contratos, casos inválidos e execução automatizada. Para reforçar essa base, veja testes com pytest e o checklist de teste técnico Python.

Validando dados de APIs públicas

Pandera também ajuda quando a origem é uma API. Imagine uma coleta de municípios do IBGE, inspirada no guia de APIs públicas brasileiras. Depois de normalizar a resposta, você pode exigir que a tabela tenha código, nome, UF e região:

schema_municipios = DataFrameSchema(
    {
        "municipio_id": Column(int, unique=True),
        "municipio": Column(str, nullable=False),
        "uf": Column(str, Check.str_length(2, 2)),
        "regiao": Column(str, Check.isin(["Norte", "Nordeste", "Centro-Oeste", "Sudeste", "Sul"])),
    },
    strict=True,
    coerce=True,
)

Esse tipo de contrato evita que uma mudança de payload passe despercebida. Se a API retornar campo renomeado, valor vazio ou região fora do padrão, o pipeline para antes de atualizar o relatório.

Em automações reais, você pode salvar os dados rejeitados em uma pasta data/quarentena/ com timestamp e registrar a causa em log. Isso é melhor do que sobrescrever a base boa com dados duvidosos.

Organizando schemas em projetos maiores

Quando o projeto cresce, não coloque todos os schemas no mesmo arquivo gigante. Uma estrutura simples funciona bem:

projeto-dados/
  src/
    coleta/
      ibge.py
      crm.py
    transformacao/
      vendas.py
    schemas/
      vendas.py
      municipios.py
      crm.py
    pipeline.py
  tests/
    test_schemas_vendas.py
    test_pipeline.py
  data/
    entrada/
    saida/
    quarentena/

Deixe schemas perto do domínio que eles validam. Um schema de vendas não é apenas detalhe técnico; ele representa uma regra de negócio. Por isso, nomes claros importam mais do que abstrações genéricas.

Para projetos de portfólio, inclua no README.md uma seção como:

• quais arquivos entram no pipeline;
• quais regras são validadas;
• como rodar pytest;
• o que acontece quando um arquivo é rejeitado;
• exemplos de erro e saída esperada.

Isso ajuda recrutadores e clientes a entenderem que o projeto foi pensado para uso real.

Pandera, Pydantic ou Great Expectations?

As três ferramentas aparecem em conversas sobre qualidade de dados, mas resolvem problemas diferentes.

Se você recebe JSON em uma API FastAPI, Pydantic costuma ser a primeira camada. Se depois transforma esse JSON em uma tabela com Pandas, Pandera pode validar o DataFrame resultante. Em times maiores, Great Expectations pode complementar com documentação de qualidade e relatórios para pessoas não técnicas.

Não comece complexo. Para a maioria dos projetos pequenos em Python, um schema Pandera bem escrito e alguns testes com pytest já resolvem muito.

Boas práticas

Algumas práticas evitam que a validação vire ruído:

1. Valide cedo, logo após leitura ou normalização.
2. Use strict=True quando colunas extras indicarem contrato quebrado.
3. Use coerce=True com cuidado e teste conversões importantes.
4. Prefira mensagens e logs que ajudem a corrigir a origem.
5. Separe dados rejeitados em quarentena, não apague silenciosamente.
6. Teste pelo menos um caso válido e um caso inválido por schema.
7. Documente regras no README, principalmente em projetos de portfólio.

Também vale alinhar validação com observabilidade. Um pipeline que registra quantas linhas entraram, quantas foram rejeitadas, quais regras falharam e onde o arquivo ficou salvo é muito mais fácil de operar. Se quiser aprofundar essa parte, veja logging em Python e OpenTelemetry com Python.

Ideias de projeto para portfólio

Pandera fica mais convincente quando aparece dentro de um projeto completo. Algumas ideias boas para o mercado brasileiro:

• validador de CSV de vendas para pequenas empresas;
• pipeline de dados públicos do IBGE com contrato por tabela;
• auditor de exportações de CRM antes de importar no sistema novo;
• preparação de dados financeiros com regras de valores e períodos;
• base de vagas Python com validação de senioridade, localidade e tecnologias;
• checador de planilhas recebidas por e-mail antes de gerar relatório.

O projeto não precisa ser enorme. Um repositório pequeno com src/, tests/, schemas, exemplos válidos e inválidos, CI rodando pytest e um README claro já mostra mais profissionalismo do que um notebook longo sem garantias.

Para vagas de engenharia de dados, analytics engineering, RevOps, QA de dados ou backend com integrações, esse tipo de evidência é forte. Muitas empresas brasileiras ainda convivem com planilhas, exports manuais e integrações frágeis. Saber proteger esse fluxo com Python é uma habilidade vendável.

Onde outras linguagens entram

Python é excelente para validação e transformação de dados porque tem Pandas, Pandera, Pydantic, pytest e uma comunidade enorme. Mas em arquiteturas mistas, nem todo componente precisa ser Python. Serviços de ingestão com muita concorrência, filas de alto volume e APIs de baixa latência podem ser implementados em Go, enquanto Python continua cuidando da validação, análise e automação. O importante é separar papéis: linguagem certa para cada parte do sistema.

Próximos passos

Para começar hoje, escolha um CSV real ou uma API simples e escreva um schema com cinco regras. Depois adicione um teste válido, um teste inválido e um comando claro no README. Só então evolua para logs, quarentena, dashboard ou agendamento.

Pandera não torna dados ruins magicamente bons. O que ela faz é impedir que dados ruins passem despercebidos. Em projetos profissionais, essa diferença vale muito: menos retrabalho, menos relatório errado, menos automação frágil e mais confiança para mudar o pipeline.

Se você já usa Pandas e está estudando ETL com Python, validação de dados é o próximo passo natural. Ela transforma scripts em sistemas pequenos, auditáveis e defendíveis em produção ou entrevista.