mapper-lib 1.0.2

Uma biblioteca C++ para mapeamento e transformação de dados

Mapper Lib

Uma biblioteca Python de alta performance para mapeamento e transformação de dados, construída com extensões C++ para máxima eficiência.

📋 Descrição

O Mapper Lib é uma biblioteca especializada em transformar e mapear estruturas de dados JSON complexas. Ela oferece funcionalidades para:

• Flattening: Converter dicionários aninhados em estruturas planas
• Field Mapping: Mapear campos entre diferentes formatos usando configurações JSON
• High Performance: Implementação em C++ para operações rápidas de transformação de dados

🚀 Características

• ⚡ Alta Performance: Implementação em C++ com bindings Python
• 🔧 Configurável: Mapeamento baseado em arquivos JSON de configuração
• 🐍 Python Native: API simples e intuitiva para Python
• 🎯 Flexível: Suporte a separadores customizáveis e chaves pai
• 🏗️ Cross-Platform: Suporte para Windows e Linux

📦 Instalação

Pré-requisitos

• Python 3.7+
• Compilador C++ com suporte a C++17
• pybind11

Instalação via pip

pip install -r requirements.txt
pip install -e .

Instalação manual

# Clone o repositório
git clone https://github.com/compre-sua-peca/csp_mapper.git
cd csp_mapper

# Instale as dependências
pip install -r requirements.txt

# Compile e instale
python setup.py build_ext --inplace
python setup.py install

💻 Exemplos de Uso

📝 Como Funciona a Configuração

A biblioteca lê arquivos JSON de configuração do sistema de arquivos. O arquivo deve conter um dicionário onde cada chave representa um "trigger" (gatilho) que define como mapear os campos.

Estrutura típica do arquivo de configuração:

{
    "trigger_1": {
        "campo_saida_1": "caminho.campo.entrada.1",
        "campo_saida_2": "caminho.campo.entrada.2"
    },
    "trigger_2": {
        "outro_campo": "outro.caminho.campo"
    }
}

Exemplo 1: Mapeamento Básico

Primeiro, crie o arquivo de configuração mapping_config.json:

{
    "user_mapping": {
        "nome": "user.personal.name",
        "idade": "user.personal.age",
        "endereco": "user.address.street",
        "cidade": "user.address.city",
        "pedido_id": "order.id",
        "valor_total": "order.total"
    }
}

Depois, use o Python:

from mapper import mapper

# Criar instância do mapper
mapper_instance = mapper(sep=".", parent_key="data")

# Dados de entrada aninhados
input_data = {
    "user": {
        "personal": {
            "name": "João Silva",
            "age": 30
        },
        "address": {
            "street": "Rua das Flores",
            "city": "São Paulo"
        }
    },
    "order": {
        "id": "12345",
        "total": 99.99
    }
}

# Mapeamento usando arquivo de configuração
result = mapper_instance.map_dic(
    input_dict=input_data,
    config_path="mapping_config.json",
    trigger="user_mapping"
)
print(result)

Exemplo 2: Mapeamento com Arquivo de Configuração

arquivo_config.json:

{
    "user_mapping": {
        "nome_completo": "user.personal.name",
        "idade_usuario": "user.personal.age",
        "endereco_completo": "user.address.street",
        "cidade_usuario": "user.address.city"
    },
    "order_mapping": {
        "id_pedido": "order.id",
        "valor": "order.total"
    }
}

Python:

# Mapeamento usando arquivo de configuração
result = mapper_instance.map_dic(
    input_dict=input_data,
    config_path="arquivo_config.json",
    trigger="user_mapping"
)

print(result)

Saída:

{
    "nome_completo": "João Silva",
    "idade_usuario": 30,
    "endereco_completo": "Rua das Flores",
    "cidade_usuario": "São Paulo"
}

Exemplo 3: Mapeamento sem Trigger (Configuração Completa)

# Mapeamento usando toda a configuração (sem trigger específico)
result = mapper_instance.map_dic(
    input_dict=input_data,
    config_path="arquivo_config.json"
    # trigger=None (padrão)
)

print(result)

Saída:

{
    "user_mapping": {
        "nome_completo": "João Silva",
        "idade_usuario": 30,
        "endereco_completo": "Rua das Flores",
        "cidade_usuario": "São Paulo"
    },
    "order_mapping": {
        "id_pedido": "12345",
        "valor": 99.99
    }
}

Exemplo 4: Diferentes Separadores

# Usar ponto como separador
mapper_dot = mapper(sep=".", parent_key="")
result_dot = mapper_dot.map_dic(input_data, "config.json", "user_mapping")

# Usar underscore como separador
mapper_underscore = mapper(sep="_", parent_key="")
result_underscore = mapper_underscore.map_dic(input_data, "config.json", "user_mapping")

# Usar barra como separador
mapper_bar = mapper(sep="/", parent_key="")
result_bar = mapper_bar.map_dic(input_data, "config.json", "user_mapping")

print("Resultado com ponto:", result_dot)
print("Resultado com underscore:", result_underscore)
print("Resultado com barra:", result_bar)

Exemplo 5: Mapeamento com Chave Pai

# Mapper com chave pai "api_data"
mapper_with_parent = mapper(sep=".", parent_key="api_data")

result_with_parent = mapper_with_parent.map_dic(input_data, "config.json", "user_mapping")
print("Resultado com chave pai 'api_data':")
print(result_with_parent)

🔧 API Reference

Classe mapper

Construtor

mapper(sep: str = "|", parent_key: str = "")

Parâmetros:

• sep: Separador para concatenar chaves aninhadas (padrão: "|")
• parent_key: Chave pai para prefixar todas as chaves (padrão: "")

Métodos

map_dic(input_dict: dict, config_path: str, trigger: str = None) -> dict

Método principal que combina flattening e mapeamento de campos.

Parâmetros:

• input_dict: Dicionário de entrada a ser mapeado
• config_path: Caminho para o arquivo JSON de configuração
• trigger: Chave específica na configuração a ser usada (opcional)

Retorna:

• Dicionário com dados mapeados conforme a configuração

Nota: Este método internamente utiliza os métodos privados _flatten_dict() e _mapping_fields() para realizar o processamento, mas o usuário só precisa conhecer este método público.

📁 Estrutura do Projeto

mapper-lib/
├── mapper/                 # Módulo principal
│   ├── __init__.py        # Inicializador do módulo
│   ├── main.cpp           # Implementação principal em C++
│   ├── mapping_fields.cpp # Lógica de mapeamento de campos
│   ├── flattener.cpp      # Lógica de flattening
│   └── includes/          # Headers específicos por plataforma
├── setup.py               # Configuração de build
├── pyproject.toml         # Configuração do projeto
├── requirements.txt       # Dependências Python
└── main.py               # Interface Python principal

🛠️ Desenvolvimento

Compilação

# Compilar extensões C++
python setup.py build_ext --inplace

# Instalar em modo desenvolvimento
pip install -e .

Testes

# Executar testes (quando implementados)
python -m pytest tests/

📄 Licença

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

👥 Contribuição

Contribuições são bem-vindas! Por favor, sinta-se à vontade para:

1. Fazer fork do projeto
2. Criar uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abrir um Pull Request

📞 Suporte

Para suporte e dúvidas:

• Autor: Gustavo de Oliveira
• Email: [e-mail]
• Repositório: https://github.com/compre-sua-peca/csp_mapper

🔄 Histórico de Versões

• v1.0.2 - Versão atual com suporte cross-platform
• v1.0.1 - Melhorias de performance
• v1.0.0 - Lançamento inicial

---

⭐ Se este projeto foi útil para você, considere dar uma estrela no repositório!