Data Validate

Sistema de validação e processamento de planilhas para a plataforma AdaptaBrasil


Testing Linux
Testing Windows
Coverage
Package
Meta

Built with the tools and technologies:

Data Validate é um validador e processador de planilhas robusto e multilíngue, desenvolvido especificamente para automatizar a checagem de integridade e estrutura de arquivos de dados da plataforma AdaptaBrasil. É especialmente útil para projetos que exigem padronização e validação rigorosa de dados tabulares, como pesquisas científicas, bancos de dados ambientais e sistemas de indicadores.

🚀 Características e protocolo de validação

Protocolo de Validação

O Data Validate implementa a especificação detalhada no protocolo de validação versão 1.13, que define regras claras para a estrutura e conteúdo das planilhas utilizadas na plataforma AdaptaBrasil.

Principais Funcionalidades

Validação Estrutural: Verifica estrutura de planilhas, nomes de colunas e organização
Validação de Conteúdo: Aplica regras de negócio específicas para cada tipo de planilha
Verificação Ortográfica: Sistema multilíngue de correção ortográfica com dicionários personalizados
Validação Hierárquica: Verifica relações entre indicadores e estruturas em árvore
Relatórios Detalhados: Gera relatórios HTML, PDF e logs detalhados de validação
Suporte Multilíngue: Suporte a internacionalização em português e inglês
Sistema de Logs: Logging detalhado para auditoria e debugging

Tecnologias Utilizadas

Python 3.12+: Linguagem principal
Pandas: Manipulação e análise de dados
PyEnchant: Verificação ortográfica
Calamine: Leitura de arquivos Excel
Babel: Internacionalização
PDFKit: Geração de relatórios PDF
Poetry: Gerenciamento de dependências

🏗️ Arquitetura

O projeto segue uma arquitetura modular baseada em padrões de design limpos:

📁 data_validate/
├── 🎛️ controllers/     # Orquestração e controle de fluxo
├── 📊 models/          # Modelos de dados para planilhas
├── ✅ validators/      # Lógica de validação
├── 🛠️ helpers/        # Utilitários e funções auxiliares
├── ⚙️ config/         # Configurações globais
├── 🔧 middleware/     # Camada de inicialização
└── 📄 static/         # Recursos estáticos (templates, dicionários)

Fluxo de Processamento

Inicialização: Bootstrap configura ambiente e dependências
Carregamento: Leitura e pré-processamento de planilhas
Validação: Execução sequencial de validadores especializados
Agregação: Coleta e organização de erros e avisos
Relatório: Geração de relatórios detalhados de saída

📦 Instalação

Pré-requisitos

Python 3.12 ou superior
Poetry para gerenciamento de dependências
Wkhtmltopdf (para geração de PDFs)

Instalação de Dependências de Sistema

GNU/LINUX

Certifique-se de que python-dev e wkhtmltopdf estejam instalados,

    # Instalando as dependências
    sudo apt install python3-dev wkhtmltopdf

Windows

Para instalar o wkhtmltopdf, baixe o instalador do site oficial: https://wkhtmltopdf.org/downloads.html Ou usando o chocolatey:

    choco install -y wkhtmltopdf

Instalação via PyPI

Crie um ambiente virtual (opcional, mas recomendado)

#  1.0 Crie e ative um ambiente virtual (opcional, mas recomendado)
python -m venv .venv

# 1.0 Ative o ambiente virtual
source .venv/bin/activate # No Linux/MacOS
.venv\Scripts\activate # No Windows

Instale o pacote via pip

pip install canoa-data-validate

Exemplo de uso após instalação via PyPI

canoa-data-validate --input_folder data/input --output_folder data/output --locale pt_BR --debug

Instalação via repositório GitHub

# 1.1 Clone o repositório
git clone https://github.com/AdaptaBrasil/data_validate.git
cd data_validate

#  1.2 Crie e ative um ambiente virtual (opcional, mas recomendado)
python -m venv .venv

# 1.3 Ative o ambiente virtual
source .venv/bin/activate # No Linux/MacOS
.venv\Scripts\activate # No Windows

# 2. Instale o Poetry (se necessário)
pip install poetry

# 3. Instale as dependências
poetry install

# 4. Ative o ambiente virtual
eval $(poetry env activate)

Comando completo

python -m data_validate.main --input_folder data/input --output_folder data/output --locale pt_BR --debug

Comando abreviado

python -m data_validate.main --i data/input --o data/output --l pt_BR --d


### Script de Pipeline

```bash
# Execução completa do pipeline
bash scripts/run_main_pipeline.sh

Modos de Execução

Modo Desenvolvimento (Recomendado)

# Com debug ativo e logs detalhados
python -m data_validate.main --input_folder data/input --debug

Modo Produção

# Sem logs, sem tempo, sem versão no relatório
python -m data_validate.main
    --input_folder data/input
    --output_folder data/output
    --no-time
    --no-version

Modo Rápido (sem verificação ortográfica e tamanhos de títulos)

# Para execuções rápidas, pulando spell check e avisos de comprimento de títulos
python -m data_validate.main
    --input_folder data/input
    --no-spellchecker
    --no-warning-titles-length

Parâmetros de Linha de Comando

Argumentos Principais

Parâmetro	Abreviação	Tipo	Descrição	Padrão	Obrigatório
`--input_folder`	`--i`	str	Caminho para a pasta de entrada com planilhas	-	✅
`--output_folder`	`--o`	str	Caminho para a pasta de saída dos relatórios	`output_data/`	❌
`--locale`	`-l`	str	Idioma da interface (pt_BR ou en_US)	`pt_BR`	❌

Argumentos de Ação

Parâmetro	Abreviação	Tipo	Descrição	Padrão
`--debug`	`--d`	flag	Ativa modo debug com logs detalhados	`False`
`--no-time`		flag	Oculta informações de tempo de execução	`False`
`--no-version`		flag	Oculta versão do script no relatório final	`False`
`--no-spellchecker`		flag	Desativa verificação ortográfica	`False`
`--no-warning-titles-length`		flag	Desativa avisos de comprimento de títulos	`False`

Argumentos de Relatório (Opcionais)

Parâmetro	Tipo	Descrição	Padrão
`--sector`	str	Nome do setor estratégico para o relatório	`None`
`--protocol`	str	Nome do protocolo para o relatório	`None`
`--user`	str	Nome do usuário para o relatório	`None`
`--file`	str	Nome específico do arquivo a ser analisado	`None`

Estrutura de Dados

Entrada (`data/input/`)

Coloque suas planilhas Excel (.xlsx) na pasta de entrada. O sistema processa:

sp_description.xlsx: Descrições e metadados dos indicadores
sp_value.xlsx: Valores dos indicadores
sp_scenario.xlsx: Cenários de análise
sp_temporal_reference.xlsx: Referências temporais
sp_composition.xlsx: Composições hierárquicas
sp_proportionality.xlsx: Proporções e relacionamentos
sp_legend.xlsx: Legendas e categorias
sp_dictionary.xlsx: Dicionários e vocabulários

Saída (`data/output/`)

O sistema gera:

Relatórios HTML: Visualização interativa dos resultados
Relatórios PDF: Geração de relatórios em formato PDF
Logs detalhados: Registros de execução e erros

✅ Validações Implementadas

Validação Estrutural

✅ Verificação de existência de arquivos obrigatórios
✅ Validação de nomes e ordem de colunas
✅ Checagem de tipos de dados esperados

Validação de Conteúdo

✅ Códigos sequenciais: Verificação de sequência numérica (1, 2, 3...)
✅ Valores únicos: Detecção de duplicatas em campos chave
✅ Relacionamentos: Validação de integridade referencial entre planilhas
✅ Níveis hierárquicos: Verificação de estruturas em árvore
✅ Cenários e temporalidade: Validação de combinações válidas

Validação de Formato

✅ Capitalização: Padronização de texto mantendo acrônimos
✅ Pontuação: Verificação de regras de pontuação específicas
✅ Caracteres especiais: Detecção de CR/LF e caracteres inválidos
✅ Comprimento de texto: Validação de limites de caracteres
✅ HTML: Detecção de tags HTML não permitidas

Validação Ortográfica

✅ Múltiplos idiomas: Suporte a pt_BR e en_US
✅ Dicionários personalizados: Termos técnicos e específicos do domínio
✅ Sugestões de correção: Recomendações automáticas

Validação de Dados

✅ Valores numéricos: Verificação de tipos e intervalos
✅ Casas decimais: Validação de precisão numérica
✅ Dados obrigatórios: Verificação de campos não vazios
✅ Combinações válidas: Validação de relacionamentos entre dados

📁 Estrutura do Projeto

data_validate/
├── 📊 assets/                    # Badges e recursos visuais
├── 📁 data/                      # Dados de entrada e saída
│   ├── input/                    # Planilhas para validação
│   └── output/                   # Relatórios e logs gerados
├── 🐍 data_validate/             # Código-fonte principal
│   ├── config/                   # Configurações globais
│   ├── controllers/              # Orquestração e controle
│   │   ├── context/              # Contextos de dados
│   │   └── report/               # Geração de relatórios
│   ├── helpers/                  # Utilitários e funções auxiliares
│   │   ├── base/                 # Classes base
│   │   ├── common/               # Funções comuns
│   │   └── tools/                # Ferramentas especializadas
│   ├── middleware/               # Inicialização e bootstrap
│   ├── models/                   # Modelos de dados das planilhas
│   ├── static/                   # Recursos estáticos
│   │   ├── dictionaries/         # Dicionários ortográficos
│   │   ├── locales/              # Arquivos de tradução
│   │   └── report/               # Templates de relatórios
│   └── validators/               # Validadores especializados
│       ├── hierarchy/            # Validação hierárquica
│       ├── spell/                # Verificação ortográfica
│       ├── spreadsheets/         # Validação de planilhas
│       └── structure/            # Validação estrutural
├── 📝 docs/                      # Documentação gerada
├── 🧪 tests/                     # Testes unitários
├── 📋 scripts/                   # Scripts de automação
└── ⚙️ Configuração               # Arquivos de configuração
    ├── pyproject.toml
    ├── pytest.ini
    ├── Makefile
    └── .coveragerc

🧪 Testes

O projeto utiliza pytest para testes unitários com cobertura completa.

Comandos de Teste

# Execultar tudo
make all-cov

# Executar todos os testes
make test

# Testes com cobertura
make test-cov

# Testes rápidos (para em erro)
make test-fast

# Gerar relatório HTML de cobertura
make html-report

# Ver todos os comandos disponíveis
make help

Métricas de Cobertura

Cobertura atual: 8.10% (em desenvolvimento)
Threshold mínimo: 4%
Módulos com 100% de cobertura: Formatação de texto e números

Executar Testes Específicos

# Testar módulos específicos
python -m pytest tests/unit/helpers/common/generation/ -v
python -m pytest tests/unit/helpers/common/formatting/ -v

🛠️ Desenvolvimento

Configuração do Ambiente de Desenvolvimento

# Instalar dependências de desenvolvimento
poetry install --with dev

# Configurar pre-commit hooks
pre-commit install

# Formatação de código black
make black

# Formatação de código ruff
ruff check . --fix

Comandos Make Disponíveis

Comando	Descrição
`make all-cov`	Executa testes com cobertura completa
`make test`	Executa todos os testes
`make test-cov`	Testes com relatório de cobertura
`make test-fast`	Testes rápidos (para no primeiro erro)
`make coverage`	Gera apenas relatório de cobertura
`make html-report`	Relatório HTML de cobertura
`make clean`	Remove arquivos temporários
`make black`	Formata código com Black
`make make-badge`	Gera badges de cobertura e testes
`make help`	Mostra todos os comandos

Estrutura de Testes

tests/
└── unit/
    └── helpers/
        └── common/
            ├── formatting/           # Testes de formatação
            ├── generation/           # Testes de geração
            ├── processing/           # Testes de processamento
            └── validation/           # Testes de validação

📚 Documentação

Gerar Documentação

# Gerar documentação com pdoc
pdoc ./data_validate/ -o ./docs --logo "https://avatars.githubusercontent.com/u/141270342?s=400&v=4"

Documentos Disponíveis

HOW_IT_WORKS.md: Arquitetura detalhada do sistema
TESTING.md: Guia completo de testes e cobertura
CODE_OF_CONDUCT.md: Diretrizes de desenvolvimento
CHANGELOG.md: Histórico de versões

🔧 Dependências Principais

Produção

pandas (>=2.2.3): Manipulação de dados
chardet (>=5.2.0): Detecção de encoding
calamine (>=0.5.3): Leitura de arquivos Excel
pyenchant (>=3.2.2): Verificação ortográfica
pdfkit (>=1.0.0): Geração de PDFs
babel (>=2.17.0): Internacionalização

Desenvolvimento

pytest (^8.4.1): Framework de testes
coverage (^7.10.6): Cobertura de código
ruff (^0.12.11): Linting rápido
black (^25.1.0): Formatação de código
pre-commit (^4.3.0): Hooks de pré-commit

💡 Exemplos de Uso

Validação Básica

# Validação mínima (apenas pasta de entrada é obrigatória)
python -m data_validate.main --input_folder data/input

# Validação com pasta específica e debug
python -m data_validate.main \
    --input_folder /caminho/para/planilhas \
    --output_folder /caminho/para/relatorios \
    --debug

Validação com Diferentes Idiomas

# Interface em português (padrão)
python -m data_validate.main --input_folder data/input --locale pt_BR

# Interface em inglês
python -m data_validate.main --input_folder data/input --locale en_US

Validação com Argumentos Avançados

# Execução completa com todos os argumentos
python -m data_validate.main \
    --input_folder data/input \
    --output_folder data/output \
    --locale pt_BR \
    --debug \
    --sector "Biodiversidade" \
    --protocol "Protocolo v2.1" \
    --user "Pesquisador"

Validação com Flags de Otimização

# Execução rápida sem verificação ortográfica e avisos de comprimento
python -m data_validate.main \
    --input_folder data/input \
    --no-spellchecker \
    --no-warning-titles-length \
    --no-time \
    --no-version

Usando Abreviações (para desenvolvimento rápido)

# Comando mais conciso usando abreviações
python -m data_validate.main --i data/input --o data/output --l pt_BR --d

Pipeline Completo

# Executar pipeline completo com logs
bash scripts/run_main_pipeline.sh

📊 Tipos de Planilhas Suportadas

Planilha	Descrição	Validações Principais
sp_description	Descrições de indicadores	Códigos sequenciais, níveis hierárquicos, formatação
sp_value	Valores dos indicadores	Integridade referencial, tipos numéricos, casas decimais
sp_scenario	Cenários de análise	Valores únicos, pontuação, relacionamentos
sp_temporal_reference	Referências temporais	Sequência temporal, símbolos únicos
sp_composition	Composições hierárquicas	Estrutura em árvore, relacionamentos pai-filho
sp_proportionality	Proporções	Validação matemática, consistência
sp_legend	Legendas e categorias	Consistência categórica, valores válidos
sp_dictionary	Dicionários	Integridade de vocabulário

⚡ Performance e Otimização

Processamento eficiente: Uso otimizado de pandas para grandes datasets
Validação paralela: Execução simultânea de validações independentes
Cache inteligente: Reutilização de dados carregados
Logs estruturados: Sistema de logging otimizado para performance

🔍 Monitoramento e Qualidade

Badges de Status

Cobertura de Testes: Gerada automaticamente com genbadge
Status dos Testes: Atualizada a cada execução
Versão: Sincronizada com pyproject.toml

Métricas de Qualidade

Cobertura de código mínima: 4%
Testes automatizados com pytest
Linting com ruff e flake8
Formatação automática com black

🤝 Contribuição

Processo de Desenvolvimento

Fork o repositório
Clone seu fork localmente
Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
Implemente suas mudanças com testes
Execute testes (make test-cov)
Commit seguindo as diretrizes
Push para sua branch (git push origin feature/nova-funcionalidade)
Abra um Pull Request

Diretrizes de Código

Siga o padrão PEP 8
Mantenha cobertura de testes >= 4%
Use type hints
Documente funções públicas
Execute make black antes do commit

📋 Roadmap

Versão 0.7.0 (Planejada)

Validação de metadados FAIR
Suporte a formatos adicionais (CSV, JSON)
Interface web básica
API REST

Versão 1.0.0 (Planejada)

Interface gráfica completa
Validação de schemas customizáveis
Integração com bases de dados
Suporte a workflows automatizados

📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

👥 Autores

Pedro Andrade - Coordenador - MAIL e GitHub
Mário de Araújo Carvalho - Colaborador e Desenvolvedor - GitHub
Mauro Assis - Colaborador - GitHub
Miguel Gastelumendi - Colaborador - GitHub

🔗 Links Úteis

Homepage: AdaptaBrasil GitHub
Documentação: Docs
Issues: Bug Tracker
Changelog: Histórico de Versões

🐛 Solução de Problemas

Desinstalando o canoa-data-validate instalado via PyPI

pip uninstall canoa-data-validate

Argumentos Obrigatórios

# Erro: "argument --input_folder is required"
# Solução: Sempre especifique a pasta de entrada
python -m data_validate.main --input_folder data/input

Performance Lenta

# Para execução mais rápida, desative verificações demoradas
python -m data_validate.main \
    --input_folder data/input \
    --no-spellchecker \
    --no-warning-titles-length

Logs Excessivos

# Para reduzir saída no console
python -m data_validate.main \
    --input_folder data/input \
    --no-time \
    --no-version

Problemas de Encoding

# O sistema detecta automaticamente encoding com chardet
# Para arquivos problemáticos, verifique se estão em UTF-8

Dependências Ausentes

# Instalar dependências completas
poetry install

# Para problemas com pdfkit no Linux
sudo apt-get install wkhtmltopdf

# Para problemas com pyenchant
sudo apt-get install libenchant-2-2

Desenvolvido com ❤️ pela equipe AdaptaBrasil para validação rigorosa de dados científicos e ambientais.

Name		Name	Last commit message	Last commit date
Latest commit History 675 Commits
.config		.config
.github		.github
assets		assets
data		data
data_validate		data_validate
docs		docs
scripts		scripts
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
HOW_IT_WORKS.md		HOW_IT_WORKS.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TESTING.md		TESTING.md
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml

License

AdaptaBrasil/data_validate

Folders and files

Latest commit

History

Repository files navigation