tablofy 1.0.0__py3-none-any.whl

tablofy/__init__.py

@@ -0,0 +1,28 @@
+"""Tablofy — A beginner-friendly data analytics library."""
+
+__version__ = "1.0.0"
+
+from tablofy.core.errors import (
+    TablofyColumnError,
+    TablofyDataError,
+    TablofyError,
+    TablofyFileError,
+)
+from tablofy.core.frame import TablofyFrame
+from tablofy.core.loader import load
+
+ColumnNotFoundError = TablofyColumnError
+EmptyTableError = TablofyDataError
+FileFormatError = TablofyFileError
+
+__all__ = [
+    "TablofyFrame",
+    "load",
+    "TablofyError",
+    "TablofyFileError",
+    "TablofyColumnError",
+    "TablofyDataError",
+    "ColumnNotFoundError",
+    "EmptyTableError",
+    "FileFormatError",
+]

tablofy/analytics/__init__.py

@@ -0,0 +1 @@
+"""Analytics: insights, statistics, outlier detection."""

tablofy/analytics/insights.py

@@ -0,0 +1,130 @@
+"""Rule-based insight generation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tablofy.core.frame import TablofyFrame
+
+
+class Insights:
+    """Generates deterministic, rule-based observations about a dataset."""
+
+    def __init__(self, frame: TablofyFrame) -> None:
+        self._frame = frame
+        self._df = frame._df
+
+    def generate(self) -> list[str]:
+        """Return a list of human-readable insight strings.
+
+        Checks performed
+        -----------------
+        - Dataset dimensions
+        - Missing values
+        - Duplicate rows
+        - Strong correlations
+        - High-cardinality columns
+        - Low-cardinality categorical columns
+        - Highest/lowest numeric values
+        - Outlier hints
+        """
+        insights: list[str] = []
+        df = self._df
+
+        rows, cols = df.shape
+        insights.append(f"Dataset has {rows} rows and {cols} columns.")
+
+        # Missing values
+        missing_counts = df.isna().sum()
+        total_missing = int(missing_counts.sum())
+        if total_missing:
+            pct = total_missing / df.size * 100
+            insights.append(
+                f"Found {total_missing} missing cell(s) ({pct:.1f}% of data)."
+            )
+            cols_with_missing = [c for c in df.columns if missing_counts[c] > 0]
+            insights.append(
+                f"Columns with missing values: {cols_with_missing}."
+            )
+        else:
+            insights.append("No missing values detected.")
+
+        # Duplicate rows
+        dup_count = int(df.duplicated().sum())
+        if dup_count:
+            dup_pct = dup_count / rows * 100
+            insights.append(
+                f"Found {dup_count} duplicate row(s) ({dup_pct:.1f}% of rows)."
+            )
+        else:
+            insights.append("No duplicate rows found.")
+
+        # Strong correlations
+        numeric = df.select_dtypes(include="number")
+        if numeric.shape[1] >= 2:
+            corr = numeric.corr().abs()
+            strong: list[str] = []
+            for i in range(len(corr.columns)):
+                for j in range(i + 1, len(corr.columns)):
+                    val = corr.iloc[i, j]
+                    if val >= 0.7:
+                        strong.append(
+                            f"{corr.columns[i]} — {corr.columns[j]} "
+                            f"(r = {corr.iloc[i, j]:.2f})"
+                        )
+            if strong:
+                insights.append(
+                    f"Strong correlations detected ({len(strong)}): "
+                    f"{'; '.join(strong)}."
+                )
+            else:
+                insights.append(
+                    "No strong correlations (|r| >= 0.7) found between numeric columns."
+                )
+
+        # High-cardinality columns
+        high_card = [
+            c for c in df.columns
+            if df[c].nunique() > 50 and df[c].nunique() == len(df)
+        ]
+        if high_card:
+            insights.append(
+                f"High-cardinality columns (unique ID-like): {high_card}."
+            )
+
+        # Low-cardinality categorical columns
+        obj_cols = df.select_dtypes(include=["object", "category"]).columns
+        low_card = [c for c in obj_cols if 2 <= df[c].nunique() <= 10]
+        if low_card:
+            insights.append(
+                f"Low-cardinality categorical columns ({len(low_card)}): "
+                f"{low_card}."
+            )
+
+        # Highest / lowest numeric
+        if numeric.shape[1] >= 1:
+            for col in numeric.columns:
+                max_val = df[col].max()
+                min_val = df[col].min()
+                insights.append(
+                    f"{col}: min = {min_val}, max = {max_val}."
+                )
+
+        # Outlier hints (IQR-based)
+        if numeric.shape[1] >= 1:
+            for col in numeric.columns:
+                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
+                outlier_count = int(((df[col] < lower) | (df[col] > upper)).sum())
+                if outlier_count:
+                    pct = outlier_count / rows * 100
+                    insights.append(
+                        f"{col}: {outlier_count} potential outlier(s) "
+                        f"({pct:.1f}% of rows)."
+                    )
+
+        return insights

tablofy/analytics/outliers.py

@@ -0,0 +1,81 @@
+"""Outlier detection using IQR and z-score methods."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+from tablofy.core.errors import TablofyColumnError
+
+if TYPE_CHECKING:
+    from tablofy.core.frame import TablofyFrame
+
+
+class OutlierDetector:
+    """Detects outliers in numeric columns."""
+
+    def __init__(self, frame: TablofyFrame) -> None:
+        self._frame = frame
+        self._df = frame._df
+
+    def iqr_outliers(
+        self, column: str, multiplier: float = 1.5
+    ) -> pd.DataFrame:
+        """Return rows where *column* values are IQR outliers.
+
+        Parameters
+        ----------
+        column : str
+            Numeric column to check.
+        multiplier : float
+            IQR multiplier for the fence (default 1.5).
+
+        Returns
+        -------
+        pd.DataFrame
+            Rows where the column value is outside the IQR fences.
+            Includes a ``_outlier_distance`` column.
+        """
+        if column not in self._df.columns:
+            raise TablofyColumnError(
+                f"Column {column!r} not found. "
+                f"Available: {list(self._df.columns)}"
+            )
+        if not pd.api.types.is_numeric_dtype(self._df[column]):
+            raise TablofyColumnError(
+                f"Column {column!r} is not numeric."
+            )
+
+        q1 = self._df[column].quantile(0.25)
+        q3 = self._df[column].quantile(0.75)
+        iqr = q3 - q1
+        lower = q1 - multiplier * iqr
+        upper = q3 + multiplier * iqr
+        mask = (self._df[column] < lower) | (self._df[column] > upper)
+        result = self._df[mask].copy()
+        result["_outlier_distance"] = (self._df.loc[mask, column] - q3).abs()
+        return result
+
+    def zscore_outliers(
+        self, column: str, threshold: float = 3.0
+    ) -> pd.DataFrame:
+        """Return rows where *column* has a z-score beyond *threshold*."""
+        if column not in self._df.columns:
+            raise TablofyColumnError(
+                f"Column {column!r} not found. "
+                f"Available: {list(self._df.columns)}"
+            )
+        if not pd.api.types.is_numeric_dtype(self._df[column]):
+            raise TablofyColumnError(
+                f"Column {column!r} is not numeric."
+            )
+
+        mean = self._df[column].mean()
+        std = self._df[column].std()
+        if std == 0:
+            return self._df.iloc[:0].copy()
+        zscores = (self._df[column] - mean).abs() / std
+        result = self._df[zscores > threshold].copy()
+        result["_zscore"] = zscores[zscores > threshold]
+        return result

tablofy/analytics/stats.py

@@ -0,0 +1,115 @@
+"""Statistical helpers for TablofyFrame."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pandas as pd
+
+from tablofy.core.errors import TablofyColumnError
+
+if TYPE_CHECKING:
+    from tablofy.core.frame import TablofyFrame
+
+
+class Stats:
+    """Statistical operations on a TablofyFrame.
+
+    Accessed via ``data.stats``.
+    """
+
+    def __init__(self, frame: TablofyFrame) -> None:
+        self._frame = frame
+        self._df = frame._df
+
+    def _check_col(self, column: str) -> None:
+        if column not in self._df.columns:
+            raise TablofyColumnError(
+                f"Column {column!r} not found. "
+                f"Available: {list(self._df.columns)}"
+            )
+
+    def _check_numeric(self, column: str) -> None:
+        self._check_col(column)
+        if not pd.api.types.is_numeric_dtype(self._df[column]):
+            raise TablofyColumnError(
+                f"Column {column!r} is not numeric."
+            )
+
+    def describe(self, **kwargs: Any) -> pd.DataFrame:
+        """Return descriptive statistics for all columns."""
+        return self._df.describe(include="all", **kwargs)
+
+    def correlation(self, **kwargs: Any) -> pd.DataFrame:
+        """Return the correlation matrix of numeric columns."""
+        return self._df.select_dtypes(include="number").corr(**kwargs)
+
+    def covariance(self, **kwargs: Any) -> pd.DataFrame:
+        """Return the covariance matrix of numeric columns."""
+        return self._df.select_dtypes(include="number").cov(**kwargs)
+
+    def outliers(
+        self,
+        column: str,
+        multiplier: float = 1.5,
+        return_indices: bool = False,
+    ) -> pd.DataFrame | dict:
+        """Detect outliers in *column* using the IQR method.
+
+        Parameters
+        ----------
+        column : str
+            Numeric column to check.
+        multiplier : float
+            IQR multiplier for the fence (default 1.5).
+        return_indices : bool
+            If True, return a dict with ``count`` and ``indices``.
+
+        Returns
+        -------
+        pd.DataFrame or dict
+        """
+        from tablofy.analytics.outliers import OutlierDetector
+
+        result = OutlierDetector(self._frame).iqr_outliers(column, multiplier)
+        if return_indices:
+            return {
+                "count": len(result),
+                "indices": list(result.index),
+            }
+        return result
+
+    def mean(self, column: str) -> float:
+        """Return the mean of *column*."""
+        self._check_numeric(column)
+        return float(self._df[column].mean())
+
+    def median(self, column: str) -> float:
+        """Return the median of *column*."""
+        self._check_numeric(column)
+        return float(self._df[column].median())
+
+    def std(self, column: str) -> float:
+        """Return the standard deviation of *column*."""
+        self._check_numeric(column)
+        return float(self._df[column].std())
+
+    def min(self, column: str) -> float:
+        """Return the minimum of *column*."""
+        self._check_numeric(column)
+        return float(self._df[column].min())
+
+    def max(self, column: str) -> float:
+        """Return the maximum of *column*."""
+        self._check_numeric(column)
+        return float(self._df[column].max())
+
+    def quantile(self, column: str, q: float) -> float:
+        """Return the *q*-th quantile of *column*."""
+        self._check_numeric(column)
+        return float(self._df[column].quantile(q))
+
+    def value_counts(self, column: str) -> pd.Series:
+        """Return frequency counts for *column*."""
+        self._check_col(column)
+        return self._df[column].value_counts()

tablofy/cleaning/__init__.py

@@ -0,0 +1 @@
+"""Data cleaning: cleaner and cleaning report."""

tablofy/cleaning/cleaner.py

@@ -0,0 +1,132 @@
+"""Data cleaning operations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pandas as pd
+
+from tablofy.utils.formatting import Formatter
+
+if TYPE_CHECKING:
+    from tablofy.core.frame import TablofyFrame
+
+
+class Cleaner:
+    """Performs cleaning operations on a TablofyFrame in-place."""
+
+    def __init__(self, frame: TablofyFrame) -> None:
+        self._frame = frame
+        self.actions: list[dict[str, Any]] = []
+
+    def run(
+        self,
+        duplicates: bool = True,
+        missing: str | dict = "smart",
+        columns: str | bool = "snake_case",
+        dates: bool = True,
+        text: bool = True,
+    ) -> TablofyFrame:
+        """Execute the cleaning pipeline and return the frame."""
+        self.actions = []
+        df = self._frame._df
+
+        # 1. Remove duplicate rows
+        if duplicates:
+            before = len(df)
+            df.drop_duplicates(inplace=True)
+            removed = before - len(df)
+            if removed:
+                self.actions.append({
+                    "action": "duplicates",
+                    "message": f"Removed {removed} duplicate row(s).",
+                })
+
+        # 2. Remove fully empty columns
+        empty_cols = [col for col in df.columns if df[col].isna().all()]
+        if empty_cols:
+            df.drop(columns=empty_cols, inplace=True)
+            self.actions.append({
+                "action": "empty_columns",
+                "message": f"Removed {len(empty_cols)} fully empty column(s): {empty_cols}.",
+            })
+
+        # 3. Clean column names to snake_case
+        if columns == "snake_case":
+            renamed = {}
+            for col in df.columns:
+                clean = Formatter.to_snake_case(col)
+                if clean != col:
+                    renamed[col] = clean
+            if renamed:
+                df.rename(columns=renamed, inplace=True)
+                self.actions.append({
+                    "action": "column_names",
+                    "message": f"Renamed {len(renamed)} column(s) to snake_case.",
+                })
+
+        # 4. Strip whitespace from text columns
+        if text:
+            stripped_cols = []
+            text_cols = df.select_dtypes(include=["object"]).columns
+            for col in text_cols:
+                before_strip = df[col].astype(str).str.strip()
+                df[col] = df[col].astype(str).str.strip()
+                df[col] = df[col].replace(["nan", "None", ""], None)
+                if not df[col].equals(before_strip):
+                    stripped_cols.append(col)
+            if stripped_cols:
+                self.actions.append({
+                    "action": "whitespace",
+                    "message": f"Stripped whitespace from {len(stripped_cols)} text column(s).",
+                })
+
+        # 5. Smart fill missing values
+        if missing == "smart":
+            filled_cols = []
+            for col in df.columns:
+                if df[col].isna().any():
+                    if pd.api.types.is_numeric_dtype(df[col]):
+                        median_val = df[col].median()
+                        if pd.notna(median_val):
+                            df[col] = df[col].fillna(median_val)
+                            filled_cols.append(col)
+                    else:
+                        mode_vals = df[col].mode()
+                        if len(mode_vals):
+                            fill_val = mode_vals[0] if pd.notna(mode_vals[0]) else ""
+                            df[col] = df[col].fillna(fill_val)
+                            filled_cols.append(col)
+            if filled_cols:
+                self.actions.append({
+                    "action": "missing_values",
+                    "message": f"Smart-filled {len(filled_cols)} column(s): {filled_cols}.",
+                })
+        elif isinstance(missing, dict):
+            df.fillna(missing, inplace=True)
+            self.actions.append({
+                "action": "missing_values",
+                "message": f"Filled missing values using explicit mapping: {missing}.",
+            })
+
+        # 6. Date parsing
+        if dates:
+            parsed_cols = []
+            for col in df.select_dtypes(include=["object"]).columns:
+                sample = df[col].dropna().head(20)
+                if len(sample) < 2:
+                    continue
+                try:
+                    pd.to_datetime(sample, errors="raise")
+                    df[col] = pd.to_datetime(df[col], errors="coerce")
+                    parsed_cols.append(col)
+                except (ValueError, TypeError):
+                    pass
+            if parsed_cols:
+                self.actions.append({
+                    "action": "date_parsing",
+                    "message": f"Parsed {len(parsed_cols)} date column(s): {parsed_cols}.",
+                })
+
+        self._frame._df = df
+        return self._frame

tablofy/cleaning/report.py

@@ -0,0 +1,29 @@
+"""Cleaning report generator."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tablofy.core.frame import TablofyFrame
+
+
+class CleanReport:
+    """Summarises the most recent cleaning run."""
+
+    def __init__(self, frame: TablofyFrame) -> None:
+        self._frame = frame
+
+    def summary(self) -> dict:
+        """Return a dict with actions, action_count, and summary_text."""
+        actions = self._frame._last_clean_actions
+        count = len(actions)
+        if count:
+            summary_text = f"Cleaning completed: {count} action(s) performed."
+        else:
+            summary_text = "No cleaning operations recorded."
+        return {
+            "actions": actions,
+            "action_count": count,
+            "summary_text": summary_text,
+        }

tablofy/core/__init__.py

@@ -0,0 +1 @@
+"""Core components: frame, loader, errors, config."""

tablofy/core/config.py

@@ -0,0 +1,11 @@
+"""Package-level configuration constants."""
+
+SUPPORTED_EXTENSIONS: frozenset[str] = frozenset({
+    ".csv",
+    ".xlsx",
+    ".xls",
+    ".json",
+    ".parquet",
+})
+
+REPORT_EXTENSIONS: frozenset[str] = frozenset({".html", ".xlsx"})

tablofy/core/errors.py

@@ -0,0 +1,25 @@
+"""Custom exception classes for Tablofy."""
+
+
+class TablofyError(Exception):
+    """Base exception for all Tablofy errors."""
+
+
+class TablofyFileError(TablofyError):
+    """Raised when a file operation fails (not found, unsupported format)."""
+
+
+class TablofyColumnError(TablofyError):
+    """Raised when a requested column does not exist."""
+
+
+class TablofyDataError(TablofyError):
+    """Raised on invalid data (empty dataset, coercion failure)."""
+
+
+class TablofyChartError(TablofyError):
+    """Raised when a chart operation is invalid."""
+
+
+class TablofyParseError(TablofyError):
+    """Raised when parsing a user string (e.g. chart description) fails."""