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.
- 📊 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
pip install excel-mapperfrom 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")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.
# 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 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 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)Initialize with Excel file path.
get_column_mapping() -> Dict[str, str]: Original → attribute name mappingget_original_columns() -> List[str]: Original column namesget_attribute_names() -> List[str]: Sanitized attribute namessave_excel(file_path=None, overwrite=False): Save to Excel fileupdate_row(row_index: int, **kwargs): Update specific rowupdate_column(column_attr: str, new_values: List): Update entire columnadd_row(**kwargs): Add new row
Each row provides dynamic attribute access:
row.transaction_id # Access data
row.amount_usd = 100.50 # Modify data
row.to_dict() # Convert to dictionarymapper = 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")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]- Python 3.7+
- pandas >= 1.0
- openpyxl >= 3.0
- Fork the repository
- Create a feature branch:
git checkout -b feature/new-feature - Commit changes:
git commit -am 'Add new feature' - Push to branch:
git push origin feature/new-feature - Submit a pull request
MIT License - see LICENSE file for details.
- 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
This project uses Semantic Versioning. Current version: 1.0.0
Excel Mapper - Making Excel data manipulation in Python more intuitive and Pythonic!