masterclean 1.0.0__tar.gz

masterclean-1.0.0/LICENSE

@@ -0,0 +1,11 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Faisal Maraicar N
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

masterclean-1.0.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: masterclean
+Version: 1.0.0
+Summary: Automated CSV cleaning toolkit
+Author: Mohamed Faisal
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: typer
+Requires-Dist: chardet
+Requires-Dist: pytest
+Requires-Dist: openpyxl
+Requires-Dist: matplotlib
+Requires-Dist: plotly
+Requires-Dist: rich
+Dynamic: license-file

masterclean-1.0.0/README.md

@@ -0,0 +1,355 @@
+# 🚀 MasterClean
+
+![Python](https://img.shields.io/badge/python-3.10-blue)
+
+![Tests](https://github.com/MohamedFaisal-11/masterclean/actions/workflows/tests.yml/badge.svg)
+
+![License](https://img.shields.io/badge/license-MIT-green)
+
+Automated Data Cleaning, Validation & Analytics Toolkit for Python.
+
+MasterClean is a professional Python package that automates dataset cleaning, preprocessing, validation, profiling, visualization, and reporting using a single command.
+
+It is designed for:
+
+* Data Analysts
+* Data Scientists
+* ML Engineers
+* Researchers
+* Students
+* Automation workflows
+
+---
+
+# ✨ Features
+
+## Data Cleaning
+
+* Automatic missing value handling
+* Duplicate row removal
+* Column standardization
+* String cleanup
+* Encoding-aware file loading
+
+---
+
+## Datatype Optimization
+
+* Automatic numeric conversion
+* Datetime detection
+* Integer optimization
+* Mixed datatype handling
+
+---
+
+## Validation Engine
+
+* Negative value detection
+* Outlier detection
+* Invalid boolean detection
+* Dataset quality warnings
+
+---
+
+## Analytics & Profiling
+
+* Automated dataset profiling
+* Numeric statistics
+* Categorical summaries
+* Memory usage analysis
+
+---
+
+## Visualization Engine
+
+* Interactive Plotly dashboards
+* Histograms
+* Pie charts
+* Boxplots
+* Distribution analysis
+* Category analytics
+
+---
+
+## Reporting
+
+* Unified HTML analytics dashboard
+* Validation summaries
+* Interactive charts
+* Automated report generation
+
+---
+
+## Developer Features
+
+* Command Line Interface (CLI)
+* Automated testing with pytest
+* GitHub Actions CI/CD pipeline
+* Modular package architecture
+
+---
+
+# 📦 Installation
+
+## Clone Repository
+
+```bash
+git clone https://github.com/MohamedFaisal-11/masterclean.git
+```
+
+```bash
+cd masterclean
+```
+
+---
+
+## Create Virtual Environment
+
+```bash
+python -m venv venv
+```
+
+---
+
+## Activate Environment
+
+### macOS / Linux
+
+```bash
+source venv/bin/activate
+```
+
+### Windows
+
+```bash
+venv\Scripts\activate
+```
+
+---
+
+## Install Package
+
+```bash
+pip install -e .
+```
+
+---
+
+# 🚀 CLI Usage
+
+## Clean Dataset
+
+```bash
+masterclean clean sample.csv
+```
+
+MasterClean automatically:
+
+* Reads datasets
+* Cleans missing values
+* Removes duplicates
+* Optimizes datatypes
+* Detects validation issues
+* Generates dashboards
+* Exports cleaned data
+* Creates HTML reports
+
+---
+
+## Show Version
+
+```bash
+masterclean version
+```
+
+---
+
+# 🐍 Python Usage
+
+```python
+from masterclean import (
+    read_file,
+    clean_data,
+    optimize_dtypes,
+    validate_data,
+    generate_profile,
+    generate_charts,
+    generate_report,
+    export_data
+)
+
+df = read_file("sample.csv")
+
+df = clean_data(df)
+
+df = optimize_dtypes(df)
+
+warnings = validate_data(df)
+
+profile = generate_profile(df)
+
+charts = generate_charts(df)
+
+generate_report(
+    df=df,
+    warnings=warnings,
+    profile=profile,
+    charts=charts
+)
+
+export_data(df)
+```
+
+---
+
+# 📊 Example Validation Output
+
+```text
+VALIDATION WARNINGS
+========================================
+⚠ Negative values found in 'age' (1 rows)
+
+⚠ Possible outliers detected in 'salary' (1 rows)
+
+⚠ Invalid boolean-like values found in 'active': {'maybe'}
+```
+
+---
+
+# 📈 Dashboard Features
+
+MasterClean generates a unified interactive HTML dashboard containing:
+
+* Dataset summaries
+* Validation warnings
+* Profiling statistics
+* Pie charts
+* Histograms
+* Boxplots
+* Category analytics
+* Interactive Plotly visualizations
+
+---
+
+# 🏗 Architecture
+
+```text
+Read
+   ↓
+Clean
+   ↓
+Optimize
+   ↓
+Validate
+   ↓
+Profile
+   ↓
+Visualize
+   ↓
+Report
+   ↓
+Export
+```
+
+---
+
+# 📂 Project Structure
+
+```text
+masterclean/
+│
+├── cleaner.py
+├── validator.py
+├── datatypes.py
+├── profiler.py
+├── visualizer.py
+├── report.py
+├── exporter.py
+├── reader.py
+├── cli.py
+│
+tests/
+│
+├── test_cleaner.py
+├── test_validator.py
+├── test_reader.py
+├── test_report.py
+├── test_visualizer.py
+│
+.github/workflows/
+│
+└── tests.yml
+```
+
+---
+
+# 🧪 Testing
+
+Run tests using:
+
+```bash
+python -m pytest
+```
+
+Current Status:
+
+✅ Automated tests passing
+✅ GitHub Actions CI/CD passing
+
+---
+
+# 🔄 CI/CD
+
+MasterClean uses GitHub Actions for:
+
+* automated testing
+* dependency validation
+* continuous integration
+
+---
+
+# 🛣 Roadmap
+
+Future improvements planned:
+
+* Advanced schema validation
+* Large dataset optimization
+* Plugin architecture
+* AI-powered cleaning suggestions
+* Cloud deployment support
+* Streamlit dashboard integration
+
+---
+
+# Dashboard Preview
+
+![Dashboard](assets/dashboard.png)
+
+---
+
+
+# 🤝 Contributing
+
+Contributions are welcome.
+
+You can:
+
+* report bugs
+* suggest features
+* improve documentation
+* submit pull requests
+
+---
+
+# 📄 License
+
+MIT License
+
+---
+
+# 👨‍💻 Author
+
+Mohamed Faisal Maraicar N
+
+GitHub:
+https://github.com/MohamedFaisal-11/masterclean

masterclean-1.0.0/masterclean/__init__.py

@@ -0,0 +1,8 @@
+from .reader import read_file
+from .cleaner import clean_data
+from .datatypes import optimize_dtypes
+from .validator import validate_data
+from .report import generate_report
+from .exporter import export_data
+from .profiler import generate_profile
+from .visualizer import generate_charts

masterclean-1.0.0/masterclean/cleaner.py

@@ -0,0 +1,54 @@
+def clean_data(df):
+
+    df = df.copy()
+
+    # Remove duplicates
+    df = df.drop_duplicates()
+
+    # Fill missing values
+    for col in df.columns:
+
+        # Object columns
+        if df[col].dtype == "object":
+
+            try:
+
+                mode_value = df[col].mode()[0]
+
+                df[col] = df[col].fillna(mode_value)
+
+            except:
+                pass
+
+        # Numeric columns
+        else:
+
+            try:
+
+                median_value = df[col].median()
+
+                df[col] = df[col].fillna(median_value)
+
+            except:
+                pass
+
+    # Standardize column names
+    df.columns = (
+        df.columns
+        .str.strip()
+        .str.lower()
+        .str.replace(" ", "_")
+    )
+
+    # Clean string columns
+    for col in df.select_dtypes(include="object"):
+
+        df[col] = (
+            df[col]
+            .astype(str)
+            .str.strip()
+        )
+
+    print("✅ Data cleaned successfully")
+
+    return df

masterclean-1.0.0/masterclean/cli.py

@@ -0,0 +1,133 @@
+import typer
+
+from masterclean import (
+    read_file,
+    clean_data,
+    export_data,
+    optimize_dtypes,
+    generate_report,
+    validate_data,
+    generate_profile,
+    generate_charts
+)
+
+app = typer.Typer()
+
+
+def process_file(
+
+    file_path: str,
+
+    output: str = "cleaned_data.csv",
+
+    report: bool = True,
+
+    skip_validation: bool = False
+
+):
+
+    # -----------------------------------
+    # Read File
+    # -----------------------------------
+
+    df = read_file(file_path)
+
+    # -----------------------------------
+    # Clean Data
+    # -----------------------------------
+
+    df = clean_data(df)
+
+    # -----------------------------------
+    # Optimize Datatypes
+    # -----------------------------------
+
+    df = optimize_dtypes(df)
+
+    # -----------------------------------
+    # Generate Profile
+    # -----------------------------------
+
+    profile = generate_profile(df)
+
+    # -----------------------------------
+    # Generate Interactive Charts
+    # -----------------------------------
+
+    charts = generate_charts(df)
+
+    # -----------------------------------
+    # Validation
+    # -----------------------------------
+
+    warnings = []
+
+    if not skip_validation:
+
+        warnings = validate_data(df)
+
+    # -----------------------------------
+    # Generate HTML Report
+    # -----------------------------------
+
+    if report:
+
+        generate_report(
+            df=df,
+            warnings=warnings,
+            profile=profile,
+            charts=charts
+        )
+
+    # -----------------------------------
+    # Export Cleaned Data
+    # -----------------------------------
+
+    export_data(df, output)
+
+    print("🎉 Cleaning completed successfully")
+
+
+@app.command()
+def clean(
+
+    file_path: str,
+
+    output: str = "cleaned_data.csv",
+
+    report: bool = True,
+
+    skip_validation: bool = False
+
+):
+
+    """
+    Clean and analyze CSV or Excel datasets.
+    """
+
+    process_file(
+        file_path,
+        output,
+        report,
+        skip_validation
+    )
+
+
+@app.command()
+def version():
+
+    """
+    Show current MasterClean version.
+    """
+
+    print("MasterClean v0.9-beta")
+
+
+def main():
+
+    app()
+
+
+if __name__ == "__main__":
+
+    main()

masterclean-1.0.0/masterclean/datatypes.py

@@ -0,0 +1,78 @@
+import pandas as pd
+
+
+def optimize_dtypes(df):
+
+    df = df.copy()
+
+    for col in df.columns:
+
+        # Skip already numeric columns
+        if pd.api.types.is_numeric_dtype(df[col]):
+            continue
+
+        # Process only object columns
+        if df[col].dtype == "object":
+
+            # -----------------------------------
+            # Intelligent Date Detection
+            # -----------------------------------
+
+            date_keywords = ["date", "time", "year"]
+
+            is_date_column = any(
+                keyword in col.lower()
+                for keyword in date_keywords
+            )
+
+            if is_date_column:
+
+                try:
+
+                    converted = pd.to_datetime(
+                        df[col],
+                        errors="coerce"
+                    )
+
+                    if converted.notna().sum() > len(df) * 0.5:
+
+                        df[col] = converted
+
+                        continue
+
+                except:
+                    pass
+
+            # -----------------------------------
+            # Numeric Conversion
+            # -----------------------------------
+
+            try:
+
+                converted = pd.to_numeric(
+                    df[col],
+                    errors="coerce"
+                )
+
+                if converted.notna().sum() > len(df) * 0.7:
+
+                    df[col] = converted
+
+            except:
+                pass
+
+    # Convert float columns into Int64 if possible
+    for col in df.select_dtypes(include=['float']):
+
+        try:
+
+            if (df[col].dropna() % 1 == 0).all():
+
+                df[col] = df[col].astype("Int64")
+
+        except:
+            pass
+
+    print("✅ Datatypes optimized")
+
+    return df

masterclean-1.0.0/masterclean/exporter.py

@@ -0,0 +1,5 @@
+def export_data(df, output_file="cleaned_data.csv"):
+
+    df.to_csv(output_file, index=False)
+
+    print(f"✅ Cleaned CSV exported as {output_file}")