pycleanframe 1.0.0

Declarative data cleaning contracts for pandas.

cleanframe

Declarative data cleaning contracts for pandas. Annotation-based. Zero API calls. Offline-first.

from cleanframe import clean, Col, Schema

schema = Schema(
    age    = Col(null="median",  clip=(0, 120)),
    salary = Col(null="median",  clip=(0, 999_999)),
    dept   = Col(null="Unknown", dtype="category"),
)

@clean(schema)
def train_model(df):
    model.fit(df)

result = train_model(dirty_df)
print(result.explain())
print(result.to_code())

Install

pip install cleanframe

Decorators

Decorator	What it does
@clean(schema)	Cleans the DataFrame before the function runs, returns a CleanResult
@validate(schema)	Raises DataQualityError if data is dirty — never modifies
@audit(schema)	Like @clean but also prints a full change log
@profile	Prints a data quality report, no schema needed
@pipeline(s1, s2, ...)	Applies multiple schemas in sequence

Col() options

Col(
    null="median",   # mean | median | mode | drop | ffill | bfill | auto | ignore | <scalar>
    clip=(0, 120),   # clip numeric values to [min, max]
    dtype="float",   # int | float | str | bool | category | datetime
    rename="age_yr", # rename column after cleaning
    required=True,   # raise KeyError if column is missing
)

CleanResult

result.df            # cleaned DataFrame
result.explain()     # human-readable change report
result.to_code()     # equivalent pandas code (no cleanframe dependency)
result.summary()     # one-line summary
result.return_value  # what your function returned

Modes

@clean(schema, mode="fix")    # default — clean silently
@clean(schema, mode="warn")   # clean and emit UserWarning per change
@clean(schema, mode="raise")  # raise DataQualityError instead of cleaning

Requirements

• Python >= 3.8
• pandas >= 1.3
• numpy >= 1.21

License

MIT