cloakdata 3.1.0

Fast data anonymization with Polars

CloakData - Data Anonymizer

A flexible data anonymization library built on Polars, designed for privacy, compliance, and testing with low overhead.

---

What's New in 2.0.0

• Improved masking and transformation consistency
• Standardized built-in methods to return pl.Expr
• Added round_date
• Improved parameter handling and null safety
• Expanded test coverage
• Reorganized built-in methods under src/cloakdata/native_methods/

---

Features

• Masking: full, partial, emails, numbers
• Replacement: static values, exact mapping, contains-based rules
• Sequential IDs: numeric and alphabetical
• Generalization: age, date, number ranges
• Randomization: choices, digits, shuffle, date offsets
• Conditional rules with nested logic
• Custom runtime methods with register_method(...)
• Built on Polars for fast vectorized execution

---

How It Works

1. Load data into a Polars DataFrame
2. Define rules in a config dictionary
3. Call anonymize(df, config)
4. Receive a transformed DataFrame

---

Quickstart

import polars as pl

from cloakdata import anonymize

df = pl.DataFrame(
    {
        "name": ["Alice Smith", "Bob Jones"],
        "email": ["[e-mail]", "[e-mail]"],
        "age": [25, 42],
    }
)

config = {
    "columns": {
        "name": {"method": "initials_only"},
        "email": {"method": "mask_email"},
        "age": {"method": "generalize_age"},
    }
}

out = anonymize(df, config)
print(out)

---

Example Config

{
  "columns": {
    "name": { "method": "initials_only" },
    "email": { "method": "mask_email" },
    "phone": { "method": "mask_number" },
    "cpf": {
      "method": "replace_with_random_digits",
      "params": { "digits": 11 }
    },
    "status": {
      "method": "replace_exact",
      "params": { "mapping": { "active": "A", "inactive": "I" } }
    },
    "id_seq": { "method": "sequential_numeric", "params": { "prefix": "ID" } },
    "ref_code": { "method": "sequential_alpha", "params": { "prefix": "REF" } },
    "comments": { "method": "truncate", "params": { "length": 5 } },
    "age": { "method": "generalize_age" },
    "birth_date": { "method": "generalize_date", "params": { "mode": "month" } },
    "state": { "method": "random_choice", "params": { "choices": ["SP", "RJ", "MG", "BA"] } },
    "last_access": { "method": "date_offset", "params": { "min_days": -2, "max_days": 2 } },
    "feedback": { "method": "shuffle" }
  }
}

---

Conditional Rules

Single condition:

"cpf": {
  "method": "replace_with_random_digits",
  "params": { "digits": 11 },
  "condition": {
    "column": "status",
    "operator": "equals",
    "value": "active"
  }
}

Multiple rules per column:

"city": [
  { "method": "replace_with_value", "params": { "value": "X" } },
  {
    "method": "mask_partial",
    "params": { "visible_start": 1, "visible_end": 1 },
    "condition": { "column": "country", "operator": "equals", "value": "BR" }
  }
]

Nested conditions:

"age": {
  "method": "generalize_age",
  "condition": {
    "all": [
      { "column": "country", "operator": "equals", "value": "BR" },
      {
        "any": [
          { "column": "status", "operator": "equals", "value": "active" },
          { "column": "status", "operator": "equals", "value": "archived" }
        ]
      }
    ]
  }
}

Supported operators: equals, not_equals, in, not_in, gt, gte, lt, lte, contains, not_contains

Supported groups: all, any, not

---

Example Input to Output

Input:

name	email	age	status
Alice Smith	[e-mail]	25	active
Bob Jones	[e-mail]	42	inactive

Config:

{
  "columns": {
    "name": { "method": "initials_only" },
    "email": { "method": "mask_email" },
    "age": { "method": "generalize_age" },
    "cpf": {
      "method": "replace_with_random_digits",
      "params": { "digits": 8 },
      "condition": {
        "column": "status",
        "operator": "equals",
        "value": "active"
      }
    }
  }
}

Output:

name	email	age	cpf
A.S.	[e-mail]	20-29	48291034
B.J.	[e-mail]	40-49	null

---

Examples

Runnable scripts live under examples/.

• Masking: examples/masking/full_mask.py, examples/masking/mask_email.py, examples/masking/mask_credit_card.py
• Replacement: examples/replace/replace_with_value.py, examples/replace/hash_value.py, examples/replace/redact_regex.py, examples/replace/replace_with_hash_bucket.py
• Generalization: examples/generalize/generalize_age.py, examples/generalize/top_k_bucket.py, examples/generalize/generalize_zip_code.py, examples/generalize/coarsen_datetime.py
• Dates: examples/random/date_offset.py
• Randomization: examples/random/random_choice.py, examples/random/noise_numeric.py
• Numeric transforms: examples/round/round_number.py, examples/round/clip_range.py
• Utilities: examples/utils/coalesce.py, examples/utils/null_if_matches.py

---

Supported Methods

Method	Description
full_mask	Fixed mask or literal
mask_email	Masks the local part of an email
mask_number	Keeps leading characters and masks the rest
mask_credit_card	Masks card digits while preserving the last visible digits
mask_partial	Masks the middle while preserving visible edges
truncate	Truncates strings to a fixed length
initials_only	Converts names to initials
replace_with_value	Replaces all values with a static value
hash_value	Generates deterministic hashes, with optional salt
redact_regex	Redacts regex matches inside free text
replace_with_hash_bucket	Replaces values with deterministic hash buckets
replace_exact	Replaces exact values using a mapping
replace_by_contains	Replaces values that contain substrings
replace_with_random_digits	Generates deterministic digit strings
sequential_numeric	Sequential numeric pseudonyms
sequential_alpha	Sequential alphabetic pseudonyms
generalize_age	Groups ages into ranges
generalize_date	Reduces date and datetime granularity
generalize_number_range	Buckets numeric values into fixed intervals
generalize_zip_code	Preserves a visible postal-code prefix and masks the rest
coarsen_datetime	Coarsens timestamps into buckets, minute-of-day buckets (time-only or full datetime), hour, part-of-day, weekday, weekend/weekday, or configurable business-hours labels
top_k_bucket	Keeps the top-k most frequent categories and buckets the rest
random_choice	Picks deterministic values from a fixed set
noise_numeric	Adds deterministic numeric noise within configured bounds
shuffle	Shuffles values while keeping row count
date_offset	Applies deterministic date offsets
clip_range	Constrains numeric values to configured min/max bounds
round_number	Rounds numeric values
round_date	Rounds dates to month or year start
coalesce_cols	Returns the first non-null value across columns
null_if_matches	Converts known placeholders or regex matches into null

---

Notes

• hash_value is deterministic and better when you need stable one-way pseudonymization.
• replace_with_hash_bucket is deterministic bucketing, not unique pseudonymization. Different input values can land in the same bucket when the number of unique values is greater than the configured number of buckets.

---

Project Structure

src/
  cloakdata/
    native_methods/  # Built-in methods organized by domain
tests/               # Pytest suite
examples/            # Runnable examples
README.md
pyproject.toml

Built-in methods live under src/cloakdata/native_methods/ and are registered automatically with @native_method.

---

Installation

pip install cloakdata

Or with uv:

uv add cloakdata

---

Development

git clone https://github.com/youruser/cloakdata
cd cloakdata
uv sync --extra dev
pre-commit install
pytest -v

---

Roadmap

• Regex-based redaction
• Hashing strategies
• Parallel processing for large datasets

---

Contributing

See CONTRIBUTING.md for setup, coding standards, how to add a new anonymization method, and the PR checklist.

Notice

See NOTICE for attribution details.

License

MIT Copyright Jeferson Peter