datarecon 0.1.0__tar.gz

datarecon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sameer Nimse
+
+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.

datarecon-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: datarecon
+Version: 0.1.0
+Summary: Explainable dataset reconciliation: find out why two datasets do not match.
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.23
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1; extra == "excel"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: openpyxl>=3.1; extra == "dev"
+Dynamic: license-file
+
+# datarecon
+
+Compare two datasets and get an explanation of *why* they differ, not just a list of mismatched cells.
+
+```python
+from datarecon import reconcile
+
+result = reconcile(
+    "source.csv", "warehouse_export.csv",
+    key="student_id",
+    rules={"score": {"tolerance": 0.01}},
+    treat_as_equal={"case", "whitespace"},
+)
+print(result.summary())
+result.to_excel("reconciliation.xlsx")
+```
+
+```
+datarecon compare source.csv target.csv --key student_id -o report.xlsx --fail-on-diff
+```
+
+## What it detects
+
+| Cause | Example |
+|---|---|
+| `leading_zeros` | `00123` vs `123` |
+| `null_vs_blank` | `None` vs `""` vs `NULL` |
+| `whitespace` / `case` | `Mary  Jones` vs `MARY JONES` |
+| `numeric_format` | `0.0` vs `00`, `10` vs `10.00` |
+| `numeric_tolerance` | `10.004` vs `10.00` with `tolerance=0.01` |
+| `date_format` | `2026-09-01` vs `09/01/2026` (month-first) |
+| `similar_text` | `Ann Lee` vs `Anne Lee` (opt-in via `fuzzy_threshold`) |
+| `value_mismatch` | everything else |
+
+Also reported: rows missing on either side, duplicate keys, null keys, columns present on only one side.
+
+Key values are matched after trimming, case folding and stripping leading zeros. Files are read as strings so no information is lost before comparison.
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+```

datarecon-0.1.0/README.md

@@ -0,0 +1,44 @@
+# datarecon
+
+Compare two datasets and get an explanation of *why* they differ, not just a list of mismatched cells.
+
+```python
+from datarecon import reconcile
+
+result = reconcile(
+    "source.csv", "warehouse_export.csv",
+    key="student_id",
+    rules={"score": {"tolerance": 0.01}},
+    treat_as_equal={"case", "whitespace"},
+)
+print(result.summary())
+result.to_excel("reconciliation.xlsx")
+```
+
+```
+datarecon compare source.csv target.csv --key student_id -o report.xlsx --fail-on-diff
+```
+
+## What it detects
+
+| Cause | Example |
+|---|---|
+| `leading_zeros` | `00123` vs `123` |
+| `null_vs_blank` | `None` vs `""` vs `NULL` |
+| `whitespace` / `case` | `Mary  Jones` vs `MARY JONES` |
+| `numeric_format` | `0.0` vs `00`, `10` vs `10.00` |
+| `numeric_tolerance` | `10.004` vs `10.00` with `tolerance=0.01` |
+| `date_format` | `2026-09-01` vs `09/01/2026` (month-first) |
+| `similar_text` | `Ann Lee` vs `Anne Lee` (opt-in via `fuzzy_threshold`) |
+| `value_mismatch` | everything else |
+
+Also reported: rows missing on either side, duplicate keys, null keys, columns present on only one side.
+
+Key values are matched after trimming, case folding and stripping leading zeros. Files are read as strings so no information is lost before comparison.
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+```

datarecon-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "datarecon"
+version = "0.1.0"
+description = "Explainable dataset reconciliation: find out why two datasets do not match."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["pandas>=2.0", "numpy>=1.23"]
+
+[project.optional-dependencies]
+excel = ["openpyxl>=3.1"]
+dev = ["pytest>=7", "openpyxl>=3.1"]
+
+[project.scripts]
+datarecon = "datarecon.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

datarecon-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

datarecon-0.1.0/src/datarecon/__init__.py

@@ -0,0 +1,5 @@
+from .core import reconcile
+from .result import ReconResult
+
+__all__ = ["reconcile", "ReconResult"]
+__version__ = "0.1.0"

datarecon-0.1.0/src/datarecon/cli.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional, Sequence
+
+from .core import reconcile
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="datarecon", description="Explainable dataset reconciliation.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    cmp = sub.add_parser("compare", help="Compare two files.")
+    cmp.add_argument("source")
+    cmp.add_argument("target")
+    cmp.add_argument("--key", action="append", required=True, help="Key column; repeat or comma-separate.")
+    cmp.add_argument("--output", "-o", help="Write report to .xlsx (full) or .csv (differences only).")
+    cmp.add_argument("--tolerance", action="append", default=[], metavar="COL=VALUE")
+    cmp.add_argument("--fuzzy", type=float, help="Similarity threshold (0-1) for near-identical text.")
+    cmp.add_argument("--ignore-column", action="append", default=[])
+    cmp.add_argument("--treat-as-equal", default="", help="Comma-separated causes, e.g. case,whitespace.")
+    cmp.add_argument("--fail-on-diff", action="store_true", help="Exit with status 1 if differences exist.")
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    keys = [k.strip() for entry in args.key for k in entry.split(",") if k.strip()]
+    rules = {}
+    for item in args.tolerance:
+        column, _, value = item.partition("=")
+        rules[column] = {"tolerance": float(value)}
+
+    result = reconcile(
+        args.source,
+        args.target,
+        keys,
+        rules=rules,
+        ignore_columns=args.ignore_column,
+        treat_as_equal={c.strip() for c in args.treat_as_equal.split(",") if c.strip()},
+        fuzzy_threshold=args.fuzzy,
+    )
+    sys.stdout.write(result.summary() + "\n")
+
+    if args.output:
+        if args.output.lower().endswith(".csv"):
+            result.differences.to_csv(args.output, index=False)
+        else:
+            result.to_excel(args.output)
+
+    return 1 if (args.fail_on_diff and result.has_differences) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

datarecon-0.1.0/src/datarecon/core.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Optional, Sequence, Union
+
+import numpy as np
+import pandas as pd
+
+from .normalize import FORMATTING_CAUSES, classify, normalize_key_part
+from .result import ReconResult
+
+Source = Union[pd.DataFrame, str, Path]
+
+_DEFAULT_IGNORED = frozenset({"numeric_tolerance"})
+
+
+def _norm_col(name: Any) -> str:
+    return str(name).strip().casefold()
+
+
+def _read(obj: Source) -> pd.DataFrame:
+    if isinstance(obj, pd.DataFrame):
+        return obj
+    path = Path(obj)
+    suffix = path.suffix.lower()
+    if suffix in {".csv", ".txt"}:
+        return pd.read_csv(path, dtype=str, keep_default_na=False)
+    if suffix == ".tsv":
+        return pd.read_csv(path, sep="\t", dtype=str, keep_default_na=False)
+    if suffix in {".xlsx", ".xlsm", ".xls"}:
+        return pd.read_excel(path, dtype=str, keep_default_na=False)
+    if suffix == ".parquet":
+        return pd.read_parquet(path)
+    raise ValueError(f"Unsupported file type: {path.suffix!r}")
+
+
+def _is_na(value: Any) -> bool:
+    return value is None or (not isinstance(value, str) and bool(pd.isna(value)))
+
+
+def _prepare(obj: Source) -> tuple[pd.DataFrame, dict[str, str]]:
+    """Convert to an all-string frame (None for nulls) with normalized column names."""
+    df = _read(obj)
+    data: dict[str, list] = {}
+    display: dict[str, str] = {}
+    for col in df.columns:
+        name = _norm_col(col)
+        if name in data:
+            raise ValueError(f"Duplicate column after normalization: {col!r}")
+        data[name] = [None if _is_na(v) else str(v) for v in df[col].tolist()]
+        display[name] = str(col).strip()
+    return pd.DataFrame(data), display
+
+
+def _add_key(df: pd.DataFrame, keys: list[str]) -> pd.DataFrame:
+    parts = [df[k].map(normalize_key_part).tolist() for k in keys]
+    raw = [df[k].tolist() for k in keys]
+    df = df.copy()
+    df["__key__"] = [
+        None if any(p is None for p in row) else "|".join(row) for row in zip(*parts)
+    ]
+    df["__label__"] = ["|".join("" if v is None else v for v in row) for row in zip(*raw)]
+    return df
+
+
+def _duplicates(df: pd.DataFrame, side: str) -> pd.DataFrame:
+    counts = df.groupby("__key__").agg(key=("__label__", "first"), occurrences=("__label__", "size"))
+    counts = counts[counts["occurrences"] > 1].reset_index(drop=True)
+    counts.insert(0, "side", side)
+    return counts
+
+
+def _public(df: pd.DataFrame, display: Mapping[str, str]) -> pd.DataFrame:
+    out = df.drop(columns=["__label__"], errors="ignore").reset_index(drop=True)
+    return out.rename(columns=display)
+
+
+def reconcile(
+    source: Source,
+    target: Source,
+    key: Union[str, Sequence[str]],
+    *,
+    rules: Optional[Mapping[str, Mapping[str, Any]]] = None,
+    ignore_columns: Iterable[str] = (),
+    treat_as_equal: Optional[Iterable[str]] = None,
+    fuzzy_threshold: Optional[float] = None,
+) -> ReconResult:
+    """Compare two datasets and explain every difference.
+
+    Parameters
+    ----------
+    key
+        Column name (or list of names) that identifies a row. Names are matched
+        case-insensitively. Key values are compared after trimming, case folding
+        and removing leading zeros, so ``001234`` matches ``1234``.
+    rules
+        Per-column options: ``tolerance`` (absolute numeric tolerance),
+        ``fuzzy`` (0-1 similarity threshold), ``date_formats`` (list of strptime formats).
+    treat_as_equal
+        Cause labels to treat as equal, for example ``{"case", "whitespace"}``.
+        ``numeric_tolerance`` is always treated as equal.
+    fuzzy_threshold
+        Default similarity threshold for labelling near-identical text ``similar_text``.
+    """
+    keys = [key] if isinstance(key, str) else list(key)
+    keys_n = [_norm_col(k) for k in keys]
+
+    src, src_names = _prepare(source)
+    tgt, tgt_names = _prepare(target)
+    for original, name in zip(keys, keys_n):
+        for side, frame in (("source", src), ("target", tgt)):
+            if name not in frame.columns:
+                raise KeyError(f"Key column {original!r} not found in {side}")
+
+    ignore = {_norm_col(c) for c in ignore_columns}
+    rules_n = {_norm_col(c): dict(r) for c, r in (rules or {}).items()}
+    ignored_causes = set(_DEFAULT_IGNORED) | set(treat_as_equal or ())
+
+    common = [c for c in src.columns if c in tgt.columns and c not in keys_n and c not in ignore]
+    only_src = [src_names[c] for c in src.columns if c not in tgt.columns]
+    only_tgt = [tgt_names[c] for c in tgt.columns if c not in src.columns]
+    compared = [src_names[c] for c in common]
+
+    src_rows, tgt_rows = len(src), len(tgt)
+    src, tgt = _add_key(src, keys_n), _add_key(tgt, keys_n)
+    null_src, null_tgt = int(src["__key__"].isna().sum()), int(tgt["__key__"].isna().sum())
+    src, tgt = src[src["__key__"].notna()], tgt[tgt["__key__"].notna()]
+
+    duplicates = pd.concat([_duplicates(src, "source"), _duplicates(tgt, "target")], ignore_index=True)
+
+    s_idx = src.drop_duplicates("__key__", keep="first").set_index("__key__")
+    t_idx = tgt.drop_duplicates("__key__", keep="first").set_index("__key__")
+
+    s_in_t = s_idx.index.isin(t_idx.index)
+    t_in_s = t_idx.index.isin(s_idx.index)
+    missing_in_target = _public(s_idx[~s_in_t], src_names)
+    missing_in_source = _public(t_idx[~t_in_s], tgt_names)
+
+    both = s_idx.index[s_in_t]
+    sa, ta = s_idx.loc[both, common], t_idx.loc[both, common]
+    labels = s_idx.loc[both, "__label__"].tolist()
+
+    equal = ((sa == ta) | (sa.isna() & ta.isna())).to_numpy()
+    sv = sa.astype(object).where(sa.notna(), None).to_numpy()
+    tv = ta.astype(object).where(ta.notna(), None).to_numpy()
+
+    records, rows_any, rows_real, ignored_cells = [], set(), set(), 0
+    for r, c in zip(*np.nonzero(~equal)):
+        col = common[c]
+        cause = classify(sv[r, c], tv[r, c], rules_n.get(col, {}), fuzzy_threshold)
+        if cause in ignored_causes:
+            ignored_cells += 1
+            continue
+        rows_any.add(r)
+        if cause not in FORMATTING_CAUSES:
+            rows_real.add(r)
+        records.append((labels[r], src_names[col], sv[r, c], tv[r, c], cause))
+
+    differences = pd.DataFrame(records, columns=["key", "column", "source", "target", "cause"])
+
+    return ReconResult(
+        source_rows=src_rows,
+        target_rows=tgt_rows,
+        matched_keys=len(both),
+        exact_rows=len(both) - len(rows_any),
+        formatting_rows=len(rows_any - rows_real),
+        mismatch_rows=len(rows_real),
+        ignored_cells=ignored_cells,
+        differences=differences,
+        missing_in_target=missing_in_target,
+        missing_in_source=missing_in_source,
+        duplicates=duplicates,
+        null_keys_source=null_src,
+        null_keys_target=null_tgt,
+        columns_only_in_source=only_src,
+        columns_only_in_target=only_tgt,
+        compared_columns=compared,
+    )

datarecon-0.1.0/src/datarecon/normalize.py

@@ -0,0 +1,106 @@
+"""Cell-level comparison logic: decide *why* two values differ."""
+from __future__ import annotations
+
+import math
+import re
+from datetime import datetime
+from difflib import SequenceMatcher
+from typing import Optional, Sequence
+
+FORMATTING_CAUSES = frozenset(
+    {"null_vs_blank", "whitespace", "case", "leading_zeros", "numeric_format", "date_format"}
+)
+
+DEFAULT_DATE_FORMATS = (
+    "%Y-%m-%d",
+    "%Y-%m-%d %H:%M:%S",
+    "%Y-%m-%dT%H:%M:%S",
+    "%m/%d/%Y",
+    "%m/%d/%Y %H:%M:%S",
+    "%Y/%m/%d",
+    "%m-%d-%Y",
+    "%Y%m%d",
+    "%d-%b-%Y",
+    "%b %d, %Y",
+)
+
+_NULL_TOKENS = frozenset({"", "null", "none", "nan"})
+_NUM_RE = re.compile(r"^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$")
+_KEY_NUM_RE = re.compile(r"^\d+(\.0+)?$")
+
+
+def is_null(value: Optional[str]) -> bool:
+    return value is None or value.strip().casefold() in _NULL_TOKENS
+
+
+def normalize_key_part(value: Optional[str]) -> Optional[str]:
+    """Canonical form of one key column value used only for matching rows."""
+    if value is None:
+        return None
+    text = value.strip().casefold()
+    if not text:
+        return None
+    if _KEY_NUM_RE.match(text):
+        text = text.split(".")[0].lstrip("0") or "0"
+    return text
+
+
+def _to_float(text: str) -> Optional[float]:
+    cleaned = text.replace(",", "")
+    if not _NUM_RE.match(cleaned):
+        return None
+    number = float(cleaned)
+    return number if math.isfinite(number) else None
+
+
+def _to_datetime(text: str, formats: Sequence[str]) -> Optional[datetime]:
+    for fmt in formats:
+        try:
+            return datetime.strptime(text, fmt)
+        except ValueError:
+            continue
+    return None
+
+
+def classify(
+    source: Optional[str],
+    target: Optional[str],
+    rule: dict,
+    fuzzy_default: Optional[float] = None,
+) -> str:
+    """Return the cause label for a pair of values already known to differ."""
+    s_null, t_null = is_null(source), is_null(target)
+    if s_null and t_null:
+        return "null_vs_blank"
+    if s_null or t_null:
+        return "value_mismatch"
+
+    if source.strip() == target.strip():
+        return "whitespace"
+    a, b = " ".join(source.split()), " ".join(target.split())
+    if a == b:
+        return "whitespace"
+    if a.casefold() == b.casefold():
+        return "case"
+    if a.isdigit() and b.isdigit() and a.lstrip("0") == b.lstrip("0"):
+        return "leading_zeros"
+
+    fa, fb = _to_float(a), _to_float(b)
+    if fa is not None and fb is not None:
+        if fa == fb:
+            return "numeric_format"
+        tolerance = rule.get("tolerance")
+        if tolerance is not None and abs(fa - fb) <= tolerance:
+            return "numeric_tolerance"
+        return "value_mismatch"
+
+    formats = rule.get("date_formats", DEFAULT_DATE_FORMATS)
+    da, db = _to_datetime(a, formats), _to_datetime(b, formats)
+    if da is not None and db is not None:
+        return "date_format" if da == db else "value_mismatch"
+
+    threshold = rule.get("fuzzy", fuzzy_default)
+    if threshold is not None:
+        if SequenceMatcher(None, a.casefold(), b.casefold()).ratio() >= threshold:
+            return "similar_text"
+    return "value_mismatch"

datarecon-0.1.0/src/datarecon/result.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Union
+
+import pandas as pd
+
+
+@dataclass
+class ReconResult:
+    source_rows: int
+    target_rows: int
+    matched_keys: int
+    exact_rows: int
+    formatting_rows: int
+    mismatch_rows: int
+    ignored_cells: int
+    differences: pd.DataFrame
+    missing_in_target: pd.DataFrame
+    missing_in_source: pd.DataFrame
+    duplicates: pd.DataFrame
+    null_keys_source: int
+    null_keys_target: int
+    columns_only_in_source: list[str]
+    columns_only_in_target: list[str]
+    compared_columns: list[str]
+
+    @property
+    def has_differences(self) -> bool:
+        return bool(
+            len(self.differences)
+            or len(self.missing_in_target)
+            or len(self.missing_in_source)
+            or len(self.duplicates)
+            or self.null_keys_source
+            or self.null_keys_target
+            or self.columns_only_in_source
+            or self.columns_only_in_target
+        )
+
+    def cause_summary(self) -> pd.DataFrame:
+        return (
+            self.differences["cause"]
+            .value_counts()
+            .rename_axis("cause")
+            .reset_index(name="cells")
+        )
+
+    def column_summary(self) -> pd.DataFrame:
+        if self.differences.empty:
+            return pd.DataFrame(columns=["column", "differences", "top_cause"])
+        grouped = self.differences.groupby("column")["cause"]
+        out = pd.DataFrame(
+            {"differences": grouped.size(), "top_cause": grouped.agg(lambda s: s.value_counts().index[0])}
+        )
+        return out.sort_values("differences", ascending=False, kind="stable").reset_index()
+
+    def metrics(self) -> pd.DataFrame:
+        dup_src = int((self.duplicates["side"] == "source").sum()) if len(self.duplicates) else 0
+        dup_tgt = int((self.duplicates["side"] == "target").sum()) if len(self.duplicates) else 0
+        rows = [
+            ("Source rows", self.source_rows),
+            ("Target rows", self.target_rows),
+            ("Matched keys", self.matched_keys),
+            ("Exact matches", self.exact_rows),
+            ("Formatting differences only", self.formatting_rows),
+            ("Value mismatches", self.mismatch_rows),
+            ("Missing in target", len(self.missing_in_target)),
+            ("Missing in source", len(self.missing_in_source)),
+            ("Duplicate keys in source", dup_src),
+            ("Duplicate keys in target", dup_tgt),
+            ("Null keys in source", self.null_keys_source),
+            ("Null keys in target", self.null_keys_target),
+        ]
+        return pd.DataFrame(rows, columns=["metric", "value"])
+
+    def summary(self, top: int = 10) -> str:
+        lines = ["Reconciliation Summary", "-" * 42]
+        metrics = self.metrics()
+        always = {"Source rows", "Target rows", "Matched keys", "Exact matches"}
+        for label, value in metrics.itertuples(index=False):
+            if label in always or value:
+                indent = "  " if label in {"Exact matches", "Formatting differences only", "Value mismatches"} else ""
+                lines.append(f"{indent}{label + ':':<30}{value:>10,}")
+        if self.ignored_cells:
+            lines.append(f"{'Cells treated as equal:':<32}{self.ignored_cells:>10,}")
+
+        if len(self.differences):
+            lines += ["", "Differences by cause:"]
+            for cause, cells in self.cause_summary().itertuples(index=False):
+                lines.append(f"  {cause:<28}{cells:>10,}")
+            lines += ["", "Most problematic columns:"]
+            for i, (col, n, cause) in enumerate(self.column_summary().head(top).itertuples(index=False), 1):
+                lines.append(f"  {i:>2}. {col:<24}{n:>8,}  (mostly {cause})")
+
+        if self.columns_only_in_source:
+            lines += ["", "Columns only in source: " + ", ".join(self.columns_only_in_source)]
+        if self.columns_only_in_target:
+            lines += ["Columns only in target: " + ", ".join(self.columns_only_in_target)]
+        return "\n".join(lines)
+
+    def to_excel(self, path: Union[str, Path]) -> Path:
+        path = Path(path)
+        schema = pd.DataFrame(
+            [("compared", c) for c in self.compared_columns]
+            + [("only_in_source", c) for c in self.columns_only_in_source]
+            + [("only_in_target", c) for c in self.columns_only_in_target],
+            columns=["status", "column"],
+        )
+        with pd.ExcelWriter(path, engine="openpyxl") as writer:
+            self.metrics().to_excel(writer, sheet_name="Summary", index=False)
+            if len(self.differences):
+                start = len(self.metrics()) + 3
+                self.cause_summary().to_excel(writer, sheet_name="Summary", index=False, startrow=start)
+                self.column_summary().to_excel(
+                    writer, sheet_name="Summary", index=False, startrow=start + len(self.cause_summary()) + 3
+                )
+            self.differences.to_excel(writer, sheet_name="Differences", index=False)
+            self.missing_in_target.to_excel(writer, sheet_name="Missing in target", index=False)
+            self.missing_in_source.to_excel(writer, sheet_name="Missing in source", index=False)
+            self.duplicates.to_excel(writer, sheet_name="Duplicate keys", index=False)
+            schema.to_excel(writer, sheet_name="Schema", index=False)
+        return path

datarecon-0.1.0/src/datarecon.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: datarecon
+Version: 0.1.0
+Summary: Explainable dataset reconciliation: find out why two datasets do not match.
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.23
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1; extra == "excel"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: openpyxl>=3.1; extra == "dev"
+Dynamic: license-file
+
+# datarecon
+
+Compare two datasets and get an explanation of *why* they differ, not just a list of mismatched cells.
+
+```python
+from datarecon import reconcile
+
+result = reconcile(
+    "source.csv", "warehouse_export.csv",
+    key="student_id",
+    rules={"score": {"tolerance": 0.01}},
+    treat_as_equal={"case", "whitespace"},
+)
+print(result.summary())
+result.to_excel("reconciliation.xlsx")
+```
+
+```
+datarecon compare source.csv target.csv --key student_id -o report.xlsx --fail-on-diff
+```
+
+## What it detects
+
+| Cause | Example |
+|---|---|
+| `leading_zeros` | `00123` vs `123` |
+| `null_vs_blank` | `None` vs `""` vs `NULL` |
+| `whitespace` / `case` | `Mary  Jones` vs `MARY JONES` |
+| `numeric_format` | `0.0` vs `00`, `10` vs `10.00` |
+| `numeric_tolerance` | `10.004` vs `10.00` with `tolerance=0.01` |
+| `date_format` | `2026-09-01` vs `09/01/2026` (month-first) |
+| `similar_text` | `Ann Lee` vs `Anne Lee` (opt-in via `fuzzy_threshold`) |
+| `value_mismatch` | everything else |
+
+Also reported: rows missing on either side, duplicate keys, null keys, columns present on only one side.
+
+Key values are matched after trimming, case folding and stripping leading zeros. Files are read as strings so no information is lost before comparison.
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+```

datarecon-0.1.0/src/datarecon.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/datarecon/__init__.py
+src/datarecon/cli.py
+src/datarecon/core.py
+src/datarecon/normalize.py
+src/datarecon/result.py
+src/datarecon.egg-info/PKG-INFO
+src/datarecon.egg-info/SOURCES.txt
+src/datarecon.egg-info/dependency_links.txt
+src/datarecon.egg-info/entry_points.txt
+src/datarecon.egg-info/requires.txt
+src/datarecon.egg-info/top_level.txt
+tests/test_reconcile.py

datarecon-0.1.0/src/datarecon.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

datarecon-0.1.0/src/datarecon.egg-info/entry_points.txt

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

datarecon-0.1.0/src/datarecon.egg-info/requires.txt

@@ -0,0 +1,9 @@
+pandas>=2.0
+numpy>=1.23
+
+[dev]
+pytest>=7
+openpyxl>=3.1
+
+[excel]
+openpyxl>=3.1

datarecon-0.1.0/src/datarecon.egg-info/top_level.txt

@@ -0,0 +1 @@
+datarecon

datarecon-0.1.0/tests/test_reconcile.py

@@ -0,0 +1,100 @@
+import pandas as pd
+import pytest
+
+from datarecon import reconcile
+from datarecon.cli import main
+
+
+def frames():
+    source = pd.DataFrame(
+        {
+            "Student_ID": ["001234", "005678", "009999", "000111", "000111", "000222"],
+            "Name": ["John Smith", "Mary  Jones", "Ann Lee", "Bob Ray", "Bob Ray", "Cy Young"],
+            "DOB": ["2026-09-01", "2010-01-15", "2011-03-03", "2012-04-04", "2012-04-04", "2013-05-05"],
+            "Score": ["10.00", "20.5", "30", "40", "40", "50"],
+            "Status": [None, "A", "B", "C", "C", "D"],
+        }
+    )
+    target = pd.DataFrame(
+        {
+            "STUDENT_ID": [1234, 5678, 9999, 111, 333],
+            "NAME": ["JOHN SMITH", "Mary Jones", "Anne Lee", "Bob Ray", "New Kid"],
+            "DOB": ["09/01/2026", "2010-01-15", "2011-03-04", "2012-04-04", "2014-06-06"],
+            "SCORE": [10.004, 20.5, 30, 40, 60],
+            "STATUS": ["", "A", "B", "X", "E"],
+        }
+    )
+    return source, target
+
+
+def causes(result):
+    return dict(zip(zip(result.differences["key"], result.differences["column"]), result.differences["cause"]))
+
+
+def test_key_normalization_matches_leading_zeros():
+    result = reconcile(*frames(), key="student_id")
+    assert result.matched_keys == 4
+    assert [k for k in result.missing_in_target["Student_ID"]] == ["000222"]
+    assert list(result.missing_in_source["STUDENT_ID"]) == ["333"]
+
+
+def test_causes_are_classified():
+    result = reconcile(*frames(), key="student_id", rules={"score": {"tolerance": 0.01}}, fuzzy_threshold=0.8)
+    found = causes(result)
+    assert found[("001234", "Name")] == "case"
+    assert found[("001234", "DOB")] == "date_format"
+    assert found[("001234", "Status")] == "null_vs_blank"
+    assert found[("005678", "Name")] == "whitespace"
+    assert found[("009999", "Name")] == "similar_text"
+    assert found[("009999", "DOB")] == "value_mismatch"
+    assert found[("000111", "Status")] == "value_mismatch"
+    assert ("001234", "Score") not in found  # within tolerance
+
+
+def test_row_buckets_and_duplicates():
+    result = reconcile(*frames(), key="student_id", rules={"score": {"tolerance": 0.01}})
+    assert result.formatting_rows == 2
+    assert result.mismatch_rows == 2
+    assert result.exact_rows == 0
+    assert result.duplicates["key"].tolist() == ["000111"]
+
+
+def test_treat_as_equal():
+    result = reconcile(*frames(), key="student_id", treat_as_equal={"case", "date_format", "null_vs_blank"})
+    assert "case" not in set(result.differences["cause"])
+    assert result.ignored_cells >= 3
+
+
+def test_numeric_format_and_multi_key():
+    a = pd.DataFrame({"a": ["1", "2"], "b": ["x", "y"], "v": ["0.0", "5"]})
+    b = pd.DataFrame({"A": [1, 2], "B": ["X", "y"], "V": ["00", "5.0"]})
+    result = reconcile(a, b, key=["a", "b"])
+    assert result.matched_keys == 2
+    assert set(result.differences["cause"]) == {"numeric_format"}
+
+
+def test_missing_key_column_raises():
+    a, b = frames()
+    with pytest.raises(KeyError):
+        reconcile(a, b, key="nope")
+
+
+def test_summary_and_excel_and_cli(tmp_path):
+    a, b = frames()
+    a.to_csv(tmp_path / "a.csv", index=False)
+    b.to_csv(tmp_path / "b.csv", index=False)
+    report = tmp_path / "out.xlsx"
+    code = main(["compare", str(tmp_path / "a.csv"), str(tmp_path / "b.csv"),
+                 "--key", "student_id", "-o", str(report), "--fail-on-diff"])
+    assert code == 1
+    assert report.exists()
+    sheets = pd.read_excel(report, sheet_name=None, dtype=str)
+    assert {"Summary", "Differences", "Missing in target", "Duplicate keys"} <= set(sheets)
+    assert "Reconciliation Summary" in reconcile(a, b, key="student_id").summary()
+
+
+def test_identical_frames():
+    a, _ = frames()
+    result = reconcile(a, a, key="student_id")
+    assert result.mismatch_rows == 0 and result.formatting_rows == 0
+    assert result.duplicates["key"].tolist() == ["000111", "000111"]