clean-column-names

Clean pandas DataFrame column names into predictable, consistent case styles.

Installation

uv add clean-column-names

Usage

import pandas as pd
import clean_column_names

df = pd.DataFrame(
    columns=[
        "First Name",
        "Café Sales ($)",
        "HTTPStatusCode",
        "",
        None,
        "First Name",
    ]
)

df = df.pipe(clean_column_names.clean_column_names)

print(df.columns.tolist())

Output:

[
    "first_name",
    "cafe_sales_$",
    "http_status_code",
    "column",
    "column_1",
    "first_name_1",
]

The original DataFrame is not modified.

API

df = df.pipe(
    clean_column_names.clean_column_names,
    case="snake",
    replace=None,
    remove_accents=True,
)

Arguments

df: A pandas DataFrame.

case: The target case style. Defaults to "snake".

replace: Optional mapping of literal text replacements to apply before case conversion. Matching is case-insensitive.

remove_accents: When True, accented characters are transliterated to ASCII where possible. Defaults to True.

Case Styles

Examples

Use kebab case:

df = df.pipe(
    clean_column_names.clean_column_names,
    case="kebab",
)

print(df.columns.tolist())

[
    "first-name",
    "cafe-sales-$",
    "http-status-code",
    "column",
    "column-1",
    "first-name-1",
]

Apply replacements before cleaning:

df = df.pipe(
    clean_column_names.clean_column_names,
    replace={"HTTP": "API"},
)

print(df.columns.tolist())

[
    "first_name",
    "cafe_sales_$",
    "api_status_code",
    "column",
    "column_1",
    "first_name_1",
]

Keep accented characters:

df = df.pipe(
    clean_column_names.clean_column_names,
    case="title",
    remove_accents=False,
)

print(df.columns.tolist())

[
    "First Name",
    "Café Sales ($)",
    "Http Status Code",
    "Column",
    "Column 1",
    "First Name 1",
]

Behavior Notes

Blank and null column names are converted to column.

If multiple columns clean to the same name, numeric suffixes are added using the target case style's separator:

df = pd.DataFrame(columns=["Name", "Name", "Name"])
df = df.pipe(clean_column_names.clean_column_names)

print(df.columns.tolist())

["name", "name_1", "name_2"]

This package supports ordinary flat columns and pandas MultiIndex columns.

License

MIT