extended_stats 0.1.0__py3-none-any.whl

extended_stats/__about__.py

@@ -0,0 +1,2 @@
+# Versioning
+__version__ = "0.1.0"

extended_stats/__init__.py

@@ -0,0 +1,14 @@
+from .diffing import diff_datasets, summarize_diff, DiffReport
+from .profiling import profile_dataset, DatasetProfile
+from .cleaning import drop_duplicate_rows, standardize_column_names
+from .__about__ import __version__
+
+__all__ = [
+    "diff_datasets",
+    "summarize_diff",
+    "DiffReport",
+    "profile_dataset",
+    "DatasetProfile",
+    "drop_duplicate_rows",
+    "standardize_column_names",
+]

extended_stats/cleaning/__init__.py

@@ -0,0 +1,4 @@
+# cleaning/__init__.py
+from .core import drop_duplicate_rows, standardize_column_names
+
+__all__ = ["drop_duplicate_rows", "standardize_column_names"]

extended_stats/cleaning/core.py

@@ -0,0 +1,40 @@
+"""Deterministic DataFrame cleaning transformations."""
+
+import pandas as pd
+
+
+def drop_duplicate_rows(df: pd.DataFrame) -> pd.DataFrame:
+    """Return a copy of df with fully duplicate rows removed.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+
+    Returns
+    -------
+    pd.DataFrame
+        A new DataFrame with duplicate rows dropped (keeps first
+        occurrence). The index is reset.
+    """
+    return df.drop_duplicates().reset_index(drop=True)
+
+
+def standardize_column_names(df: pd.DataFrame) -> pd.DataFrame:
+    """Return a copy of df with column names lowercased, stripped,
+    and spaces replaced with underscores.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+
+    Returns
+    -------
+    pd.DataFrame
+        A new DataFrame with cleaned column names. Original df is
+        not modified.
+    """
+    new_df = df.copy()
+    new_df.columns = (
+        new_df.columns.str.strip().str.lower().str.replace(r"\s+", "_", regex=True)
+    )
+    return new_df

extended_stats/diffing/__init__.py

@@ -0,0 +1,5 @@
+# diffing/__init__.py
+from .core import diff_datasets, DiffReport
+from .narrative import summarize_diff
+
+__all__ = ["diff_datasets", "DiffReport", "summarize_diff"]

extended_stats/diffing/core.py

@@ -0,0 +1,176 @@
+"""Core dataset comparison logic."""
+
+from dataclasses import dataclass, field
+
+import pandas as pd
+
+
+@dataclass
+class DiffReport:
+    """Holds the structured result of comparing two DataFrames.
+
+    Attributes
+    ----------
+    rows_added : int
+    rows_removed : int
+    columns_added : list[str]
+    columns_removed : list[str]
+    dtype_changes : dict[str, tuple]
+        column -> (old_dtype, new_dtype)
+    value_diffs : pd.DataFrame
+        Tidy frame of (key, column, old_value, new_value) for matched
+        rows whose values changed. Empty if no key was provided.
+    stat_shifts : pd.DataFrame
+        Per numeric column, mean/median/null-count shift between old
+        and new.
+    """
+
+    rows_added: int
+    rows_removed: int
+    columns_added: list = field(default_factory=list)
+    columns_removed: list = field(default_factory=list)
+    dtype_changes: dict = field(default_factory=dict)
+    value_diffs: pd.DataFrame = field(default_factory=pd.DataFrame, repr=False)
+    stat_shifts: pd.DataFrame = field(default_factory=pd.DataFrame, repr=False)
+
+    def __repr__(self) -> str:
+        return (
+            f"DiffReport(rows_added={self.rows_added}, "
+            f"rows_removed={self.rows_removed}, "
+            f"columns_added={self.columns_added}, "
+            f"columns_removed={self.columns_removed}, "
+            f"dtype_changes={self.dtype_changes}, "
+            f"value_diffs={len(self.value_diffs)} cell(s), "
+            f"stat_shifts={len(self.stat_shifts)} column(s))"
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "rows_added": self.rows_added,
+            "rows_removed": self.rows_removed,
+            "columns_added": self.columns_added,
+            "columns_removed": self.columns_removed,
+            "dtype_changes": self.dtype_changes,
+            "value_diffs": self.value_diffs.to_dict(orient="records"),
+            "stat_shifts": self.stat_shifts.to_dict(orient="index"),
+        }
+
+
+def _compare_row_counts(df_old: pd.DataFrame, df_new: pd.DataFrame, key):
+    if key is None:
+        old_n, new_n = len(df_old), len(df_new)
+        added = max(new_n - old_n, 0)
+        removed = max(old_n - new_n, 0)
+        return {"added": added, "removed": removed}
+
+    keys = [key] if isinstance(key, str) else list(key)
+    old_keys = (
+        set(map(tuple, df_old[keys].values)) if len(keys) > 1 else set(df_old[keys[0]])
+    )
+    new_keys = (
+        set(map(tuple, df_new[keys].values)) if len(keys) > 1 else set(df_new[keys[0]])
+    )
+
+    return {
+        "added": len(new_keys - old_keys),
+        "removed": len(old_keys - new_keys),
+    }
+
+
+def _compare_columns(df_old: pd.DataFrame, df_new: pd.DataFrame):
+    old_cols, new_cols = set(df_old.columns), set(df_new.columns)
+    added = sorted(new_cols - old_cols)
+    removed = sorted(old_cols - new_cols)
+
+    dtype_changes = {}
+    for col in old_cols & new_cols:
+        old_dtype, new_dtype = str(df_old[col].dtype), str(df_new[col].dtype)
+        if old_dtype != new_dtype:
+            dtype_changes[col] = (old_dtype, new_dtype)
+
+    return {"added": added, "removed": removed, "dtype_changes": dtype_changes}
+
+
+def _compare_values(df_old: pd.DataFrame, df_new: pd.DataFrame, key):
+    if key is None:
+        return pd.DataFrame(columns=["key", "column", "old_value", "new_value"])
+
+    keys = [key] if isinstance(key, str) else list(key)
+    merged = df_old.merge(df_new, on=keys, suffixes=("_old", "_new"), how="inner")
+
+    shared_cols = (set(df_old.columns) & set(df_new.columns)) - set(keys)
+    records = []
+    for col in shared_cols:
+        old_col, new_col = f"{col}_old", f"{col}_new"
+        changed = merged[merged[old_col] != merged[new_col]]
+        for _, row in changed.iterrows():
+            key_val = tuple(row[k] for k in keys) if len(keys) > 1 else row[keys[0]]
+            records.append(
+                {
+                    "key": key_val,
+                    "column": col,
+                    "old_value": row[old_col],
+                    "new_value": row[new_col],
+                }
+            )
+
+    return pd.DataFrame(records, columns=["key", "column", "old_value", "new_value"])
+
+
+def _compare_summary_stats(df_old: pd.DataFrame, df_new: pd.DataFrame):
+    shared_numeric = [
+        col
+        for col in set(df_old.columns) & set(df_new.columns)
+        if pd.api.types.is_numeric_dtype(df_old[col])
+        and pd.api.types.is_numeric_dtype(df_new[col])
+    ]
+
+    rows = []
+    for col in shared_numeric:
+        rows.append(
+            {
+                "column": col,
+                "mean_old": df_old[col].mean(),
+                "mean_new": df_new[col].mean(),
+                "median_old": df_old[col].median(),
+                "median_new": df_new[col].median(),
+                "nulls_old": int(df_old[col].isnull().sum()),
+                "nulls_new": int(df_new[col].isnull().sum()),
+            }
+        )
+
+    return pd.DataFrame(rows).set_index("column") if rows else pd.DataFrame()
+
+
+def diff_datasets(df_old: pd.DataFrame, df_new: pd.DataFrame, key=None) -> DiffReport:
+    """Compare two DataFrames and return a structured DiffReport.
+
+    Parameters
+    ----------
+    df_old : pd.DataFrame
+        The "before" version of the dataset.
+    df_new : pd.DataFrame
+        The "after" version of the dataset.
+    key : str or list of str, optional
+        Column(s) to match rows on. If omitted, row-level value diffs
+        are skipped and only row counts, column changes, and summary
+        stat shifts are computed.
+
+    Returns
+    -------
+    DiffReport
+    """
+    row_diff = _compare_row_counts(df_old, df_new, key)
+    col_diff = _compare_columns(df_old, df_new)
+    value_diffs = _compare_values(df_old, df_new, key)
+    stat_shifts = _compare_summary_stats(df_old, df_new)
+
+    return DiffReport(
+        rows_added=row_diff["added"],
+        rows_removed=row_diff["removed"],
+        columns_added=col_diff["added"],
+        columns_removed=col_diff["removed"],
+        dtype_changes=col_diff["dtype_changes"],
+        value_diffs=value_diffs,
+        stat_shifts=stat_shifts,
+    )

extended_stats/diffing/narrative.py

@@ -0,0 +1,47 @@
+"""Human-readable summaries of a DiffReport."""
+
+from .core import DiffReport
+
+
+def summarize_diff(report: DiffReport) -> str:
+    """Return a plain-language summary of a DiffReport.
+
+    Parameters
+    ----------
+    report : DiffReport
+
+    Returns
+    -------
+    str
+    """
+    lines = []
+
+    if report.rows_added or report.rows_removed:
+        lines.append(
+            f"{report.rows_added} row(s) added, {report.rows_removed} row(s) removed."
+        )
+    else:
+        lines.append("No row count changes.")
+
+    if report.columns_added:
+        lines.append(f"Columns added: {', '.join(report.columns_added)}.")
+    if report.columns_removed:
+        lines.append(f"Columns removed: {', '.join(report.columns_removed)}.")
+    if report.dtype_changes:
+        changes = [
+            f"{col} ({old} -> {new})"
+            for col, (old, new) in report.dtype_changes.items()
+        ]
+        lines.append(f"Dtype changes: {', '.join(changes)}.")
+
+    if not report.value_diffs.empty:
+        changed_cols = report.value_diffs["column"].value_counts()
+        parts = [f"'{col}' changed in {n} row(s)" for col, n in changed_cols.items()]
+        lines.append("Value changes: " + "; ".join(parts) + ".")
+
+    if not report.stat_shifts.empty:
+        for col, row in report.stat_shifts.iterrows():
+            mean_delta = row["mean_new"] - row["mean_old"]
+            lines.append(f"'{col}' mean shifted by {mean_delta:+.2f}.")
+
+    return " ".join(lines)

extended_stats/profiling/__init__.py

@@ -0,0 +1,4 @@
+# profiling/__init__.py
+from .core import profile_dataset, DatasetProfile
+
+__all__ = ["profile_dataset", "DatasetProfile"]

extended_stats/profiling/core.py

@@ -0,0 +1,133 @@
+"""Combined describe()/info()-style dataset profiling."""
+
+from dataclasses import dataclass, field
+
+import pandas as pd
+
+
+@dataclass
+class DatasetProfile:
+    """Holds a structured profile of a DataFrame.
+
+    Attributes
+    ----------
+    shape : tuple
+        (n_rows, n_columns)
+    memory_usage_bytes : int
+        Total memory usage of the DataFrame in bytes.
+    duplicated_rows : int
+        Count of fully duplicated rows.
+    column_summary : pd.DataFrame
+        One row per column with dtype, null count, null %, unique
+        count, and (for numeric columns) mean/median/std/min/max, or
+        (for non-numeric columns) the most frequent value and its
+        frequency.
+    """
+
+    shape: tuple
+    memory_usage_bytes: int
+    duplicated_rows: int
+    column_summary: pd.DataFrame = field(repr=False)
+
+    def __repr__(self) -> str:
+        lines = [
+            f"DatasetProfile(rows={self.shape[0]}, columns={self.shape[1]}, "
+            f"memory={self.memory_usage_bytes / 1024:.1f} KB, "
+            f"duplicated_rows={self.duplicated_rows})",
+            "",
+            self.column_summary.to_string(),
+        ]
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "shape": self.shape,
+            "memory_usage_bytes": self.memory_usage_bytes,
+            "duplicated_rows": self.duplicated_rows,
+            "column_summary": self.column_summary.to_dict(orient="index"),
+        }
+
+
+def profile_dataset(df: pd.DataFrame) -> DatasetProfile:
+    """Produce a combined describe()/info()-style profile of a DataFrame.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+
+    Returns
+    -------
+    DatasetProfile
+    """
+    rows = []
+    for col in df.columns:
+        series = df[col]
+        null_count = series.isnull().sum()
+        null_pct = round(100 * null_count / len(df), 2) if len(df) else 0.0
+
+        row = {
+            "column": col,
+            "dtype": str(series.dtype),
+            "non_null_count": series.notnull().sum(),
+            "null_count": null_count,
+            "null_pct": null_pct,
+            "unique_count": series.nunique(),
+        }
+
+        if pd.api.types.is_numeric_dtype(series):
+            row.update(
+                {
+                    "mean": series.mean(),
+                    "median": series.median(),
+                    "std": series.std(),
+                    "min": series.min(),
+                    "max": series.max(),
+                    "top_value": None,
+                    "top_freq": None,
+                }
+            )
+        else:
+            value_counts = series.value_counts()
+            top_value = value_counts.index[0] if not value_counts.empty else None
+            top_freq = value_counts.iloc[0] if not value_counts.empty else None
+            row.update(
+                {
+                    "mean": None,
+                    "median": None,
+                    "std": None,
+                    "min": None,
+                    "max": None,
+                    "top_value": top_value,
+                    "top_freq": top_freq,
+                }
+            )
+
+        rows.append(row)
+
+    if rows:
+        column_summary = pd.DataFrame(rows).set_index("column")
+    else:
+        column_summary = pd.DataFrame(
+            columns=[
+                "dtype",
+                "non_null_count",
+                "null_count",
+                "null_pct",
+                "unique_count",
+                "mean",
+                "median",
+                "std",
+                "min",
+                "max",
+                "top_value",
+                "top_freq",
+            ]
+        )
+        column_summary.index.name = "column"
+
+    return DatasetProfile(
+        shape=df.shape,
+        memory_usage_bytes=int(df.memory_usage(deep=True).sum()),
+        duplicated_rows=int(df.duplicated().sum()),
+        column_summary=column_summary,
+    )

extended_stats/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

extended_stats/utils.py

@@ -0,0 +1,2 @@
+def do_something_useful() -> None:
+    print("Replace this with a utility function")

extended_stats-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: extended_stats
+Version: 0.1.0
+Summary: Python Boilerplate contains all the boilerplate you need to create a Python package.
+Project-URL: bugs, https://github.com/dreireyez/extended_stats/issues
+Project-URL: changelog, https://github.com/dreireyez/extended_stats/releases
+Project-URL: documentation, https://dreireyez.github.io/extended_stats/
+Project-URL: homepage, https://github.com/dreireyez/extended_stats
+Author-email: Djem Andreif Reyes <contact.dafreyes@gmail.com>
+Maintainer-email: Djem Andreif Reyes <contact.dafreyes@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: rich
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# Extended Statistics
+
+[![PyPI version](https://img.shields.io/pypi/v/extended_stats.svg)](https://pypi.org/project/extended_stats/)
+[![PyPI downloads](https://static.pepy.tech/badge/extended_stats/month)](https://pepy.tech/projects/extended_stats)
+
+**Extended Statistics** is a lightweight toolkit for comparing, profiling, and cleaning pandas DataFrames. It combines dataset diffing, an extended summary, and a handful of common cleaning transformations into a single, subpackage-organized API — built as a proof of concept for practicing Python package development fundamentals (structure, subpackages, testing, and packaging).
+
+* [GitHub](https://github.com/dreireyez/extended_stats/) | [PyPI](https://pypi.org/project/extended_stats/) | [Documentation](https://dreireyez.github.io/extended_stats/)
+* Created by **Djem Andreif Reyes**
+* MIT License
+
+## Features
+
+* **Dataset diffing:** Compare two versions of a DataFrame and get a structured report of what changed: rows added/removed, columns added/removed, dtype changes, per-cell value changes (when a key column is provided), and shifts in summary statistics (mean/median/nulls) for numeric columns.
+* **Human-readable diff summaries:** Turn a diff report into a plain-language sentence summary, no manual interpretation required.
+* **Dataset profiling:** A single function that merges the useful parts of .describe() and .info() into one report: shape, memory usage, duplicate row count, and per-column stats (nulls, uniques, mean/median/std for numeric columns, top value/frequency for categorical columns).
+* **Basic cleaning utilities:** Drop fully duplicate rows and standardize column names (lowercase, trimmed, underscore-separated) in one call each.
+* **Subpackage-organized API:** Diffing, profiling, and cleaning each live in their own subpackage, with a top-level re-export layer so functions are accessible.
+
+## Installation
+
+### Stable Release
+
+To install **Extended Statistics**, run this command in your terminal:
+
+```sh
+uv add extended_stats
+```
+
+Or if you prefer to use `pip`:
+
+```sh
+pip install extended_stats
+```
+
+## From Source
+
+The source files for Extended Statistics can be downloaded from the [Github repo](https://github.com/dreireyez/extended_stats).
+
+You can either clone the public repository:
+
+```sh
+git clone https://github.com/dreireyez/extended_stats
+```
+
+Or download the [tarball](https://github.com/dreireyez/extended_stats/tarball/main):
+
+```sh
+curl -OJL https://github.com/dreireyez/extended_stats/tarball/main
+```
+
+Once you have a copy of the source, you can install it with:
+
+```sh
+cd extended_stats
+uv sync
+```
+
+## Usage
+
+To use **Extended Statistics** in a project:
+
+```python
+import extended_stats
+```
+
+## Documentation
+
+Full documentation is available on
+[GitHub Pages](https://dreireyez.github.io/extended_stats/).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and
+documentation instructions.
+
+## Author
+
+**Extended Statistics** was created in **2026** by **Djem Andreif Reyes**.
+
+GitHub [@dreireyez](https://github.com/dreireyez) | PyPI [@dreireyez](https://pypi.org/user/dreireyez/)

extended_stats-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+extended_stats/__about__.py,sha256=iEaqPDduXz5v3Haiav21xA_XJhpc3_g4d5ooEglsvmY,37
+extended_stats/__init__.py,sha256=2f9V2FuobQhFnguogvCLkrVvFQJxjk7pu5eYZoO7bLQ,415
+extended_stats/py.typed,sha256=TBDV9m9vjfnp9vsgTeJmpoNseoJEfHwvZaBLvLMfzz8,27
+extended_stats/utils.py,sha256=xnQZ-yxjfHFE5dIwg6oa73ocytJ0DV69K4gFB5gfcQE,87
+extended_stats/cleaning/__init__.py,sha256=DUdlf6ZFnCveiVqHL7sq56Ctb6bdQ-fR5tYOTbK0E1o,154
+extended_stats/cleaning/core.py,sha256=z6HIDTcbKxJqPDN2yFr1x6g1lzS_wUrqEX4bLpm2fI8,1024
+extended_stats/diffing/__init__.py,sha256=tVUYgjLB2KEJ_QbfQ_o2YSu2CM4_6m9DTrZ6tjQQGeY,170
+extended_stats/diffing/core.py,sha256=5bxql5Mj5MSdGAuujmT6R61GWhFM8jT5sNF6a2tmQd4,6263
+extended_stats/diffing/narrative.py,sha256=exahyuwUBDZR17WaV4KVBUV0GpdjUKlbCZMjtRH90NU,1512
+extended_stats/profiling/__init__.py,sha256=NN-cWBzt9OpzgeSxp9EMQZtZYHvOZRDphaqvYKsOikc,127
+extended_stats/profiling/core.py,sha256=3fQrEwl5u7G3jv2vv97mc46SkjmmKPDIkGYkMxI58zQ,4023
+extended_stats-0.1.0.dist-info/METADATA,sha256=kxPEi2bqJdX9fLi9hAmNVJ7jGUFkF5tKHPAeOH6-98Q,4023
+extended_stats-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+extended_stats-0.1.0.dist-info/licenses/LICENSE,sha256=-SqQD97Q9UKTz8t92Lhlwj-iQB7aWSzGkseXb2giKAc,1097
+extended_stats-0.1.0.dist-info/RECORD,,

extended_stats-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

extended_stats-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Djem Andreif Reyes
+
+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, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.