masterclean 1.0.0__py3-none-any.whl

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/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/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/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/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}")

masterclean/profiler.py

@@ -0,0 +1,103 @@
+import pandas as pd
+
+
+def generate_profile(df):
+
+    profile = {}
+
+    # -----------------------------------
+    # Dataset Summary
+    # -----------------------------------
+
+    profile["rows"] = df.shape[0]
+    profile["columns"] = df.shape[1]
+
+    profile["duplicate_rows"] = df.duplicated().sum()
+
+    profile["memory_usage_mb"] = round(
+        df.memory_usage(deep=True).sum() / 1024 / 1024,
+        2
+    )
+
+    # -----------------------------------
+    # Column Profiles
+    # -----------------------------------
+
+    column_profiles = {}
+
+    for col in df.columns:
+
+        column_data = {}
+
+        column_data["dtype"] = str(df[col].dtype)
+
+        column_data["missing_values"] = int(
+            df[col].isnull().sum()
+        )
+
+        column_data["unique_values"] = int(
+            df[col].nunique()
+        )
+
+        # -----------------------------------
+        # Numeric Statistics
+        # -----------------------------------
+
+        if pd.api.types.is_numeric_dtype(df[col]):
+
+            column_data["mean"] = round(
+                df[col].mean(),
+                2
+            )
+
+            column_data["median"] = round(
+                df[col].median(),
+                2
+            )
+
+            column_data["min"] = round(
+                df[col].min(),
+                2
+            )
+
+            column_data["max"] = round(
+                df[col].max(),
+                2
+            )
+
+            column_data["std"] = round(
+                df[col].std(),
+                2
+            )
+
+        # -----------------------------------
+        # Categorical Statistics
+        # -----------------------------------
+
+        else:
+
+            try:
+
+                mode_value = df[col].mode()[0]
+
+                mode_frequency = int(
+                    (df[col] == mode_value).sum()
+                )
+
+                column_data["top_value"] = str(mode_value)
+
+                column_data["top_frequency"] = mode_frequency
+
+            except:
+
+                column_data["top_value"] = "N/A"
+
+                column_data["top_frequency"] = 0
+
+        column_profiles[col] = column_data
+
+    profile["column_profiles"] = column_profiles
+
+    print("✅ Data profile generated")
+
+    return profile

masterclean/reader.py

@@ -0,0 +1,66 @@
+import pandas as pd
+import chardet
+from pathlib import Path
+
+
+def detect_encoding(file_path):
+
+    with open(file_path, "rb") as file:
+
+        raw_data = file.read(100000)
+
+    result = chardet.detect(raw_data)
+
+    return result["encoding"]
+
+
+def read_file(file_path):
+
+    try:
+
+        file_extension = Path(file_path).suffix.lower()
+
+        # -----------------------------------
+        # CSV Support
+        # -----------------------------------
+
+        if file_extension == ".csv":
+
+            encoding = detect_encoding(file_path)
+
+            print(f"📄 Detected Encoding: {encoding}")
+
+            df = pd.read_csv(
+                file_path,
+                encoding=encoding
+            )
+
+            print("✅ CSV loaded successfully")
+
+            return df
+
+        # -----------------------------------
+        # Excel Support
+        # -----------------------------------
+
+        elif file_extension in [".xlsx", ".xls"]:
+
+            df = pd.read_excel(file_path)
+
+            print("✅ Excel file loaded successfully")
+
+            return df
+
+        # -----------------------------------
+        # Unsupported Files
+        # -----------------------------------
+
+        else:
+
+            raise ValueError(
+                "Unsupported file format. Use CSV or Excel files."
+            )
+
+    except Exception as e:
+
+        print(f"❌ Error reading file: {e}")

masterclean/report.py

@@ -0,0 +1,332 @@
+import pandas as pd
+
+
+def generate_report(
+
+    df,
+    warnings=None,
+    profile=None,
+    charts="",
+    output_file="report.html"
+
+):
+
+    rows = df.shape[0]
+    columns = df.shape[1]
+
+    missing_values = df.isnull().sum()
+
+    dtypes = df.dtypes
+
+    html = f"""
+    <html>
+
+    <head>
+
+        <title>MasterClean Report</title>
+
+        <style>
+
+            body {{
+                font-family: Arial;
+                margin: 40px;
+                background-color: #111827;
+                color: white;
+            }}
+
+            h1 {{
+                color: #00E5FF;
+            }}
+
+            h2 {{
+                color: #A5F3FC;
+                margin-top: 40px;
+            }}
+
+            table {{
+                border-collapse: collapse;
+                width: 95%;
+                margin-bottom: 30px;
+                background-color: #1F2937;
+            }}
+
+            th, td {{
+                border: 1px solid #374151;
+                padding: 12px;
+                text-align: left;
+            }}
+
+            th {{
+                background-color: #06B6D4;
+                color: white;
+            }}
+
+            tr:nth-child(even) {{
+                background-color: #111827;
+            }}
+
+            .warning {{
+                color: #FCA5A5;
+                font-weight: bold;
+            }}
+
+            .section {{
+                margin-bottom: 50px;
+            }}
+
+        </style>
+
+    </head>
+
+    <body>
+
+        <h1>🚀 MasterClean Analytics Dashboard</h1>
+
+        <div class="section">
+
+        <h2>Dataset Summary</h2>
+
+        <table>
+
+            <tr>
+                <th>Metric</th>
+                <th>Value</th>
+            </tr>
+
+            <tr>
+                <td>Rows</td>
+                <td>{rows}</td>
+            </tr>
+
+            <tr>
+                <td>Columns</td>
+                <td>{columns}</td>
+            </tr>
+    """
+
+    # -----------------------------------
+    # Profile Summary
+    # -----------------------------------
+
+    if profile:
+
+        html += f"""
+
+            <tr>
+                <td>Duplicate Rows</td>
+                <td>{profile.get("duplicate_rows", 0)}</td>
+            </tr>
+
+            <tr>
+                <td>Memory Usage (MB)</td>
+                <td>{profile.get("memory_usage_mb", 0)}</td>
+            </tr>
+
+        """
+
+    html += """
+        </table>
+
+        </div>
+
+        <div class="section">
+
+        <h2>Column Types</h2>
+
+        <table>
+
+            <tr>
+                <th>Column</th>
+                <th>Datatype</th>
+            </tr>
+    """
+
+    for col, dtype in dtypes.items():
+
+        html += f"""
+            <tr>
+                <td>{col}</td>
+                <td>{dtype}</td>
+            </tr>
+        """
+
+    html += """
+        </table>
+
+        </div>
+
+        <div class="section">
+
+        <h2>Missing Values</h2>
+
+        <table>
+
+            <tr>
+                <th>Column</th>
+                <th>Missing Values</th>
+            </tr>
+    """
+
+    for col, value in missing_values.items():
+
+        html += f"""
+            <tr>
+                <td>{col}</td>
+                <td>{value}</td>
+            </tr>
+        """
+
+    html += """
+        </table>
+
+        </div>
+    """
+
+    # -----------------------------------
+    # Numeric Statistics
+    # -----------------------------------
+
+    if profile:
+
+        html += """
+        <div class="section">
+
+        <h2>Numeric Statistics</h2>
+
+        <table>
+
+            <tr>
+                <th>Column</th>
+                <th>Mean</th>
+                <th>Median</th>
+                <th>Min</th>
+                <th>Max</th>
+                <th>Std</th>
+            </tr>
+        """
+
+        for col, stats in profile["column_profiles"].items():
+
+            if "mean" in stats:
+
+                html += f"""
+                <tr>
+                    <td>{col}</td>
+                    <td>{stats.get("mean", "N/A")}</td>
+                    <td>{stats.get("median", "N/A")}</td>
+                    <td>{stats.get("min", "N/A")}</td>
+                    <td>{stats.get("max", "N/A")}</td>
+                    <td>{stats.get("std", "N/A")}</td>
+                </tr>
+                """
+
+        html += """
+        </table>
+
+        </div>
+        """
+
+    # -----------------------------------
+    # Categorical Statistics
+    # -----------------------------------
+
+    if profile:
+
+        html += """
+        <div class="section">
+
+        <h2>Categorical Statistics</h2>
+
+        <table>
+
+            <tr>
+                <th>Column</th>
+                <th>Top Value</th>
+                <th>Frequency</th>
+                <th>Unique Values</th>
+            </tr>
+        """
+
+        for col, stats in profile["column_profiles"].items():
+
+            if "top_value" in stats:
+
+                html += f"""
+                <tr>
+                    <td>{col}</td>
+                    <td>{stats.get("top_value", "N/A")}</td>
+                    <td>{stats.get("top_frequency", "N/A")}</td>
+                    <td>{stats.get("unique_values", "N/A")}</td>
+                </tr>
+                """
+
+        html += """
+        </table>
+
+        </div>
+        """
+
+    # -----------------------------------
+    # Validation Warnings
+    # -----------------------------------
+
+    if warnings:
+
+        html += """
+        <div class="section">
+
+        <h2 class="warning">
+            ⚠ Validation Warnings
+        </h2>
+
+        <table>
+
+            <tr>
+                <th>Warning</th>
+            </tr>
+        """
+
+        for warning in warnings:
+
+            html += f"""
+            <tr>
+                <td>{warning}</td>
+            </tr>
+            """
+
+        html += """
+        </table>
+
+        </div>
+        """
+
+    # -----------------------------------
+    # Interactive Charts
+    # -----------------------------------
+
+    if charts:
+
+        html += """
+        <div class="section">
+
+        <h2>📊 Interactive Visual Analytics</h2>
+        """
+
+        html += charts
+
+        html += """
+        </div>
+        """
+
+    html += """
+
+    </body>
+
+    </html>
+    """
+
+    with open(output_file, "w") as file:
+
+        file.write(html)
+
+    print(f"✅ Unified dashboard generated as {output_file}")

masterclean/validator.py

@@ -0,0 +1,103 @@
+def validate_data(df):
+
+    warnings = []
+
+    # -----------------------------------
+    # Negative Values
+    # -----------------------------------
+
+    for col in df.select_dtypes(include=["int64", "float64", "Int64"]):
+
+        try:
+
+            negative_count = (df[col] < 0).sum()
+
+            if negative_count > 0:
+
+                warnings.append(
+                    f"⚠ Negative values found in '{col}' ({negative_count} rows)"
+                )
+
+        except:
+            pass
+
+    # -----------------------------------
+    # Outlier Detection
+    # -----------------------------------
+
+    for col in df.select_dtypes(include=["int64", "float64", "Int64"]):
+
+        try:
+
+            Q1 = df[col].quantile(0.25)
+            Q3 = df[col].quantile(0.75)
+
+            IQR = Q3 - Q1
+
+            lower_bound = Q1 - 1.5 * IQR
+            upper_bound = Q3 + 1.5 * IQR
+
+            outliers = df[
+                (df[col] < lower_bound) |
+                (df[col] > upper_bound)
+            ]
+
+            if len(outliers) > 0:
+
+                warnings.append(
+                    f"⚠ Possible outliers detected in '{col}' ({len(outliers)} rows)"
+                )
+
+        except:
+            pass
+
+    # -----------------------------------
+    # Boolean Validation
+    # -----------------------------------
+
+    valid_boolean_values = {
+        "true",
+        "false",
+        "yes",
+        "no"
+    }
+
+    for col in df.select_dtypes(include="object"):
+
+        unique_values = set(
+            df[col]
+            .dropna()
+            .astype(str)
+            .str.lower()
+            .unique()
+        )
+
+        if (
+            unique_values.intersection(valid_boolean_values)
+            and not unique_values.issubset(valid_boolean_values)
+        ):
+
+            invalid_values = unique_values - valid_boolean_values
+
+            warnings.append(
+                f"⚠ Invalid boolean-like values found in '{col}': {invalid_values}"
+            )
+
+    # -----------------------------------
+    # Display Warnings
+    # -----------------------------------
+
+    if warnings:
+
+        print("\nVALIDATION WARNINGS")
+        print("=" * 40)
+
+        for warning in warnings:
+
+            print(warning)
+
+    else:
+
+        print("✅ No major validation issues found")
+
+    return warnings

masterclean/visualizer.py

@@ -0,0 +1,102 @@
+import plotly.express as px
+
+
+def generate_charts(df):
+
+    chart_html = ""
+
+    # -----------------------------------
+    # Numeric Charts
+    # -----------------------------------
+
+    numeric_columns = df.select_dtypes(
+        include=["int64", "float64", "Int64"]
+    ).columns
+
+    for col in numeric_columns:
+
+        try:
+
+            # Histogram
+            fig = px.histogram(
+                df,
+                x=col,
+                title=f"{col} Distribution",
+                template="plotly_dark"
+            )
+
+            chart_html += fig.to_html(
+                full_html=False,
+                include_plotlyjs="cdn"
+            )
+
+            # Boxplot
+            fig = px.box(
+                df,
+                y=col,
+                title=f"{col} Boxplot",
+                template="plotly_dark"
+            )
+
+            chart_html += fig.to_html(
+                full_html=False,
+                include_plotlyjs=False
+            )
+
+        except:
+            pass
+
+    # -----------------------------------
+    # Categorical Charts
+    # -----------------------------------
+
+    categorical_columns = df.select_dtypes(
+        include="object"
+    ).columns
+
+    for col in categorical_columns:
+
+        try:
+
+            value_counts = (
+                df[col]
+                .value_counts()
+                .head(10)
+            )
+
+            # Bar Chart
+            fig = px.bar(
+                x=value_counts.index,
+                y=value_counts.values,
+                title=f"{col} Top Categories",
+                labels={
+                    "x": col,
+                    "y": "Count"
+                },
+                template="plotly_dark"
+            )
+
+            chart_html += fig.to_html(
+                full_html=False,
+                include_plotlyjs=False
+            )
+
+            # Pie Chart
+            fig = px.pie(
+                values=value_counts.values,
+                names=value_counts.index,
+                title=f"{col} Distribution",
+                template="plotly_dark"
+            )
+
+            chart_html += fig.to_html(
+                full_html=False,
+                include_plotlyjs=False
+            )
+
+        except:
+            pass
+
+    print("✅ Unified interactive charts generated")
+
+    return chart_html

masterclean-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+masterclean/__init__.py,sha256=DA2aftVukkKpam_I6jtFvTP52y8e6fkK_pTyj-yj0mM,286
+masterclean/cleaner.py,sha256=bZHXg1gb2o-SdkOExOAjxJFSiGuF4io6XZB_0cV1L6s,968
+masterclean/cli.py,sha256=oO-bRIaCpCRfBY1lg2gZbFKLkRxjzf-MeHWBRw78Z3Q,2206
+masterclean/datatypes.py,sha256=GagqNIJDJSlZgieMbWz74EY5RxT9UNQBV_zetehrKww,1734
+masterclean/exporter.py,sha256=frLLVxOYSMv1jBDPl5Gnwqn4jUEVvouM1PCsqcaFebA,150
+masterclean/profiler.py,sha256=XV_S5uS7fKBGhvnyvfKR7P4aI6wAjcYjuBWdKZxiyP4,2241
+masterclean/reader.py,sha256=dY1izmAnXHAiIlAh_TV4onKgyQdndDznoPwi2y7wKpU,1392
+masterclean/report.py,sha256=rBrGPTg3RxQy6GwCSzY-pOKKbiNwnHg2P3UH6GF7l9Y,6241
+masterclean/validator.py,sha256=JsRJB5fG3yUbK25CR04Dy1MPRyzT5i4346lc2YtvjKE,2311
+masterclean/visualizer.py,sha256=gg3czfSrG8MEchnCrOSMuopMZEGKP_q9LOQ-fJAUiqg,2303
+masterclean-1.0.0.dist-info/licenses/LICENSE,sha256=l92G-jngF3KP4hAIeGW5VMKLRJpwjI7rogm_786SVLs,453
+masterclean-1.0.0.dist-info/METADATA,sha256=ojJDFvrlmMUdUC6EigZnHVlRipfiZeppXaZKiV44NxA,363
+masterclean-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+masterclean-1.0.0.dist-info/entry_points.txt,sha256=VpZvrE-sBOw2weiy0E_0m8oO-2-vAeHqLNMV1jww7Is,53
+masterclean-1.0.0.dist-info/top_level.txt,sha256=HGlOlIyGokt9u34mtY_noOUBqygDWx9149XfNoWnYDw,12
+masterclean-1.0.0.dist-info/RECORD,,

masterclean-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

masterclean-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+masterclean = masterclean.cli:main

masterclean-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+masterclean