dataproof 0.1.0__tar.gz

dataproof-0.1.0/LICENSE

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

dataproof-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: dataproof
+Version: 0.1.0
+Summary: Find out what your dataframe code actually did — silent row loss, join fan-out, misleading statistics
+Author: oluwagbemilesi
+License: MIT
+Keywords: pandas,data-quality,verification,observability,AI,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas<4.0.0,>=2.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+# dataproof
+
+Find out what your dataframe code actually did.
+
+```python
+import pandas as pd, dataproof
+
+with dataproof.observe() as report:
+    orders = pd.read_csv("orders.csv")
+    clean  = orders.dropna()
+    joined = clean.merge(tiers, on="customer_id")
+    gold   = (joined.tier == "gold").sum()
+
+print(f"gold customers: {gold}")
+print(report)
+```
+
+```
+gold customers: 0
+dataproof: 1 finding(s)
+  - dropna() removed ALL 122 rows — a row was dropped if any value in it was
+    null. Pass how='all', a subset=[...] of columns that matter, or thresh=N
+    to keep partly-populated rows.  [analysis.py:5]
+```
+
+The answer was zero. The real answer was 33. One column in that file was
+entirely empty, so every row contained a null, so `dropna()` removed all of
+them — and pandas said nothing, because nothing went wrong as far as pandas is
+concerned.
+
+That is the problem this solves. Not crashes: crashes are easy. **Plausible
+answers that are quietly wrong.**
+
+## What it watches for
+
+| | |
+|---|---|
+| **Silent row loss** | `dropna()` that empties a frame, deduplication that removes most of it |
+| **Join fan-out** | a repeated key multiplying rows instead of pairing them |
+| **Joins that matched nothing** | usually a type mismatch — `1` and `"1"` do not join |
+| **Unmatched rows in a left join** | row count unchanged, but a third of the result is null on one side |
+| **Numbers stored as text** | statistics silently computed over nothing |
+| **Derived correlations** | `r = 1.000` because one column was computed from the other |
+| **Sparse columns** | a confident mean resting on 4 of 60 values |
+
+## What it does not do
+
+**It does not change your results.** Every wrapped call returns exactly what
+pandas returned. The code inside the block is ordinary pandas.
+
+**It does not ask you to write differently.** No new API to learn, no wrapper
+types, no rewriting a pipeline to use someone else's functions. That is
+deliberate — a verification tool you have to remember to call is one you will
+not call.
+
+**It does not cry wolf.** Every threshold here exists because a noisier version
+was tried and rejected. A group-by is not a 96% row loss. A few points beyond
+the IQR fence are not outliers worth reporting unless they actually move the
+mean. **A finding that fires on correct code teaches you to skip all of them**,
+which is worse than having none.
+
+## Install
+
+```bash
+pip install dataproof
+```
+
+Pandas is the only dependency.
+
+## Also useful
+
+Check any frame on demand, without a block:
+
+```python
+dataproof.Report().check(df)
+```
+
+Use it as an assertion in a pipeline or a notebook:
+
+```python
+with dataproof.observe() as report:
+    ...
+assert report.ok, str(report)
+```
+
+## Why this exists
+
+It came out of building a data library for AI agents, and measuring what agents
+actually do. Given six purpose-built tools and a free choice, an agent used none
+of them and wrote pandas — correctly. The tools were not the problem. The
+problem was that neither the agent nor the person reading its answer could tell
+when an operation had quietly destroyed the data.
+
+Agents now write a great deal of dataframe code, at a speed no one reviews line
+by line. They are good at it. But `dropna()` behaves the same for everyone, and
+the failure is silent for everyone.
+
+MIT licensed.

dataproof-0.1.0/README.md

@@ -0,0 +1,98 @@
+# dataproof
+
+Find out what your dataframe code actually did.
+
+```python
+import pandas as pd, dataproof
+
+with dataproof.observe() as report:
+    orders = pd.read_csv("orders.csv")
+    clean  = orders.dropna()
+    joined = clean.merge(tiers, on="customer_id")
+    gold   = (joined.tier == "gold").sum()
+
+print(f"gold customers: {gold}")
+print(report)
+```
+
+```
+gold customers: 0
+dataproof: 1 finding(s)
+  - dropna() removed ALL 122 rows — a row was dropped if any value in it was
+    null. Pass how='all', a subset=[...] of columns that matter, or thresh=N
+    to keep partly-populated rows.  [analysis.py:5]
+```
+
+The answer was zero. The real answer was 33. One column in that file was
+entirely empty, so every row contained a null, so `dropna()` removed all of
+them — and pandas said nothing, because nothing went wrong as far as pandas is
+concerned.
+
+That is the problem this solves. Not crashes: crashes are easy. **Plausible
+answers that are quietly wrong.**
+
+## What it watches for
+
+| | |
+|---|---|
+| **Silent row loss** | `dropna()` that empties a frame, deduplication that removes most of it |
+| **Join fan-out** | a repeated key multiplying rows instead of pairing them |
+| **Joins that matched nothing** | usually a type mismatch — `1` and `"1"` do not join |
+| **Unmatched rows in a left join** | row count unchanged, but a third of the result is null on one side |
+| **Numbers stored as text** | statistics silently computed over nothing |
+| **Derived correlations** | `r = 1.000` because one column was computed from the other |
+| **Sparse columns** | a confident mean resting on 4 of 60 values |
+
+## What it does not do
+
+**It does not change your results.** Every wrapped call returns exactly what
+pandas returned. The code inside the block is ordinary pandas.
+
+**It does not ask you to write differently.** No new API to learn, no wrapper
+types, no rewriting a pipeline to use someone else's functions. That is
+deliberate — a verification tool you have to remember to call is one you will
+not call.
+
+**It does not cry wolf.** Every threshold here exists because a noisier version
+was tried and rejected. A group-by is not a 96% row loss. A few points beyond
+the IQR fence are not outliers worth reporting unless they actually move the
+mean. **A finding that fires on correct code teaches you to skip all of them**,
+which is worse than having none.
+
+## Install
+
+```bash
+pip install dataproof
+```
+
+Pandas is the only dependency.
+
+## Also useful
+
+Check any frame on demand, without a block:
+
+```python
+dataproof.Report().check(df)
+```
+
+Use it as an assertion in a pipeline or a notebook:
+
+```python
+with dataproof.observe() as report:
+    ...
+assert report.ok, str(report)
+```
+
+## Why this exists
+
+It came out of building a data library for AI agents, and measuring what agents
+actually do. Given six purpose-built tools and a free choice, an agent used none
+of them and wrote pandas — correctly. The tools were not the problem. The
+problem was that neither the agent nor the person reading its answer could tell
+when an operation had quietly destroyed the data.
+
+Agents now write a great deal of dataframe code, at a speed no one reviews line
+by line. They are good at it. But `dropna()` behaves the same for everyone, and
+the failure is silent for everyone.
+
+MIT licensed.

dataproof-0.1.0/dataproof/__init__.py

@@ -0,0 +1,28 @@
+"""dataproof — find out what your dataframe code actually did.
+
+Pandas fails quietly. `dropna()` on a frame with one empty column removes every
+row. A join with a repeated key multiplies rows instead of pairing them. A
+filter that matches nothing returns an empty frame, not an error. Each produces
+a plausible answer that nothing questions.
+
+    import dataproof
+
+    with dataproof.observe() as report:
+        orders = pd.read_csv("orders.csv")
+        clean = orders.dropna()
+        joined = clean.merge(tiers, on="customer_id")
+
+    print(report)
+
+The code inside the block is ordinary pandas, unchanged and unaffected. The
+report says what it did.
+"""
+from dataproof._observer import Finding, Report, observe
+
+__all__ = ["observe", "Report", "Finding"]
+
+try:
+    from importlib.metadata import PackageNotFoundError, version as _version
+    __version__ = _version("dataproof")
+except Exception:  # a source tree that was never installed
+    __version__ = "0.0.0.dev0"

dataproof-0.1.0/dataproof/_observer.py

@@ -0,0 +1,240 @@
+"""Watch what pandas actually did, without changing what it does.
+
+The design constraint that produced this: a verification tool the analyst has to
+*choose to call* will not be called. That was measured — an AI agent given six
+purpose-built data tools and a free choice used none of them and wrote pandas
+instead, because pandas is right there and already understood.
+
+So this does not ask anyone to write different code. It wraps a handful of
+pandas methods for the duration of a block, records anything surprising, and
+puts the originals back. The code inside the block is ordinary pandas and
+behaves identically; the only difference is that afterwards you can ask what it
+did.
+
+Three rules this module holds itself to:
+
+1. **Never change a result.** Every wrapper returns exactly what pandas returned.
+2. **Always restore.** The patch is undone in a finally block, even on an
+   exception, so a crash inside the block cannot leave pandas modified.
+3. **Never raise from a check.** A bug in a rule must not break the analysis it
+   is observing, so every check is wrapped and failures are swallowed.
+"""
+import functools
+import traceback
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import pandas as pd
+
+from dataproof import _rules
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One thing an operation did that the caller may not have intended."""
+
+    operation: str
+    message: str
+    location: str = ""
+
+    def __str__(self):
+        where = f"  [{self.location}]" if self.location else ""
+        return f"{self.operation}() {self.message}{where}"
+
+
+@dataclass
+class Report:
+    """What the observed code did. Empty means nothing surprising happened."""
+
+    findings: list = field(default_factory=list)
+
+    @property
+    def ok(self):
+        return not self.findings
+
+    def __len__(self):
+        return len(self.findings)
+
+    def __iter__(self):
+        return iter(self.findings)
+
+    def __str__(self):
+        if not self.findings:
+            return "dataproof: nothing surprising."
+        lines = [f"dataproof: {len(self.findings)} finding(s)"]
+        lines += [f"  - {f}" for f in self.findings]
+        return "\n".join(lines)
+
+    def check(self, df, label="frame"):
+        """Inspect a finished frame on demand: sparse columns, derived
+        correlations, nothing numeric to compute over."""
+        for message in _safely(_rules.frame_quality, df) or []:
+            self.findings.append(Finding(label, message, _caller()))
+        return self
+
+
+def _safely(rule, *args, **kwargs):
+    """Run a rule, swallowing any failure. A broken check must never break the
+    analysis it is watching."""
+    try:
+        return rule(*args, **kwargs)
+    except Exception:
+        return None
+
+
+def _caller():
+    """The user's own line, skipping pandas internals and this package."""
+    here = str(Path(__file__).parent)
+    for frame in reversed(traceback.extract_stack()[:-1]):
+        name = frame.filename
+        if here in name or f"{'pandas'}{'/'}" in name or name.endswith("pandas/core/frame.py"):
+            continue
+        if "/pandas/" in name or "<frozen" in name:
+            continue
+        return f"{Path(name).name}:{frame.lineno}"
+    return ""
+
+
+class _Patcher:
+    """Applies the wrappers and guarantees they come off again."""
+
+    def __init__(self, report):
+        self.report = report
+        self.originals = []
+
+    def wrap(self, owner, name, make_wrapper):
+        original = getattr(owner, name, None)
+        if original is None:  # pandas version without this method
+            return
+        self.originals.append((owner, name, original))
+        setattr(owner, name, make_wrapper(original))
+
+    def restore(self):
+        for owner, name, original in reversed(self.originals):
+            setattr(owner, name, original)
+        self.originals.clear()
+
+    def record(self, operation, messages, location):
+        for message in messages or []:
+            if message:
+                self.report.findings.append(Finding(operation, message, location))
+
+
+def _install(patcher):
+    report_to = patcher.record
+
+    def dropna_wrapper(original):
+        @functools.wraps(original)
+        def dropna(self, *args, **kwargs):
+            before = len(self)
+            result = original(self, *args, **kwargs)
+            if isinstance(result, pd.DataFrame):
+                how = kwargs.get("how", "any")
+                report_to("dropna", [_safely(
+                    _rules.row_loss, before, len(result),
+                    f"a row was dropped if {'every' if how == 'all' else 'any'} "
+                    f"value in it was null.",
+                    "Pass how='all', a subset=[...] of columns that matter, or "
+                    "thresh=N to keep partly-populated rows.",
+                )], _caller())
+            return result
+        return dropna
+
+    def merge_wrapper(original):
+        @functools.wraps(original)
+        def merge(self, right, *args, **kwargs):
+            result = original(self, right, *args, **kwargs)
+            how = kwargs.get("how", "inner")
+            unmatched = None
+            if how in {"left", "outer"}:
+                unmatched = _safely(_unmatched_left, self, right, result, kwargs)
+            report_to("merge", _safely(
+                _rules.merge_result, len(self), len(right), len(result),
+                how=how, unmatched=unmatched,
+            ), _caller())
+            return result
+        return merge
+
+    def drop_duplicates_wrapper(original):
+        @functools.wraps(original)
+        def drop_duplicates(self, *args, **kwargs):
+            before = len(self)
+            result = original(self, *args, **kwargs)
+            if isinstance(result, pd.DataFrame):
+                report_to("drop_duplicates", [_safely(
+                    _rules.row_loss, before, len(result),
+                    "duplicate rows were removed.",
+                    "If duplicates are meaningful here, keep them or pass a subset.",
+                )], _caller())
+            return result
+        return drop_duplicates
+
+    patcher.wrap(pd.DataFrame, "dropna", dropna_wrapper)
+    patcher.wrap(pd.DataFrame, "merge", merge_wrapper)
+    patcher.wrap(pd.DataFrame, "drop_duplicates", drop_duplicates_wrapper)
+
+
+def _unmatched_left(left, right, result, kwargs):
+    """How many left rows found no match, read off the finished join.
+
+    Deliberately not recomputed from the keys. Building a set of the right-hand
+    keys and testing the left against it cost more than the merge itself — 71ms
+    against 46ms on 50k rows — which is exactly the kind of overhead that gets a
+    tool switched off. A left join already encodes the answer: an unmatched row
+    has nulls in every column that came from the right.
+
+    Uses a right-hand column that had no nulls to begin with, so a null in the
+    result can only mean "no match". Returns None when no such column exists,
+    because a wrong count is worse than no count.
+    """
+    on = kwargs.get("on")
+    right_on = kwargs.get("right_on", on)
+    keys = right_on if isinstance(right_on, (list, tuple)) else [right_on]
+    candidates = [c for c in right.columns if c not in keys]
+
+    for column in candidates:
+        # notna().all() short-circuits in C and is far cheaper than set + isin.
+        if not right[column].notna().all():
+            continue
+        merged_name = column if column in result.columns else f"{column}_y"
+        if merged_name not in result.columns:
+            continue
+        return int(result[merged_name].isna().sum())
+    return None
+
+
+class observe:
+    """Watch pandas for the duration of a block.
+
+        with dataproof.observe() as report:
+            df = pd.read_csv("export.csv")
+            df = df.dropna()
+            joined = df.merge(other, on="id")
+
+        print(report)
+
+    The code inside is unmodified pandas and produces identical results. Nesting
+    is allowed; only the outermost block patches and restores.
+    """
+
+    _depth = 0
+
+    def __init__(self):
+        self.report = Report()
+        self._patcher = None
+
+    def __enter__(self):
+        if observe._depth == 0:
+            self._patcher = _Patcher(self.report)
+            _install(self._patcher)
+        observe._depth += 1
+        return self.report
+
+    def __exit__(self, *exc):
+        observe._depth -= 1
+        if self._patcher is not None:
+            # finally-equivalent: restoring must happen even if the observed
+            # block raised, or every later import of pandas stays wrapped.
+            self._patcher.restore()
+            self._patcher = None
+        return False

dataproof-0.1.0/dataproof/_rules.py

@@ -0,0 +1,160 @@
+"""What counts as worth reporting, and what does not.
+
+These rules are the whole product. They were tuned over several releases of a
+data library, and the tuning — not the detection — is the hard part. Two lessons
+are baked into every threshold here:
+
+**A warning that fires on correct behaviour destroys the rest.** An early version
+reported a group-by collapsing 120 rows to 5 as a "96% row loss". That is a
+description of grouping, not a finding. Anyone who sees one false alarm stops
+reading all of them, so a rule that cannot stay quiet on healthy data is worse
+than no rule.
+
+**A warning must say what to do.** "Rows were dropped" is not actionable.
+"Removed 268 of 1000 rows (27%) because every row containing any null was
+dropped — pass how='all' or a subset" is.
+"""
+
+# Share of rows an operation may remove before it is worth reporting. Not zero:
+# a report on every removed row would fire constantly and teach the reader to
+# skip it. Total loss is always reported regardless.
+ROW_LOSS_SHARE = 0.10
+
+# Correlations this close to 1 are almost never a discovery — they are one
+# column derived from another, and reporting them as findings invites someone
+# to announce a tautology as an insight.
+DERIVED_CORRELATION = 0.999
+
+# A statistic computed from a handful of values carries far less weight than its
+# precision suggests, and nothing in "mean: 7.5" says so.
+SPARSE_COLUMN_SHARE = 0.50
+
+
+def _percent(part, whole):
+    return 0.0 if not whole else (part / whole) * 100
+
+
+def row_loss(rows_in, rows_out, cause, remedy=None, threshold=ROW_LOSS_SHARE):
+    """Report rows removed, or None if the loss is unremarkable.
+
+    Total loss is always reported, whatever the threshold: an empty result is
+    the single most misleading thing an operation can produce silently, and it
+    is exactly what a plain `dropna()` does to a frame with one empty column.
+    """
+    if rows_in <= 0 or rows_out >= rows_in:
+        return None
+
+    lost = rows_in - rows_out
+    if rows_out == 0:
+        message = f"removed ALL {rows_in} rows"
+    elif lost / rows_in >= threshold:
+        message = f"removed {lost} of {rows_in} rows ({_percent(lost, rows_in):.0f}%)"
+    else:
+        return None
+
+    message = f"{message} — {cause}"
+    return f"{message} {remedy}" if remedy else message
+
+
+def merge_result(left_rows, right_rows, result_rows, how="inner", unmatched=None):
+    """Report a join whose shape is probably not what was intended.
+
+    A join fails by multiplying rather than by raising, so nothing about a
+    successful result distinguishes a correct 3-row join from one that silently
+    became 9.
+    """
+    findings = []
+    if how == "cross":
+        return findings
+
+    # Fan-out is judged against the side the join is anchored to, not against
+    # max(left, right). A 2-row frame joined to a 3-row frame coming back with 3
+    # rows IS a fan-out — one left row matched twice — and comparing to the
+    # larger side missed exactly that case.
+    if (
+        (how in {"inner", "left"} and result_rows > left_rows)
+        or (how == "right" and result_rows > right_rows)
+        # An outer join legitimately exceeds either side, because unmatched rows
+        # from both are kept; it cannot exceed their sum without duplication.
+        or (how == "outer" and result_rows > left_rows + right_rows)
+    ):
+        findings.append(
+            f"joined {left_rows} x {right_rows} rows into {result_rows} — the key "
+            f"matched more than once, so rows were multiplied rather than paired. "
+            f"Pass validate='one_to_one' or 'many_to_one' to make that an error."
+        )
+    elif result_rows == 0 and left_rows and right_rows:
+        findings.append(
+            f"joined {left_rows} x {right_rows} rows into NOTHING — the key values "
+            f"do not overlap at all. Check the join column, and check its type: "
+            f"1 and '1' do not match."
+        )
+    elif how == "inner" and result_rows < left_rows:
+        findings.append(
+            f"inner join kept {result_rows} of {left_rows} left rows — the rest had "
+            f"no match and were dropped. Use how='left' to keep them."
+        )
+
+    if how in {"left", "outer"} and unmatched:
+        findings.append(
+            f"{unmatched} of {left_rows} left rows found no match, so their columns "
+            f"from the right frame are null. Counts and averages over those columns "
+            f"will be computed from {left_rows - unmatched} rows, not {left_rows}."
+        )
+    return findings
+
+
+def frame_quality(df):
+    """Report columns whose statistics would mislead, given a finished frame."""
+    import pandas as pd
+
+    findings = []
+    total = len(df)
+    if total == 0:
+        return ["the frame is empty — every statistic computed from it is undefined."]
+
+    numeric = [c for c in df.columns if pd.api.types.is_numeric_dtype(df[c])]
+    if not numeric:
+        text_numbers = []
+        for column in df.columns:
+            series = df[column]
+            non_null = int(series.count())
+            if not non_null:
+                continue
+            share = int(pd.to_numeric(series, errors="coerce").count()) / non_null
+            if share >= 0.5:
+                text_numbers.append(f"{column!r} ({share:.0%} numeric)")
+        message = "no column is numeric, so any statistic over this frame is empty."
+        if text_numbers:
+            message += (
+                f" Column(s) [{', '.join(text_numbers)}] hold numbers stored as "
+                f"text — convert them first."
+            )
+        findings.append(message)
+        return findings
+
+    for column in df.columns:
+        series = df[column]
+        non_null = int(series.count())
+        if non_null == 0:
+            findings.append(f"column {column!r} is entirely null.")
+            continue
+        null_share = 1 - non_null / total
+        if null_share >= SPARSE_COLUMN_SHARE and pd.api.types.is_numeric_dtype(series):
+            findings.append(
+                f"column {column!r} is {null_share:.0%} null — statistics come from "
+                f"{non_null} of {total} values, so treat them as indicative."
+            )
+
+    for i, left in enumerate(numeric):
+        for right in numeric[i + 1:]:
+            if df[left].count() < 2 or df[right].count() < 2:
+                continue
+            value = df[left].corr(df[right])
+            if value == value and abs(value) >= DERIVED_CORRELATION:
+                findings.append(
+                    f"columns {left!r} and {right!r} correlate at {value:.3f} — a "
+                    f"correlation this perfect usually means one is derived from "
+                    f"the other, not that a relationship was found."
+                )
+    return findings

dataproof-0.1.0/dataproof.egg-info/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: dataproof
+Version: 0.1.0
+Summary: Find out what your dataframe code actually did — silent row loss, join fan-out, misleading statistics
+Author: oluwagbemilesi
+License: MIT
+Keywords: pandas,data-quality,verification,observability,AI,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas<4.0.0,>=2.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+# dataproof
+
+Find out what your dataframe code actually did.
+
+```python
+import pandas as pd, dataproof
+
+with dataproof.observe() as report:
+    orders = pd.read_csv("orders.csv")
+    clean  = orders.dropna()
+    joined = clean.merge(tiers, on="customer_id")
+    gold   = (joined.tier == "gold").sum()
+
+print(f"gold customers: {gold}")
+print(report)
+```
+
+```
+gold customers: 0
+dataproof: 1 finding(s)
+  - dropna() removed ALL 122 rows — a row was dropped if any value in it was
+    null. Pass how='all', a subset=[...] of columns that matter, or thresh=N
+    to keep partly-populated rows.  [analysis.py:5]
+```
+
+The answer was zero. The real answer was 33. One column in that file was
+entirely empty, so every row contained a null, so `dropna()` removed all of
+them — and pandas said nothing, because nothing went wrong as far as pandas is
+concerned.
+
+That is the problem this solves. Not crashes: crashes are easy. **Plausible
+answers that are quietly wrong.**
+
+## What it watches for
+
+| | |
+|---|---|
+| **Silent row loss** | `dropna()` that empties a frame, deduplication that removes most of it |
+| **Join fan-out** | a repeated key multiplying rows instead of pairing them |
+| **Joins that matched nothing** | usually a type mismatch — `1` and `"1"` do not join |
+| **Unmatched rows in a left join** | row count unchanged, but a third of the result is null on one side |
+| **Numbers stored as text** | statistics silently computed over nothing |
+| **Derived correlations** | `r = 1.000` because one column was computed from the other |
+| **Sparse columns** | a confident mean resting on 4 of 60 values |
+
+## What it does not do
+
+**It does not change your results.** Every wrapped call returns exactly what
+pandas returned. The code inside the block is ordinary pandas.
+
+**It does not ask you to write differently.** No new API to learn, no wrapper
+types, no rewriting a pipeline to use someone else's functions. That is
+deliberate — a verification tool you have to remember to call is one you will
+not call.
+
+**It does not cry wolf.** Every threshold here exists because a noisier version
+was tried and rejected. A group-by is not a 96% row loss. A few points beyond
+the IQR fence are not outliers worth reporting unless they actually move the
+mean. **A finding that fires on correct code teaches you to skip all of them**,
+which is worse than having none.
+
+## Install
+
+```bash
+pip install dataproof
+```
+
+Pandas is the only dependency.
+
+## Also useful
+
+Check any frame on demand, without a block:
+
+```python
+dataproof.Report().check(df)
+```
+
+Use it as an assertion in a pipeline or a notebook:
+
+```python
+with dataproof.observe() as report:
+    ...
+assert report.ok, str(report)
+```
+
+## Why this exists
+
+It came out of building a data library for AI agents, and measuring what agents
+actually do. Given six purpose-built tools and a free choice, an agent used none
+of them and wrote pandas — correctly. The tools were not the problem. The
+problem was that neither the agent nor the person reading its answer could tell
+when an operation had quietly destroyed the data.
+
+Agents now write a great deal of dataframe code, at a speed no one reviews line
+by line. They are good at it. But `dropna()` behaves the same for everyone, and
+the failure is silent for everyone.
+
+MIT licensed.

dataproof-0.1.0/dataproof.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+dataproof/__init__.py
+dataproof/_observer.py
+dataproof/_rules.py
+dataproof.egg-info/PKG-INFO
+dataproof.egg-info/SOURCES.txt
+dataproof.egg-info/dependency_links.txt
+dataproof.egg-info/requires.txt
+dataproof.egg-info/top_level.txt
+tests/test_observer.py

dataproof-0.1.0/dataproof.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dataproof-0.1.0/dataproof.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pandas<4.0.0,>=2.2.0
+
+[dev]
+pytest>=8.0.0

dataproof-0.1.0/dataproof.egg-info/top_level.txt

@@ -0,0 +1 @@
+dataproof

dataproof-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dataproof"
+version = "0.1.0"
+description = "Find out what your dataframe code actually did — silent row loss, join fan-out, misleading statistics"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "oluwagbemilesi"}]
+keywords = ["pandas", "data-quality", "verification", "observability", "AI", "agents"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+
+dependencies = ["pandas>=2.2.0,<4.0.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["dataproof*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dataproof-0.1.0/setup.cfg

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

dataproof-0.1.0/tests/test_observer.py

@@ -0,0 +1,203 @@
+import numpy as np
+import pandas as pd
+import pytest
+
+import dataproof
+
+
+# --- the safety properties -------------------------------------------------
+# This patches a library everyone else's code depends on, so these matter more
+# than the findings themselves.
+
+def test_results_are_untouched():
+    df = pd.DataFrame({"a": [1.0, None, 3.0]})
+    expected = df.dropna()
+    with dataproof.observe():
+        observed = df.dropna()
+    pd.testing.assert_frame_equal(observed, expected)
+
+
+def test_pandas_is_restored_afterwards():
+    original = pd.DataFrame.dropna
+    with dataproof.observe():
+        assert pd.DataFrame.dropna is not original
+    assert pd.DataFrame.dropna is original
+
+
+def test_pandas_is_restored_after_an_exception():
+    # If a crash inside the block left pandas patched, every later import in
+    # the process would still be wrapped.
+    original = pd.DataFrame.merge
+    with pytest.raises(ValueError):
+        with dataproof.observe():
+            raise ValueError("boom")
+    assert pd.DataFrame.merge is original
+
+
+def test_nesting_restores_only_once():
+    original = pd.DataFrame.dropna
+    with dataproof.observe():
+        with dataproof.observe():
+            assert pd.DataFrame.dropna is not original
+        # the inner block must not have unpatched the outer one
+        assert pd.DataFrame.dropna is not original
+    assert pd.DataFrame.dropna is original
+
+
+def test_a_broken_rule_does_not_break_the_analysis(monkeypatch):
+    # A bug in a check must never take down the code it is watching.
+    from dataproof import _rules
+
+    def explode(*a, **k):
+        raise RuntimeError("rule is broken")
+
+    monkeypatch.setattr(_rules, "row_loss", explode)
+    df = pd.DataFrame({"a": [1.0, None]})
+    with dataproof.observe() as report:
+        result = df.dropna()
+    assert len(result) == 1
+    assert report.ok
+
+
+# --- the findings ----------------------------------------------------------
+
+def test_catches_dropna_removing_everything():
+    # The case that motivated the project: one entirely-empty column means every
+    # row holds a null, so a plain dropna() silently returns nothing.
+    df = pd.DataFrame({"keep": [1, 2, 3], "empty": [None, None, None]})
+    with dataproof.observe() as report:
+        result = df.dropna()
+    assert len(result) == 0
+    assert len(report) == 1
+    assert "removed ALL 3 rows" in str(report.findings[0])
+    assert "how='all'" in str(report.findings[0])
+
+
+def test_catches_a_join_that_multiplied_rows():
+    left = pd.DataFrame({"k": [1, 2]})
+    right = pd.DataFrame({"k": [1, 1, 2], "v": ["a", "b", "c"]})
+    with dataproof.observe() as report:
+        left.merge(right, on="k")
+    assert any("multiplied" in str(f) for f in report)
+
+
+def test_catches_a_join_that_matched_nothing():
+    with dataproof.observe() as report:
+        pd.DataFrame({"k": [1]}).merge(pd.DataFrame({"k": [99]}), on="k")
+    assert any("NOTHING" in str(f) for f in report)
+
+
+def test_catches_unmatched_rows_in_a_left_join():
+    # A left join keeps its row count, so nothing else reveals that a third of
+    # the result is null on one side.
+    left = pd.DataFrame({"k": range(10)})
+    right = pd.DataFrame({"k": range(6), "v": ["x"] * 6})
+    with dataproof.observe() as report:
+        left.merge(right, on="k", how="left")
+    assert any("4 of 10 left rows found no match" in str(f) for f in report)
+
+
+def test_catches_heavy_deduplication():
+    df = pd.DataFrame({"a": [1] * 50 + list(range(50))})
+    with dataproof.observe() as report:
+        df.drop_duplicates()
+    assert any("drop_duplicates" in str(f) for f in report)
+
+
+def test_findings_name_the_line():
+    df = pd.DataFrame({"a": [1.0, None], "b": [None, None]})
+    with dataproof.observe() as report:
+        df.dropna()
+    assert "test_observer.py:" in report.findings[0].location
+
+
+# --- silence on healthy work ----------------------------------------------
+# The property the whole tool depends on. A false alarm teaches the reader to
+# skip every finding, which is worse than having none.
+
+def test_silent_on_a_healthy_pipeline():
+    rng = np.random.default_rng(0)
+    df = pd.DataFrame({"k": range(200), "v": rng.normal(size=200)})
+    keys = pd.DataFrame({"k": range(200), "label": rng.choice(["a", "b"], 200)})
+    with dataproof.observe() as report:
+        clean = df.dropna()
+        joined = clean.merge(keys, on="k")
+        joined.drop_duplicates()
+    assert report.ok, str(report)
+
+
+def test_a_small_row_loss_is_not_reported():
+    df = pd.DataFrame({"a": [1.0] * 99 + [None]})
+    with dataproof.observe() as report:
+        df.dropna()
+    assert report.ok
+
+
+def test_a_clean_one_to_one_join_is_silent():
+    left = pd.DataFrame({"k": range(50)})
+    right = pd.DataFrame({"k": range(50), "v": range(50)})
+    with dataproof.observe() as report:
+        left.merge(right, on="k", how="left")
+    assert report.ok
+
+
+# --- on-demand frame checks ------------------------------------------------
+
+def test_check_reports_a_derived_correlation():
+    df = pd.DataFrame({"signups": range(1, 61)})
+    df["revenue"] = df["signups"] * 12.5
+    report = dataproof.Report().check(df)
+    assert any("derived from" in str(f) for f in report)
+
+
+def test_check_reports_numbers_stored_as_text():
+    df = pd.DataFrame({"revenue": ["1200.50", "980.00", "1450.75"]})
+    report = dataproof.Report().check(df)
+    assert any("stored as text" in str(f) for f in report)
+
+
+def test_check_reports_a_sparse_column():
+    df = pd.DataFrame({"nps": [None] * 56 + [7.0, 8.0, 9.0, 6.0]})
+    report = dataproof.Report().check(df)
+    assert any("93% null" in str(f) for f in report)
+
+
+def test_check_is_silent_on_a_healthy_frame():
+    rng = np.random.default_rng(1)
+    df = pd.DataFrame({"a": rng.normal(size=60), "b": rng.normal(size=60)})
+    assert dataproof.Report().check(df).ok
+
+
+# --- the report object -----------------------------------------------------
+
+def test_report_reads_well_when_empty():
+    assert "nothing surprising" in str(dataproof.Report())
+
+
+def test_report_is_iterable_and_sized():
+    df = pd.DataFrame({"a": [1.0], "b": [None]})
+    with dataproof.observe() as report:
+        df.dropna()
+    assert len(report) == 1
+    assert len(list(report)) == 1
+
+
+def test_fan_out_is_judged_against_the_anchored_side():
+    # 2 left rows becoming 3 is a fan-out, even though 3 does not exceed the
+    # 3-row right frame. Comparing against max(left, right) missed this.
+    left = pd.DataFrame({"k": [1, 2]})
+    right = pd.DataFrame({"k": [1, 1, 2], "v": ["a", "b", "c"]})
+    with dataproof.observe() as report:
+        result = left.merge(right, on="k")
+    assert len(result) == 3
+    assert any("multiplied" in str(f) for f in report)
+
+
+def test_outer_join_keeping_both_sides_is_not_a_fan_out():
+    # An outer join legitimately returns more rows than either input.
+    left = pd.DataFrame({"k": [1, 2]})
+    right = pd.DataFrame({"k": [3, 4], "v": ["a", "b"]})
+    with dataproof.observe() as report:
+        result = left.merge(right, on="k", how="outer")
+    assert len(result) == 4
+    assert not any("multiplied" in str(f) for f in report)