Comparador de Registros é uma ferramenta Python focada em deduplicação e vinculação probabilística de bases cadastrais – especialmente em contextos de saúde pública, assistência social e cadastros massivos – onde inconsistências de grafia, abreviações e datas trocadas comprometem a análise de dados.
Motivações principais
- Reduzir falsos negativos ao comparar registros que parecem diferentes, mas representam a mesma pessoa.
- Tornar reprodutível um processo que antes dependia de planilhas manuais e macros difíceis de manter.
- Oferecer resultados rastreáveis, com pontuação explicável e colunas auxiliares que justificam cada nota.
Funcionalidades de destaque
- Interface gráfica interativa (Tkinter) com barra de progresso, escolha de separador, número de núcleos e mapeamento rápido das colunas relevantes.
- Comparadores especializados para nomes, datas, localidades, logradouros e campos textuais, aproveitando bibliotecas otimizadas (RapidFuzz, python-Levenshtein, Jellyfish) com fallback automático para ambientes restritos.
- Cache e construção incremental de frequências, permitindo reaproveitar estatísticas de grandes bases e acelerar execuções subsequentes.
- Suíte completa de testes (unitária, integração e funcional) e pipeline GitHub Actions que executa
pytest, calcula cobertura e empacota executáveis multiplataforma com PyInstaller.
🗂️ Estrutura do repositório (resumo)
src/ ├─ gui.py # Interface Tk ├─ comparaRegistros.py # Núcleo de pontuação ├─ freqBuilder.py # Construção e cache de tabelas de frequência ├─ util.py # Normalização, Soundex e distâncias ├─ comparators/ # Comparadores especializados ├─ transformabase.py # Conversão de bases legadas └─ ... tests/ ├─ unit/ # Testes de unidade ├─ functional/ # Fluxos completos usando CSVs reais └─ integration/ # Testes entre módulos principais .github/workflows/ # Pipeline CI (testes + build + release) requirements.txt # Dependências pinadas (pip freeze) README.md # Este guia LICENSE # GPL-3.0
| Item | Versão sugerida | Observação |
|---|---|---|
| Python | 3.11 ou superior | CI oficial roda em 3.11; localmente testado até 3.13 |
| pip | Última versão | python -m pip install --upgrade pip |
| Git | Opcional | Facilita baixar e atualizar o repositório |
Tkinter acompanha as distribuições oficiais do Python (Windows/macOS). Em Linux Debian/Ubuntu instale com apt install python3-tk.
git clone https://github.com/marco-jardim/Comparador-de-Registros.git
cd Comparador-de-RegistrosAlternativa: baixe o ZIP pelo botão Code ▾ ➜ Download ZIP e extraia.
python -m venv .venv
# Ativar (Windows PowerShell)
.venv\Scripts\Activate.ps1
# Ativar (Linux/macOS/Git Bash)
source .venv/bin/activateFinalize com deactivate quando quiser sair do ambiente virtual.
(.venv) pip install --upgrade pip
(.venv) pip install -r requirements.txtℹ️ O arquivo
requirements.txtlista apenas as dependências realmente usadas pelo projeto (pandas, RapidFuzz, python-Levenshtein, Jellyfish, Unidecode e pytest). Outras bibliotecas de suporte são dependências transitivas instaladas automaticamente pelopip.
Caso esteja em um ambiente com restrições e deseje o mínimo essencial, instale manualmente pandas, RapidFuzz, python-Levenshtein, Unidecode e jellyfish. O código faz fallback para implementações Python puras quando esses aceleradores não estiverem disponíveis, porém com processamento mais lento.
A suíte de testes usa pytest e cobre cenários de unidade, integração e fluxo completo.
(.venv) pytest --cov=src --cov-report=term-missing
(.venv) pytest tests/unit # apenas unitários
(.venv) pytest -k nomes # filtra por expressãoOs testes são executados automaticamente no GitHub Actions antes de cada build e o relatório de cobertura é enviado ao Codecov. É altamente recomendado rodá-los localmente antes de abrir um Pull Request ou gerar executáveis.
(.venv) python src/gui.py- Abrir CSV → clique em Abrir e selecione o arquivo de entrada.
- Configurar colunas → ajuste as letras das colunas nos comboboxes se o layout não for o padrão.
- Comparar → clique em Comparar para iniciar o processamento. A barra de progresso mostra o andamento e, ao final,
saida.csvé criado com o mesmo separador do arquivo original.
O resultado é ordenado pela nota final (decrescente). Alterar o critério de ordenação antes de iniciar reflete imediatamente no arquivo gerado.
| Coluna | Campo |
|---|---|
| J | Nome 1 |
| K | Nome da mãe 1 |
| L | Data de nascimento 1 |
| N | Nome 2 |
| O | Nome da mãe 2 |
| P | Data de nascimento 2 |
Se os nomes das colunas forem simples (sem prefixos do OpenRecLink), desmarque Formato OpenRecLink antes de abrir o arquivo. O separador padrão é vírgula (,); no modo OpenRecLink é pipe (|). Ambos podem ser alterados no campo Separador.
A caixa Núcleos define quantos processadores serão utilizados para paralelizar a comparação. O valor inicial corresponde a 75 % dos núcleos disponíveis, mas você pode aumentar ou reduzir conforme o hardware.
Para executar sem interface gráfica:
(.venv) python -m src.comparaRegistros path/entrada.csv saida --idx 9 10 11 13 14 15O parâmetro --idx recebe os seis índices (0-based) referentes aos campos Nome1, Mãe1, Data1, Nome2, Mãe2, Data2. Consulte python -m src.comparaRegistros --help para ver todas as opções disponíveis.
Na primeira execução, o sistema cria a pasta .freq_cache/ processando o CSV em blocos de aproximadamente 500 mil linhas. Se a base for atualizada ou o cache ficar obsoleto, basta removê-lo:
rm -r .freq_cacheO diretório será reconstruído automaticamente em uma nova execução.
| Problema / Mensagem | Causa provável | Como resolver |
|---|---|---|
ModuleNotFoundError: pandas |
Ambiente virtual não ativado | Rode o comando de ativação do venv e reinstale as dependências |
| GUI abre mas congela sem barra de progresso | Script incorreto foi executado | Utilize python src/gui.py em vez de chamar módulos internos |
| Notas muito diferentes das versões antigas | Tabelas de frequência desatualizadas | Exclua .freq_cache/ para reconstruir com a base atual |
| RapidFuzz/python-Levenshtein não instala (ambiente ARM) | Sem wheels pré-compiladas | A aplicação funciona com fallback Python puro, porém mais lento |
Erros com vírgula decimal (ValueError: could not parse) |
Dados com 2,00 ou similar |
Versões atuais normalizam automaticamente; garanta estar na branch main |
- O workflow
build-release.ymlroda em todo push paramaine quando PRs são mesclados. - As etapas seguem a ordem prepare-version ➜ tests ➜ build ➜ release: o build só começa se toda a suíte
pytestpassar. - Executáveis são empacotados com PyInstaller para Windows, macOS e Linux e publicados como artefatos.
Para gerar manualmente um executável local (exemplo em Windows, com venv ativo):
(.venv) pyinstaller --noconfirm --onefile --add-data "version.env;." src/gui.pyEm sistemas Unix-like substitua ; por : dentro do argumento --add-data. O arquivo version.env é criado automaticamente no pipeline; para gerar manualmente em desenvolvimento, crie o arquivo com o conteúdo:
APP_VERSION=0.0-dev
APP_VERSION_DATE=2025-09-26
Substitua pelos valores desejados (por exemplo, usando a data atual). Executar o workflow no GitHub também produz o version.env correto como parte dos artefatos.
- Abra uma issue para discutir mudanças maiores (ex.: novos formatos de entrada, integrações externas).
- Crie um branch dedicado.
- Rode
pytestantes do commit final para garantir que a suíte continue verde. - Abra o Pull Request seguindo o estilo PEP 8 e descrevendo o impacto da alteração.
Contribuições pequenas (refactors, documentação, traduções) também são muito bem-vindas.
Distribuído sob a GNU General Public License v3.0. Consulte o arquivo LICENSE para detalhes completos.