Metadata-Version: 2.4
Name: chameleon-data
Version: 0.3.0
Summary: Interactive CLI to mask columns of CSV/TSV/XLSX files with Faker-generated fake data
Keywords: cli,faker,masking,anonymize,csv,excel
Author: hidariutiwa
Author-email: hidariutiwa <hidariutiwa22@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Dist: faker>=40.43.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas>=3.1.0
Requires-Dist: pydantic>=2.14.1
Requires-Dist: questionary>=2.1.1
Requires-Dist: rich>=15.0.0
Requires-Python: >=3.11
Project-URL: Repository, https://github.com/hidariutiwa/chameleon-data
Description-Content-Type: text/markdown

# chameleon-data

An interactive CLI that replaces selected columns of a CSV / TSV / XLSX file with fake data generated by [Faker](https://faker.readthedocs.io/). The result is saved in the same format as the input.

## Installation

Published on PyPI as [`chameleon-data`](https://pypi.org/project/chameleon-data/). Requires Python 3.11 or later.
After installation, the `chameleon` and `chameleon-example` commands are available.

### uv

```bash
# Install as a global CLI tool (recommended)
uv tool install chameleon-data

# Run once without installing
uvx --from chameleon-data chameleon -f data.csv

# Add as a dependency of another project
uv add chameleon-data

# Install into the current virtual environment
uv pip install chameleon-data
```

Upgrade / uninstall:

```bash
uv tool upgrade chameleon-data
uv tool uninstall chameleon-data
```

### pip

```bash
pip install chameleon-data

# Upgrade / uninstall
pip install --upgrade chameleon-data
pip uninstall chameleon-data
```

To use it as a standalone CLI without touching other environments, [pipx](https://pipx.pypa.io/) works too:

```bash
pipx install chameleon-data
```

### From GitHub (development version)

```bash
uv tool install git+https://github.com/hidariutiwa/chameleon-data
pip install git+https://github.com/hidariutiwa/chameleon-data
```

To pin a specific version, use `git+https://github.com/hidariutiwa/chameleon-data@<tag or commit>`.

## Usage

```bash
chameleon -f data.csv                 # saves to data_masked.csv
chameleon -f data.xlsx -o out.xlsx    # specify the output path
chameleon -f data.tsv -l en_US -s 42  # specify locale and seed
```

| Option | Description |
| --- | --- |
| `-f`, `--filepath` | Input file (required). `.csv` / `.tsv` / `.xlsx` |
| `-o`, `--output` | Output file. Defaults to `<filename>_masked.<suffix>` |
| `-l`, `--language` | Faker locale. Defaults to `ja_JP` |
| `-s`, `--seed` | Random seed. Set it to get the same result every time |
| `-v`, `--version` | Show the version |

When run, you pick the columns to mask with a checkbox prompt, then choose a replacement type for each column. Each type is shown with a sample value, and you can type to filter the list.

| Group | Types |
| --- | --- |
| — | `masking`: every character becomes `*` (length is kept) |
| person | `full_name` / `first_name` / `last_name`, `full_name_kana` / `last_name_kana` / `first_name_kana`, `email`, `user_name`, `date_of_birth`, `age`, `phone_number` |
| address | `full_address`, `zipcode`, `prefecture`, `city`, `street`, `building` |
| business | `company`, `job`, `url`, `domain`, `ipv4`, `ipv4_private` |
| finance / id | `credit_card_number`, `credit_card_expire`, `credit_card_security_code`, `bank_account`, `iban`, `uuid`, `passport_number`, `number`, `date` |

Types the locale does not support (e.g. kana names and `building` outside `ja_JP`) are hidden from the list.

Identical values are replaced with identical fake values, so relationships between rows are preserved. Empty cells stay empty.

### Sample data

```bash
chameleon-example   # writes a sample to ./example/example.csv
chameleon -f example/example.csv
```

## Development

Uses [uv](https://docs.astral.sh/uv/).

```bash
uv sync
uv run chameleon -f example/example.csv
uv build   # builds a wheel and sdist into dist/
```

### Release

Pushing a `v*` tag triggers GitHub Actions (`.github/workflows/publish.yml`), which publishes to PyPI via Trusted Publishing.

```bash
uv version --bump patch   # bump the version in pyproject.toml (minor / major also work)
git commit -am "chore: release v$(uv version --short)"
git tag "v$(uv version --short)"
git push origin main --tags
```

## License

MIT
