excel-mapper 1.0.0

Map Excel columns to Python object attributes with dynamic access

Excel Mapper

A Python library that maps Excel columns to Python object attributes with dynamic access. Read, modify, and save Excel files using clean attribute-based syntax.

Features

• 📊 Dynamic Attribute Access: Access Excel data using clean attribute names
• 🔄 Automatic Column Sanitization: Special characters and spaces converted to underscores
• ♻️ Duplicate Handling: Automatic suffixing for duplicate column names
• 💾 Bidirectional Operations: Read from and save back to Excel files
• 🐍 Pythonic Interface: Intuitive object-oriented API
• 📝 Full Type Hints: Complete type annotations for better development experience

Installation

pip install excel-mapper

Quick Start

from excel_mapper import ExcelMapper

# Load Excel file
mapper = ExcelMapper("financial_data.xlsx")

# Access data using clean attribute names
print(f"First transaction ID: {mapper.rows[0].transaction_id}")
print(f"Transaction amount: {mapper.rows[0].amount_usd}")

# Modify data
mapper.rows[0].transaction_id = "TXN_2024_001"
mapper.rows[0].amount_usd = 1500.75

# Save changes
mapper.save_excel("updated_financial_data.xlsx")

Column Name Conversion

Excel columns are automatically converted to Python-friendly attribute names:

Excel Column Name	Attribute Name
Transaction ID	transaction_id
Amount (USD)	amount_usd
Transaction Date	transaction_date
Category	category
Merchant Name	merchant_name

Duplicate columns get automatic suffixes: column_a, column_b, etc.

Advanced Usage

Access Column Information

# Get column mapping
mapping = mapper.get_column_mapping()
# {`Transaction ID`: `transaction_id`, `Amount (USD)`: `amount_usd`}

# Get original column names
columns = mapper.get_original_columns()
# [`Transaction ID`, `Amount (USD)`]

# Get attribute names
attrs = mapper.get_attribute_names()
# [`transaction_id`, `amount_usd`]

Update Data Programmatically

# Update specific row
mapper.update_row(0, transaction_id="TXN_2024_001", amount_usd=2500.50)

# Update entire column
new_amounts = [amount * 1.1 for amount in mapper.amount_usd]  # 10% increase
mapper.update_column("amount_usd", new_amounts)

# Add new row
mapper.add_row(transaction_id="TXN_2024_999", amount_usd=999.99, category="Office Supplies")

Iterate Through Data

# Iterate through all rows
for row in mapper:
    print(f"Transaction {row.transaction_id}: ${row.amount_usd}")

# Access specific row
row_2 = mapper[1]  # 0-indexed (Excel row 3)

API Reference

ExcelMapper Class

ExcelMapper(file_path: str)

Initialize with Excel file path.

Methods

• get_column_mapping() -> Dict[str, str]: Original → attribute name mapping
• get_original_columns() -> List[str]: Original column names
• get_attribute_names() -> List[str]: Sanitized attribute names
• save_excel(file_path=None, overwrite=False): Save to Excel file
• update_row(row_index: int, **kwargs): Update specific row
• update_column(column_attr: str, new_values: List): Update entire column
• add_row(**kwargs): Add new row

Row Objects

Each row provides dynamic attribute access:

row.transaction_id        # Access data
row.amount_usd = 100.50   # Modify data
row.to_dict()             # Convert to dictionary

Examples

Basic Data Processing

mapper = ExcelMapper("expense_report.xlsx")

total_expenses = 0
for row in mapper:
    if row.category == "Travel":
        total_expenses += row.amount_usd
        row.approval_status = "Pending Manager Review"

print(f"Total travel expenses: ${total_expenses}")
mapper.save_excel("processed_expenses.xlsx")

Data Analysis

mapper = ExcelMapper("quarterly_sales.xlsx")

q1_sales = sum(row.sales_amount for row in mapper if row.quarter == "Q1")
top_performers = [row for row in mapper if row.sales_amount > 100000]

Requirements

• Python 3.7+
• pandas >= 1.0
• openpyxl >= 3.0

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Commit changes: git commit -am 'Add new feature'
4. Push to branch: git push origin feature/new-feature
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Documentation: https://github.com/spllat-00/excel-mapper/wiki
• Issue Tracker: https://github.com/spllat-00/excel-mapper/issues
• Discussions: https://github.com/spllat-00/excel-mapper/discussions

Versioning

This project uses Semantic Versioning. Current version: 1.0.0

---

Excel Mapper - Making Excel data manipulation in Python more intuitive and Pythonic!