🛡️ csvguard

The Fast, Terminal-First Data Quality Profiler & Cleaning CLI for Python.

Stop writing 40 lines of boilerplate Pandas code just to inspect missing values, bad headers, duplicate rows, and statistical outliers in messy CSV files.

csvguard gives you a CIBIL-style Data Health Score (0-100), an interactive terminal dashboard, and one-command automated data cleaning.

✨ Features

• 🩺 Instant Health Score (0-100): Comprehensive weighted evaluation of missing data ratios, duplicate rows, IQR outliers, and header hygiene.
• 🎨 Rich Terminal Dashboard: Color-coded tables, status indicators, and progress spinners directly inside your shell.
• 🧹 Automated Autonomous Cleaning: Drop duplicates, sanitize column headers to snake_case, and impute missing numerical/categorical values with a single command.
• 📈 Statistical Outlier Detection: Identifies extreme values using Tukey's Interquartile Range (IQR) fences.
• 📄 Markdown & CI/CD Export: Generate markdown audit reports suitable for GitHub PRs and automated data validation pipelines.
• ⚡ Dual Interface: Use as a standalone Command-Line Tool (csvguard) or as a Python library (import csvguard).

🚀 Installation

Via PyPI (Recommended):

pip install csvguard

From Source (Local Development):

git clone https://github.com/your-username/csvguard.git
cd csvguard
pip install -e .

💻 CLI Usage

1. Audit a CSV File (Health Checkup):

csvguard audit data.csv

2. Auto-Clean and Sanitize Data:

csvguard clean messy.csv --auto -o cleaned.csv

This automatically:

• Sanitizes headers ( Annual Income ➔ annual_income)
• Removes exact duplicate records
• Imputes missing numerical values with column medians
• Fills missing text fields with 'Unknown'

3. Generate a Markdown Documentation Report:

csvguard report data.csv -o DATA_QUALITY_REPORT.md

🐍 Python Library Usage

You can also import csvguard directly in your machine learning scripts or Jupyter Notebooks:

import csvguard as cg

# 1. Audit dataset
profile = cg.audit("samples/messy_sample.csv")
print(f"Health Score: {profile['health_score']}/100 ({profile['grade']})")
print(f"Duplicates: {profile['duplicates']}")

# 2. Clean dataset programmatically
res = cg.clean("samples/messy_sample.csv", output_path="clean.csv", impute_numeric="median")
print(f"Cleaned dataset saved to: {res['output_path']}")

📦 How to Publish to PyPI (For Maintainers)

1. Build the distribution package:

python -m pip install --upgrade build twine
python -m build

2. Upload to PyPI:

python -m twine upload dist/*

📄 License

Distributed under the MIT License.