namechameleon 0.1.0

No project description provided

NameChameleon

A Python tool for anonymizing Excel and CSV files with deterministic pseudonymization.

Features

• Deterministic anonymization using salted HMAC-SHA256
• Support for multiple column types: first_name, last_name, full_name, full_name_inverted, email, id, clear
• Excel multi-sheet support
• Extensible OOP architecture
• Dynamic name generation using Faker

Installation

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .  # Install CLI tool

Usage

CLI Tool

# Interactive mode - select column types interactively
chameleon anonymize input.xlsx output.xlsx -i

# Using a config file
chameleon anonymize input.csv output.csv -c examples/config.json

# Show available columns in a file
chameleon columns input.xlsx

# With salt for reproducibility
chameleon anonymize input.csv output.csv -c config.json --salt a1b2c3d4... --show-salt

# Different locale
chameleon anonymize input.xlsx output.xlsx -i --locale fi_FI

Python API

from namechameleon import Anonymizer

# Map your column names to namechameleon types
column_config = {
    'FirstName': 'first_name',      # Column name in your file → type
    'LastName': 'last_name',
    'Email': 'email',
    'EmployeeID': 'id',
    'Notes': 'clear'
    # Columns not listed here remain unchanged
}

anonymizer = Anonymizer(column_config=column_config, locale='en_US')

# Excel (processes all sheets)
anonymizer.anonymize_excel('input.xlsx', 'output.xlsx')

# CSV
anonymizer.anonymize_csv('input.csv', 'output.csv')

# Save salt for reproducibility (optional)
salt = anonymizer.get_salt()
print(f"Salt: {salt.hex()}")

# Reuse salt for consistent results
anonymizer2 = Anonymizer(column_config=column_config, salt=salt)

Input

FirstName	LastName	FullName	Email	EmployeeID	Department	Notes
John	Smith	John Smith	[e-mail]	EMP001	Engineering	Private info 1
Alice	Johnson	Alice Johnson	[e-mail]	EMP002	Sales	Confidential 2
Bob	Anderson	Bob Anderson	[e-mail]	EMP003	Marketing	Secret 3
Mary	Brown	Mary Brown	[e-mail]	EMP004	Engineering	Internal 4

Output

FirstName	LastName	FullName	Email	EmployeeID	Department	Notes
Patrick	Lowe	Patrick Lowe	[e-mail]	JQ3O81FS	Engineering
Jason	Williams	Jason Williams	[e-mail]	0CB4RISP	Sales
Sheila	Flores	Sheila Flores	[e-mail]	0VQ5XJRZ	Marketing
Lauren	Bush	Lauren Bush	[e-mail]	XBIGNGA8	Engineering

Note: Department column remains unchanged (not in column_config), while Notes are cleared (clear type).

Column Types

• first_name: Anonymizes to realistic first names
• last_name: Anonymizes to realistic last names
• full_name: Anonymizes full names in natural order (First Middle... Last)
  • Example: "John Michael Smith" → "Jennifer Emily Thompson"
  • Single name treated as first name
• full_name_inverted: Anonymizes full names in inverted order (Last First Middle...)
  • Example: "Smith John Michael" → "Thompson Jennifer Emily"
  • Single name treated as last name
• email: Generates email from anonymized names (see below)
• id: Hashes to 8-character alphanumeric ID
• clear: Replaces with empty string (clears)

Note: Columns not in column_config remain unchanged.

Email Handling

Email anonymization preserves the domain and only treats dot (.) as a name separator:

[e-mail]    → [e-mail]    (two parts: first.last)
[e-mail]         → [e-mail]            (single name)
[e-mail] → [e-mail]            (underscore NOT a separator)

For consistency across columns, use dot-separated emails (e.g., [e-mail]) that match your FirstName and LastName columns.

Architecture

namechameleon/
├── core/
│   ├── anonymizer.py        # Main Anonymizer class
│   └── column_handlers.py   # Handler for each column type
└── utils/
    ├── normalizer.py        # String normalization
    ├── hasher.py            # Deterministic hashing
    └── name_generator.py    # Dynamic name generation