dipencsv 0.1.0__tar.gz

dipencsv-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: dipencsv
+Version: 0.1.0
+Summary: A beginner-friendly CSV analysis and ML data preparation toolkit
+Author: Dipendra
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: openpyxl>=3.0.0
+Requires-Dist: scikit-learn>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# DipenCSV 🐼
+
+> DipenCSV is to pandas what seaborn is to matplotlib — a friendlier, higher-level API.
+
+A beginner-friendly CSV analysis and ML data preparation toolkit built on top of pandas. Helps students and small teams clean, analyze, and prepare CSV data for machine learning — without needing to know pandas.
+
+## Who is it for?
+- 🎓 Students cleaning data for ML assignments
+- 🚀 Small startups needing quick data insights
+- 👨‍💻 Developers who work with CSVs occasionally
+- 📊 Anyone who finds pandas too complex
+
+## Installation
+
+```bash
+pip install dipencsv
+```
+
+## Quick Start
+
+```python
+from dipencsv import Data
+
+data = Data("your_file.csv")
+data.magic()  # one click everything
+```
+
+## Full ML Workflow in 15 lines
+
+```python
+from dipencsv import Data
+from sklearn.ensemble import RandomForestClassifier
+
+data = Data("titanic.csv")
+data.clean()
+data.drop(["passengerid", "name", "ticket", "cabin"])
+data.encode("sex")
+data.encode("embarked")
+data.remove_outliers("fare")
+data.normalize("fare")
+data.normalize("age")
+
+train, test = data.split(test_size=0.2)
+
+X_train = train.drop("survived", axis=1)
+y_train = train["survived"]
+X_test = test.drop("survived", axis=1)
+y_test = test["survived"]
+
+model = RandomForestClassifier()
+model.fit(X_train, y_train)
+print(f"Accuracy: {model.score(X_test, y_test):.2f}")
+# Accuracy: 0.76
+```
+
+---
+
+## All Commands
+
+### Loading
+```python
+data = Data("file.csv")                        # auto mode
+data = Data("bigfile.csv", stream=True)        # force stream mode
+data = Data("file.csv", auto_mode=False)       # force pandas mode
+```
+
+### Properties
+```python
+print(data.columns)   # list of column names
+print(data.shape)     # (rows, columns)
+```
+
+### Understanding Data
+```python
+data.summary()    # rows, cols, types, missing values
+data.report()     # duplicates, missing %, basic stats
+data.explain()    # trends, issues, suggestions
+data.magic()      # ⭐ one click full analysis
+```
+
+### Cleaning
+```python
+data.clean()                        # auto clean (safe mode)
+data.clean(strategy="aggressive")   # drop rows with missing values
+data.drop("column")                 # drop one column
+data.drop(["col1", "col2"])         # drop multiple columns
+data.rename("old_name", "new_name") # rename column
+data.fill("column", value)          # fill missing values manually
+```
+
+> ⚠️ After clean(), column names become lowercase with underscores.
+> Always check: `print(data.columns)`
+
+### ML Preparation
+```python
+data.encode("gender")           # text → numbers (label encoding)
+data.normalize("age")           # scale to [0, 1]
+data.standardize("salary")      # scale to mean=0, std=1
+data.remove_outliers("price")   # remove extreme values (IQR method)
+train, test = data.split(test_size=0.2)  # train/test split
+```
+
+### Analytics
+```python
+data.mean("salary")
+data.median("age")
+data.max("salary")
+data.min("salary")
+data.count("city")
+data.correlation("age", "salary")
+data.correlation_matrix()
+data.distribution("salary")
+data.outliers("salary")
+data.describe()
+data.value_counts("city")
+data.group_mean("city", "salary")
+```
+
+### Querying
+```python
+data.first()              # first 5 rows
+data.first(10)            # first 10 rows
+data.last()               # last 5 rows
+data.sort("age")          # sort ascending
+data.sort("age", asc=False)  # sort descending
+data.find("city", "Bangalore")  # find rows by value
+```
+
+### Intelligence
+```python
+data.ask("average salary")
+data.ask("top 10 salary")
+data.ask("highest salary by city")
+data.ask("lowest age")
+data.ask("count city")
+data.explain()
+data.magic()
+```
+
+### Export
+```python
+data.export("output.csv")    # CSV
+data.export("output.json")   # JSON
+data.export("output.xlsx")   # Excel (requires openpyxl)
+```
+
+---
+
+## Stream Mode (Big Files)
+
+DipenCSV auto detects file size and switches to stream mode for files > 500MB:
+
+```python
+data = Data("hugefile.csv")          # auto detects
+data = Data("hugefile.csv", stream=True)  # force stream
+```
+
+Supported in stream mode: `mean()`, `max()`, `min()`, `count()`, `group_mean()`, `filter()`, `top_n()`
+
+---
+
+## Smart Error Handling
+
+```python
+data.mean("salry")
+# ❌ Column 'salry' not found.
+# 💡 Did you mean:
+#   - salary
+#   - salary_usd
+```
+
+---
+
+## Common Issues
+
+**KeyError after clean()**
+```python
+data.clean()
+print(data.columns)      # check actual column names
+data.mean("salary")      # use lowercase
+```
+
+**Excel export failing**
+```bash
+pip install openpyxl
+```
+
+**Big file crashes**
+```python
+data = Data("bigfile.csv", stream=True)
+```
+
+---
+
+## Dependencies
+- `pandas >= 1.5.0`
+- `scikit-learn >= 1.0.0`
+- `openpyxl >= 3.0.0` (optional, Excel export)
+
+## Documentation
+Full docs available in the `docs/` folder.
+## Documentation
+
+| Doc | What it covers |
+|-----|----------------|
+| [Getting Started](docs/getting_started.md) | installation, quick start |
+| [Loading Data](docs/loading_data.md) | Data(), auto mode, stream mode |
+| [Properties](docs/properties.md) | columns, shape |
+| [Understanding Data](docs/understanding_data.md) | summary, report, explain, magic |
+| [Cleaning Data](docs/cleaning_data.md) | clean, drop, rename, fill |
+| [ML Preparation](docs/ml_prep.md) | encode, normalize, split etc |
+| [Analytics](docs/analytics.md) | mean, correlation, outliers etc |
+| [Query](docs/query.md) | sort, find, first, last |
+| [Intelligence](docs/intelligence.md) | ask, explain, magic |
+| [Stream Mode](docs/stream_mode.md) | big file handling |
+| [Export](docs/export.md) | csv, json, xlsx |
+| [Examples](docs/examples.md) | real world examples |
+| [FAQ](docs/faq.md) | common student questions |
+| [ML Workflow](docs/ml_workflow.md) | full end-to-end ML example |
+
+## License
+MIT License
+
+## Author
+Built by Dipendra — a CS student who wanted pandas to be less painful.

dipencsv-0.1.0/README.md

@@ -0,0 +1,225 @@
+# DipenCSV 🐼
+
+> DipenCSV is to pandas what seaborn is to matplotlib — a friendlier, higher-level API.
+
+A beginner-friendly CSV analysis and ML data preparation toolkit built on top of pandas. Helps students and small teams clean, analyze, and prepare CSV data for machine learning — without needing to know pandas.
+
+## Who is it for?
+- 🎓 Students cleaning data for ML assignments
+- 🚀 Small startups needing quick data insights
+- 👨‍💻 Developers who work with CSVs occasionally
+- 📊 Anyone who finds pandas too complex
+
+## Installation
+
+```bash
+pip install dipencsv
+```
+
+## Quick Start
+
+```python
+from dipencsv import Data
+
+data = Data("your_file.csv")
+data.magic()  # one click everything
+```
+
+## Full ML Workflow in 15 lines
+
+```python
+from dipencsv import Data
+from sklearn.ensemble import RandomForestClassifier
+
+data = Data("titanic.csv")
+data.clean()
+data.drop(["passengerid", "name", "ticket", "cabin"])
+data.encode("sex")
+data.encode("embarked")
+data.remove_outliers("fare")
+data.normalize("fare")
+data.normalize("age")
+
+train, test = data.split(test_size=0.2)
+
+X_train = train.drop("survived", axis=1)
+y_train = train["survived"]
+X_test = test.drop("survived", axis=1)
+y_test = test["survived"]
+
+model = RandomForestClassifier()
+model.fit(X_train, y_train)
+print(f"Accuracy: {model.score(X_test, y_test):.2f}")
+# Accuracy: 0.76
+```
+
+---
+
+## All Commands
+
+### Loading
+```python
+data = Data("file.csv")                        # auto mode
+data = Data("bigfile.csv", stream=True)        # force stream mode
+data = Data("file.csv", auto_mode=False)       # force pandas mode
+```
+
+### Properties
+```python
+print(data.columns)   # list of column names
+print(data.shape)     # (rows, columns)
+```
+
+### Understanding Data
+```python
+data.summary()    # rows, cols, types, missing values
+data.report()     # duplicates, missing %, basic stats
+data.explain()    # trends, issues, suggestions
+data.magic()      # ⭐ one click full analysis
+```
+
+### Cleaning
+```python
+data.clean()                        # auto clean (safe mode)
+data.clean(strategy="aggressive")   # drop rows with missing values
+data.drop("column")                 # drop one column
+data.drop(["col1", "col2"])         # drop multiple columns
+data.rename("old_name", "new_name") # rename column
+data.fill("column", value)          # fill missing values manually
+```
+
+> ⚠️ After clean(), column names become lowercase with underscores.
+> Always check: `print(data.columns)`
+
+### ML Preparation
+```python
+data.encode("gender")           # text → numbers (label encoding)
+data.normalize("age")           # scale to [0, 1]
+data.standardize("salary")      # scale to mean=0, std=1
+data.remove_outliers("price")   # remove extreme values (IQR method)
+train, test = data.split(test_size=0.2)  # train/test split
+```
+
+### Analytics
+```python
+data.mean("salary")
+data.median("age")
+data.max("salary")
+data.min("salary")
+data.count("city")
+data.correlation("age", "salary")
+data.correlation_matrix()
+data.distribution("salary")
+data.outliers("salary")
+data.describe()
+data.value_counts("city")
+data.group_mean("city", "salary")
+```
+
+### Querying
+```python
+data.first()              # first 5 rows
+data.first(10)            # first 10 rows
+data.last()               # last 5 rows
+data.sort("age")          # sort ascending
+data.sort("age", asc=False)  # sort descending
+data.find("city", "Bangalore")  # find rows by value
+```
+
+### Intelligence
+```python
+data.ask("average salary")
+data.ask("top 10 salary")
+data.ask("highest salary by city")
+data.ask("lowest age")
+data.ask("count city")
+data.explain()
+data.magic()
+```
+
+### Export
+```python
+data.export("output.csv")    # CSV
+data.export("output.json")   # JSON
+data.export("output.xlsx")   # Excel (requires openpyxl)
+```
+
+---
+
+## Stream Mode (Big Files)
+
+DipenCSV auto detects file size and switches to stream mode for files > 500MB:
+
+```python
+data = Data("hugefile.csv")          # auto detects
+data = Data("hugefile.csv", stream=True)  # force stream
+```
+
+Supported in stream mode: `mean()`, `max()`, `min()`, `count()`, `group_mean()`, `filter()`, `top_n()`
+
+---
+
+## Smart Error Handling
+
+```python
+data.mean("salry")
+# ❌ Column 'salry' not found.
+# 💡 Did you mean:
+#   - salary
+#   - salary_usd
+```
+
+---
+
+## Common Issues
+
+**KeyError after clean()**
+```python
+data.clean()
+print(data.columns)      # check actual column names
+data.mean("salary")      # use lowercase
+```
+
+**Excel export failing**
+```bash
+pip install openpyxl
+```
+
+**Big file crashes**
+```python
+data = Data("bigfile.csv", stream=True)
+```
+
+---
+
+## Dependencies
+- `pandas >= 1.5.0`
+- `scikit-learn >= 1.0.0`
+- `openpyxl >= 3.0.0` (optional, Excel export)
+
+## Documentation
+Full docs available in the `docs/` folder.
+## Documentation
+
+| Doc | What it covers |
+|-----|----------------|
+| [Getting Started](docs/getting_started.md) | installation, quick start |
+| [Loading Data](docs/loading_data.md) | Data(), auto mode, stream mode |
+| [Properties](docs/properties.md) | columns, shape |
+| [Understanding Data](docs/understanding_data.md) | summary, report, explain, magic |
+| [Cleaning Data](docs/cleaning_data.md) | clean, drop, rename, fill |
+| [ML Preparation](docs/ml_prep.md) | encode, normalize, split etc |
+| [Analytics](docs/analytics.md) | mean, correlation, outliers etc |
+| [Query](docs/query.md) | sort, find, first, last |
+| [Intelligence](docs/intelligence.md) | ask, explain, magic |
+| [Stream Mode](docs/stream_mode.md) | big file handling |
+| [Export](docs/export.md) | csv, json, xlsx |
+| [Examples](docs/examples.md) | real world examples |
+| [FAQ](docs/faq.md) | common student questions |
+| [ML Workflow](docs/ml_workflow.md) | full end-to-end ML example |
+
+## License
+MIT License
+
+## Author
+Built by Dipendra — a CS student who wanted pandas to be less painful.

dipencsv-0.1.0/dipencsv/__init__.py

@@ -0,0 +1,8 @@
+# dipencsv/__init__.py
+
+from dipencsv.core import Data
+
+__version__ = "0.1.0"
+__author__ = "Dipendra"
+
+__all__ = ["Data"]

dipencsv-0.1.0/dipencsv/analytics.py

@@ -0,0 +1,70 @@
+# dipencsv/analytics.py
+
+import pandas as pd
+from dipencsv.errors import format_error, format_success
+
+def describe(df: pd.DataFrame) -> pd.DataFrame:
+    numeric_df = df.select_dtypes(include="number")
+    if numeric_df.empty:
+        print("⚠️  No numeric columns found")
+        return pd.DataFrame()
+    return numeric_df.describe().round(2)
+
+
+def value_counts(df: pd.DataFrame, col: str) -> pd.Series:
+    return df[col].value_counts()
+
+
+def correlation_matrix(df: pd.DataFrame) -> pd.DataFrame:
+    numeric_df = df.select_dtypes(include="number")
+    if numeric_df.empty:
+        print("⚠️  No numeric columns found")
+        return pd.DataFrame()
+    return numeric_df.corr().round(2)
+
+
+def outliers(df: pd.DataFrame, col: str) -> pd.DataFrame:
+    q1 = df[col].quantile(0.25)
+    q3 = df[col].quantile(0.75)
+    iqr = q3 - q1
+    lower = q1 - 1.5 * iqr
+    upper = q3 + 1.5 * iqr
+    result = df[(df[col] < lower) | (df[col] > upper)]
+    print(f"📊 Outliers in '{col}': {len(result)} rows")
+    return result
+
+
+def distribution(df: pd.DataFrame, col: str) -> dict:
+    return {
+        "mean"  : round(float(df[col].mean()), 2),
+        "median": round(float(df[col].median()), 2),
+        "std"   : round(float(df[col].std()), 2),
+        "min"   : round(float(df[col].min()), 2),
+        "max"   : round(float(df[col].max()), 2),
+        "skew"  : round(float(df[col].skew()), 2),
+    }
+def sort(df: pd.DataFrame, col: str, asc: bool = True) -> pd.DataFrame:
+    if col not in df.columns:
+        print(format_error(f"Column '{col}' not found"))
+        return df
+    df = df.sort_values(by=col, ascending=asc).reset_index(drop=True)
+    direction = "ascending" if asc else "descending"
+    print(format_success(f"Sorted by '{col}' ({direction})"))
+    return df
+
+
+def first(df: pd.DataFrame, n: int = 5) -> pd.DataFrame:
+    return df.head(n)
+
+
+def last(df: pd.DataFrame, n: int = 5) -> pd.DataFrame:
+    return df.tail(n)
+
+
+def find(df: pd.DataFrame, col: str, value) -> pd.DataFrame:
+    if col not in df.columns:
+        print(format_error(f"Column '{col}' not found"))
+        return pd.DataFrame()
+    result = df[df[col] == value]
+    print(format_success(f"Found {len(result)} rows where '{col}' = '{value}'"))
+    return result

dipencsv-0.1.0/dipencsv/cleaner.py

@@ -0,0 +1,154 @@
+# dipencsv/cleaner.py
+
+import pandas as pd
+
+from dipencsv.errors import format_error, format_warning, format_success
+
+
+def clean(df: pd.DataFrame, strategy: str = "safe") -> pd.DataFrame:
+    df = df.copy()
+
+    # fix column names
+    df = _fix_columns(df)
+
+    # remove duplicates
+    before = len(df)
+    df = df.drop_duplicates()
+    removed = before - len(df)
+    if removed > 0:
+        print(format_warning(f"Removed {removed} duplicate rows"))
+
+    # handle missing values
+    df = _handle_missing(df, strategy)
+
+    # convert text numbers to numeric
+    df = _fix_numeric(df)
+
+    print(format_success("Cleaning done"))
+    return df
+
+
+def _fix_columns(df: pd.DataFrame) -> pd.DataFrame:
+    df.columns = (
+        df.columns
+        .str.strip()
+        .str.lower()
+        .str.replace(" ", "_")
+        .str.replace(r"[^\w]", "", regex=True)
+    )
+    return df
+
+
+def _handle_missing(df: pd.DataFrame, strategy: str) -> pd.DataFrame:
+    if strategy == "safe":
+        for col in df.columns:
+            if df[col].isnull().sum() == 0:
+                continue
+            if df[col].dtype in ["float64", "int64"]:
+                df[col] = df[col].fillna(df[col].median())
+            else:
+                mode = df[col].mode()
+                if not mode.empty:
+                    df[col] = df[col].fillna(mode[0])
+    elif strategy == "aggressive":
+        before = len(df)
+        df = df.dropna()
+        print(format_warning(f"Dropped {before - len(df)} rows with missing values"))
+    return df
+
+
+def _fix_numeric(df: pd.DataFrame) -> pd.DataFrame:
+    for col in df.select_dtypes(include=["object", "str"]).columns:
+        converted = pd.to_numeric(df[col], errors="coerce")
+        if converted.notna().sum() > len(df) * 0.7:
+            df[col] = converted
+    return df
+
+def drop(df: pd.DataFrame, cols) -> pd.DataFrame:
+    if isinstance(cols, str):
+        cols = [cols]
+    missing = [c for c in cols if c not in df.columns]
+    if missing:
+        print(format_error(f"Columns not found: {missing}"))
+        return df
+    df = df.drop(columns=cols)
+    print(format_success(f"Dropped columns: {cols}"))
+    return df
+
+
+def rename(df: pd.DataFrame, old: str, new: str) -> pd.DataFrame:
+    if old not in df.columns:
+        print(format_error(f"Column '{old}' not found"))
+        return df
+    df = df.rename(columns={old: new})
+    print(format_success(f"Renamed '{old}' → '{new}'"))
+    return df
+
+
+def fill(df: pd.DataFrame, col: str, value) -> pd.DataFrame:
+    if col not in df.columns:
+        print(format_error(f"Column '{col}' not found"))
+        return df
+    df[col] = df[col].fillna(value)
+    print(format_success(f"Filled missing values in '{col}' with {value}"))
+    return df
+
+def encode(df: pd.DataFrame, col: str) -> pd.DataFrame:
+    if col not in df.columns:
+        print(format_error(f"Column '{col}' not found"))
+        return df
+    unique_vals = df[col].unique()
+    mapping = {val: idx for idx, val in enumerate(unique_vals)}
+    df[col] = df[col].map(mapping)
+    print(format_success(f"Encoded '{col}': {mapping}"))
+    return df
+
+
+def normalize(df: pd.DataFrame, col: str) -> pd.DataFrame:
+    if col not in df.columns:
+        print(format_error(f"Column '{col}' not found"))
+        return df
+    min_val = df[col].min()
+    max_val = df[col].max()
+    if max_val == min_val:
+        print(format_error(f"Cannot normalize '{col}' — all values are the same"))
+        return df
+    df[col] = (df[col] - min_val) / (max_val - min_val)
+    print(format_success(f"Normalized '{col}' to range [0, 1]"))
+    return df
+
+
+def standardize(df: pd.DataFrame, col: str) -> pd.DataFrame:
+    if col not in df.columns:
+        print(format_error(f"Column '{col}' not found"))
+        return df
+    mean = df[col].mean()
+    std = df[col].std()
+    if std == 0:
+        print(format_error(f"Cannot standardize '{col}' — std is 0"))
+        return df
+    df[col] = (df[col] - mean) / std
+    print(format_success(f"Standardized '{col}' — mean=0, std=1"))
+    return df
+
+def remove_outliers(df: pd.DataFrame, col: str) -> pd.DataFrame:
+    if col not in df.columns:
+        print(format_error(f"Column '{col}' not found"))
+        return df
+    q1 = df[col].quantile(0.25)
+    q3 = df[col].quantile(0.75)
+    iqr = q3 - q1
+    lower = q1 - 1.5 * iqr
+    upper = q3 + 1.5 * iqr
+    before = len(df)
+    df = df[(df[col] >= lower) & (df[col] <= upper)]
+    removed = before - len(df)
+    print(format_success(f"Removed {removed} outliers from '{col}'"))
+    return df
+
+
+def split(df: pd.DataFrame, test_size: float = 0.2, random_state: int = 42):
+    from sklearn.model_selection import train_test_split
+    train, test = train_test_split(df, test_size=test_size, random_state=random_state)
+    print(format_success(f"Split done — train: {len(train)} rows, test: {len(test)} rows"))
+    return train, test