mapper-lib 1.0.3

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

Mapper Lib

A high-performance Python library for data mapping and transformation, built with C++ extensions for maximum efficiency.

📋 Description

Mapper Lib is a specialized library for transforming and mapping complex JSON data structures. It provides functionality for:

• Flattening: Convert nested dictionaries into flat structures
• Field Mapping: Map fields between different formats using JSON configurations
• High Performance: C++ implementation for fast data transformation operations

🚀 Features

• ⚡ High Performance: C++ implementation with Python bindings
• 🔧 Configurable: Mapping based on JSON configuration files
• 🐍 Python Native: Simple and intuitive API for Python
• 🎯 Flexible: Support for customizable separators and parent keys
• 🏗️ Cross-Platform: Support for Windows and Linux

📦 Installation

Prerequisites

• Python 3.7+
• C++ compiler with C++17 support
• pybind11

Installation via pip

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

Manual installation

# Clone the repository
git clone https://github.com/compre-sua-peca/csp_mapper.git
cd csp_mapper

# Install dependencies
pip install -r requirements.txt

# Compile and install
python setup.py build_ext --inplace
python setup.py install

💻 Usage Examples

📝 How Configuration Works

The library reads JSON configuration files from the file system. The file must contain a dictionary where each key represents a "trigger" that defines how to map the fields.

Typical configuration file structure:

{
    "trigger_1": {
        "output_field_1": "input.field.path.1",
        "output_field_2": "input.field.path.2"
    },
    "trigger_2": {
        "another_field": "another.field.path"
    }
}

Example 1: Basic Mapping

First, create the configuration file 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"
    }
}

Then, use Python:

from mapper import mapper

# Create mapper instance
mapper_instance = mapper(sep=".", parent_key="data")

# Nested input data
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
    }
}

# Mapping using configuration file
result = mapper_instance.map_dic(
    input_dict=input_data,
    config_path="mapping_config.json",
    trigger="user_mapping"
)
print(result)

Example 2: Mapping with Configuration File

config_file.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:

# Mapping using configuration file
result = mapper_instance.map_dic(
    input_dict=input_data,
    config_path="config_file.json",
    trigger="user_mapping"
)

print(result)

Output:

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

Example 3: Mapping without Trigger (Complete Configuration)

# Mapping using entire configuration (without specific trigger)
result = mapper_instance.map_dic(
    input_dict=input_data,
    config_path="config_file.json"
    # trigger=None (default)
)

print(result)

Output:

{
    "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
    }
}

Example 4: Different Separators

# Use dot as separator
mapper_dot = mapper(sep=".", parent_key="")
result_dot = mapper_dot.map_dic(input_data, "config.json", "user_mapping")

# Use underscore as separator
mapper_underscore = mapper(sep="_", parent_key="")
result_underscore = mapper_underscore.map_dic(input_data, "config.json", "user_mapping")

# Use slash as separator
mapper_bar = mapper(sep="/", parent_key="")
result_bar = mapper_bar.map_dic(input_data, "config.json", "user_mapping")

print("Result with dot:", result_dot)
print("Result with underscore:", result_underscore)
print("Result with slash:", result_bar)

Example 5: Mapping with Parent Key

# Mapper with parent key "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("Result with parent key 'api_data':")
print(result_with_parent)

🔧 API Reference

Class mapper

Constructor

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

Parameters:

• sep: Separator to concatenate nested keys (default: "|")
• parent_key: Parent key to prefix all keys (default: "")

Methods

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

Main method that combines flattening and field mapping.

Parameters:

• input_dict: Input dictionary to be mapped
• config_path: Path to the JSON configuration file
• trigger: Specific key in the configuration to be used (optional)

Returns:

• Dictionary with mapped data according to the configuration

Note: This method internally uses the private methods _flatten_dict() and _mapping_fields() to perform processing, but the user only needs to know this public method.

📁 Project Structure

mapper-lib/
├── mapper/                 # Main module
│   ├── __init__.py        # Module initializer
│   ├── main.cpp           # Main C++ implementation
│   ├── mapping_fields.cpp # Field mapping logic
│   ├── flattener.cpp      # Flattening logic
│   └── includes/          # Platform-specific headers
├── setup.py               # Build configuration
├── pyproject.toml         # Project configuration
├── requirements.txt       # Python dependencies
└── main.py               # Main Python interface

🛠️ Development

Compilation

# Compile C++ extensions
python setup.py build_ext --inplace

# Install in development mode
pip install -e .

Testing

# Run tests (when implemented)
python -m pytest tests/

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Contributing

Contributions are welcome! Please feel free to:

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📞 Support

For support and questions:

• Author: Gustavo de Oliveira
• Email: [e-mail]
• Repository: https://github.com/compre-sua-peca/csp_mapper

🔄 Version History

• v1.0.2 - Current version with cross-platform support
• v1.0.1 - Performance improvements
• v1.0.0 - Initial release

---

⭐ If this project was useful to you, consider giving it a star in the repository!