WolfzBR

Limpeza de planilhas brasileiras com receitas reproduzíveis. Você arrasta a planilha suja (título, cabeçalho no meio, totais, 1.234,56, R$, datas 31/12/2024), ajusta os passos na tela e exporta a tabela limpa junto com a receita: o mesmo passo a passo em Power Query M e em script Python, para refazer no mês seguinte.

Tudo roda na sua máquina. Nenhum dado sai do seu computador.

Status: pré-alfa (0.6). O formato da receita ainda pode mudar até a 1.0.

Instalação

Requer Python 3.12 ou mais novo. Recomendado com pipx, que isola o WolfzBR num ambiente próprio:

pipx install wolfzbr

ou com pip, num ambiente virtual:

pip install wolfzbr

O pacote já traz a interface compilada; não precisa de Node.

Uso

Interface

wolfz ui

Abre o navegador com a interface. Para usar:

1. Arraste o arquivo (.xlsx, .xls, .ods ou .csv). Se tiver mais de uma aba, escolha qual.
2. Confira a estrutura detectada: título, cabeçalho, dados, totais e rodapé aparecem em cores. Se a área estiver errada, clique e arraste na grade para marcar a certa.
3. Ajuste a receita: adicione, edite, reordene ou desative passos, vendo a tabela antes e depois de cada um. Clique no cabeçalho de uma coluna para ver o perfil dela.
4. Exporte: CSV (pronto para o Excel em português), Excel, Parquet, Power Query M e script Python.

A receita é salva automaticamente a cada edição. O endereço só funciona com a chave de acesso que o terminal mostra, nova a cada execução. Deixe o terminal aberto enquanto usa; Ctrl+C encerra.

Opções: --port fixa a porta; --no-browser só mostra o endereço, sem abrir o navegador.

Linha de comando

Aplicar uma receita salva ao arquivo do mês seguinte:

wolfz run vendas.wolfz.json vendas_fevereiro.xlsx -o saida/ --format xlsx

• Se algum passo não se aplicar ao arquivo novo (uma coluna mudou de nome, por exemplo), nada é gravado e a mensagem diz qual passo falhou e quais colunas existem.
• Se a aba muda de nome todo mês (Vendas 2024 → Vendas 2025), use source.match.sheet_name_regex na receita.

Outros comandos:

wolfz inspect planilha.xlsx      # perfil das colunas no terminal
wolfz schema                     # JSON Schema da receita
wolfz --help

Códigos de saída do run: 0 ok · 1 um passo falhou · 2 receita inválida ou uso incorreto · 3 arquivo ilegível.

Em Python

import wolfz

df = wolfz.run("vendas.wolfz.json", "vendas_fevereiro.xlsx")  # polars.DataFrame

Exportação

Tableau (.hyper) e projeto do Power BI (.pbip) estão previstos para versões futuras.

Padrões brasileiros

O catálogo tem 39 operações: estrutura (área, cabeçalho, linhas e colunas vazias, preencher para baixo, despivotar), colunas, texto e padrões brasileiros. Os padrões cobrem:

• números (1.234,56, (1,5), 10- do SAP, R$) e a escala da unidade ("Mil Reais");
• valores do IBGE com os sinais -, .., ... e X, sem virar zero o que não é zero;
• percentual, datas e mês/ano;
• sim/não;
• CPF, CNPJ (inclusive o alfanumérico), coluna com CPF ou CNPJ, CEP, telefone e UF;
• município e UF no mesmo campo ("Vitória - ES");
• município do IBGE: casa o nome digitado com a lista oficial (exato, abreviação como "V. Velha" e parecido), com o código de 7 dígitos. O que não casa com segurança fica para você revisar na tela; nada é trocado em silêncio;
• acento estragado (São Paulo) e marca de nota de rodapé (Abacaxi*).

Cada operação tem a mesma regra no motor (Polars), no M e no script Python, com teste de equivalência. A exceção é o casamento de municípios por semelhança, que o M não sabe fazer: a exportação leva junto a tabela de-para (depara_municipios.csv) e o M e o script fazem a ligação exata com ela.

A lista de municípios vem da API de localidades do IBGE e fica dentro do pacote (funciona sem internet); fonte e data no NOTICE.

Limites

• Arquivo de até 100 MB.
• Uma tabela por aba. Duas tabelas na mesma aba: marque a área de cada uma em projetos separados.
• Cabeçalho em várias linhas é juntado num nome só, mas o cabeçalho mesclado na horizontal ainda não é preenchido. Isso chega na 0.6.

Documentação

• Desenho técnico: docs/system_design.md
• Mudanças: CHANGELOG.md
• Como contribuir: CONTRIBUTING.md

Licença

MIT