tracepipe 0.3.1__tar.gz → 0.3.3__tar.gz

{tracepipe-0.3.1 → tracepipe-0.3.3}/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to TracePipe will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.3.3 - 2026-02-03
+
+### Fixed
+- **Double-logging bug**: `df['col'] = df['col'].fillna()` now logs exactly one event, not two
+  - Fixed duplicate capture from both `_wrap_setitem` and `wrap_series_assignment`
+- **Merge warning scoping**: `tp.check(df)` now only shows warnings for merges in df's lineage
+  - Previously showed warnings from ALL merges in the session (cross-contamination)
+  - Now filters by tracking which merge steps produced the queried DataFrame's rows
+
+### Added
+- `_get_merge_stats_for_df()` helper to scope merge warnings to df's lineage
+- Tests for double-logging prevention and merge warning scoping
+
+## 0.3.2 - 2026-02-03
+
+### Fixed
+- Merge duplicate key warnings now correctly identify which table (left/right) has duplicates
+- Previously `right_dup_rate` was mislabeled as "Right table" when it actually indicates LEFT table duplicates
+
 ## 0.3.1 - 2026-02-03
 
 ### Fixed

{tracepipe-0.3.1 → tracepipe-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tracepipe
-Version: 0.3.1
+Version: 0.3.3
 Summary: Row-level data lineage tracking for pandas pipelines
 Project-URL: Homepage, https://github.com/tracepipe/tracepipe
 Project-URL: Documentation, https://tracepipe.github.io/tracepipe/

{tracepipe-0.3.1 → tracepipe-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tracepipe"
-version = "0.3.1"
+version = "0.3.3"
 description = "Row-level data lineage tracking for pandas pipelines"
 readme = "README.md"
 license = {file = "LICENSE"}

{tracepipe-0.3.1 → tracepipe-0.3.3}/tests/test_lineage_through_merge.py

@@ -262,6 +262,135 @@ class TestFillnaTrackingVerification:
         ), f"loc assignment should be tracked, got {result.n_changes} changes"
 
 
+class TestMergeWarningLabeling:
+    """Tests for correct left/right labeling in merge warnings."""
+
+    def test_duplicate_left_keys_warns_about_left(self):
+        """When LEFT has duplicate keys, warning should say 'Left table'."""
+        tp.enable(mode="debug")
+
+        # LEFT has duplicate key (94107 appears twice)
+        left = pd.DataFrame({"zip": ["10001", "94107", "94107"], "val": [1, 2, 3]})
+        # RIGHT has unique keys
+        right = pd.DataFrame({"zip": ["10001", "94107", "99999"], "region": ["NY", "CA", "XX"]})
+
+        df = left.merge(right, on="zip", how="left")
+        result = tp.check(df)
+
+        # Should warn about LEFT having duplicates, not RIGHT
+        dup_warnings = [w for w in result.warnings if "duplicate" in w.message.lower()]
+        assert len(dup_warnings) >= 1, "Should have duplicate key warning"
+
+        # The warning should mention "Left table", not "Right table"
+        left_warnings = [w for w in dup_warnings if "left" in w.message.lower()]
+        right_warnings = [w for w in dup_warnings if "right" in w.message.lower()]
+
+        assert len(left_warnings) >= 1, (
+            f"Should warn about LEFT table having duplicates. "
+            f"Got warnings: {[w.message for w in dup_warnings]}"
+        )
+        # RIGHT is unique, shouldn't warn about right
+        assert len(right_warnings) == 0, (
+            f"Should NOT warn about RIGHT table (it's unique). "
+            f"Got warnings: {[w.message for w in dup_warnings]}"
+        )
+
+    def test_duplicate_right_keys_warns_about_right(self):
+        """When RIGHT has duplicate keys, warning should say 'Right table'."""
+        tp.enable(mode="debug")
+
+        # LEFT has unique keys
+        left = pd.DataFrame({"zip": ["10001", "94107"], "val": [1, 2]})
+        # RIGHT has duplicate key (94107 appears twice)
+        right = pd.DataFrame({"zip": ["10001", "94107", "94107"], "region": ["NY", "CA", "CA2"]})
+
+        df = left.merge(right, on="zip", how="left")
+        result = tp.check(df)
+
+        dup_warnings = [w for w in result.warnings if "duplicate" in w.message.lower()]
+        assert len(dup_warnings) >= 1, "Should have duplicate key warning"
+
+        # The warning should mention "Right table"
+        right_warnings = [w for w in dup_warnings if "right" in w.message.lower()]
+        assert len(right_warnings) >= 1, (
+            f"Should warn about RIGHT table having duplicates. "
+            f"Got warnings: {[w.message for w in dup_warnings]}"
+        )
+
+
+class TestNoDoubleLogging:
+    """Tests to verify no duplicate events are logged."""
+
+    def test_fillna_logs_once_not_twice(self):
+        """df['col'] = df['col'].fillna() should log exactly one event per row."""
+        tp.enable(mode="debug", watch=["income"])
+
+        df = pd.DataFrame({"id": [1], "income": [None]})
+        df["income"] = df["income"].fillna(0)
+
+        result = tp.why(df, col="income", row=0)
+
+        # Should have exactly 1 change event, not 2 (no double-logging)
+        assert result.n_changes == 1, (
+            f"Expected exactly 1 change event, got {result.n_changes}. "
+            f"Double-logging bug if > 1. History: {result.history}"
+        )
+
+    def test_setitem_logs_once(self):
+        """Direct column assignment should log exactly once."""
+        tp.enable(mode="debug", watch=["val"])
+
+        df = pd.DataFrame({"id": [1], "val": [10]})
+        df["val"] = df["val"] * 2
+
+        result = tp.why(df, col="val", row=0)
+
+        assert result.n_changes == 1, (
+            f"Expected exactly 1 change event, got {result.n_changes}. "
+            f"History: {result.history}"
+        )
+
+
+class TestMergeWarningScoping:
+    """Tests for merge warnings being scoped to df's lineage."""
+
+    def test_check_only_shows_warnings_for_df_lineage(self):
+        """check(df) should only show warnings from merges that produced df."""
+        tp.enable(mode="debug")
+
+        # First pipeline - merge with unique right
+        left1 = pd.DataFrame({"k": ["a", "a", "b"], "v": [1, 2, 3]})  # Dup left
+        right1 = pd.DataFrame({"k": ["a", "b", "c"], "r": [10, 20, 30]})  # Unique
+        df1 = left1.merge(right1, on="k", how="left")
+
+        # Second pipeline - merge with duplicate right
+        left2 = pd.DataFrame({"k": ["x", "y"], "v": [1, 2]})  # Unique
+        right2 = pd.DataFrame({"k": ["x", "x", "y"], "r": [10, 11, 20]})  # Dup right
+        df2 = left2.merge(right2, on="k", how="left")
+
+        # check(df1) should only show warnings about LEFT duplicates (from df1's merge)
+        result1 = tp.check(df1)
+        dup_warnings1 = [w for w in result1.warnings if "duplicate" in w.message.lower()]
+
+        # check(df2) should only show warnings about RIGHT duplicates (from df2's merge)
+        result2 = tp.check(df2)
+        dup_warnings2 = [w for w in result2.warnings if "duplicate" in w.message.lower()]
+
+        # df1's check should NOT include df2's "Right table" warning
+        right_in_df1 = [w for w in dup_warnings1 if "right" in w.message.lower()]
+        assert len(right_in_df1) == 0, (
+            f"df1 check should not have Right table warnings (from df2). "
+            f"Got: {[w.message for w in dup_warnings1]}"
+        )
+
+        # df2's check should NOT include df1's "Left table" warning
+        left_in_df2 = [w for w in dup_warnings2 if "left" in w.message.lower()]
+        assert len(left_in_df2) == 0, (
+            f"df2 check should not have Left table warnings (from df1). "
+            f"Got: {[w.message for w in dup_warnings2]}"
+        )
+
+
 class TestLineageDepthLimit:
     """Tests for lineage traversal depth limiting."""
 

{tracepipe-0.3.1 → tracepipe-0.3.3}/tracepipe/__init__.py

@@ -81,7 +81,7 @@ from .core import TracePipeConfig, TracePipeMode
 from .snapshot import DiffResult, Snapshot, diff, snapshot
 
 # === VERSION ===
-__version__ = "0.3.1"
+__version__ = "0.3.3"
 
 # === MINIMAL __all__ ===
 __all__ = [

{tracepipe-0.3.1 → tracepipe-0.3.3}/tracepipe/convenience.py

@@ -361,8 +361,8 @@ def check(
     facts["rows_dropped"] = len(dropped)
     facts["total_steps"] = len(ctx.store.steps)
 
-    # Merge statistics
-    merge_stats_list = ctx.store.get_merge_stats() if hasattr(ctx.store, "get_merge_stats") else []
+    # Merge statistics - filter to df's lineage to avoid cross-contamination
+    merge_stats_list = _get_merge_stats_for_df(df, ctx)
 
     for i, (step_id, stats) in enumerate(merge_stats_list):
         facts[f"merge_{i}_expansion"] = stats.expansion_ratio
@@ -385,22 +385,27 @@ def check(
                 )
             )
 
-        if stats.left_dup_rate > 0.01:
+        # Note on dup_rate semantics:
+        # - left_dup_rate = fraction of LEFT rows appearing >1 times in result
+        #   This happens when RIGHT table has duplicate join keys
+        # - right_dup_rate = fraction of RIGHT rows appearing >1 times in result
+        #   This happens when LEFT table has duplicate join keys
+        if stats.right_dup_rate > 0.01:
             warnings_list.append(
                 CheckWarning(
                     category="duplicate_keys",
                     severity="fact",
-                    message=f"Left table has {stats.left_dup_rate:.1%} duplicate join keys",
-                    details={"step_id": step_id, "dup_rate": stats.left_dup_rate},
+                    message=f"Left table has {stats.right_dup_rate:.1%} duplicate join keys",
+                    details={"step_id": step_id, "dup_rate": stats.right_dup_rate},
                 )
             )
-        if stats.right_dup_rate > 0.01:
+        if stats.left_dup_rate > 0.01:
             warnings_list.append(
                 CheckWarning(
                     category="duplicate_keys",
                     severity="fact",
-                    message=f"Right table has {stats.right_dup_rate:.1%} duplicate join keys",
-                    details={"step_id": step_id, "dup_rate": stats.right_dup_rate},
+                    message=f"Right table has {stats.left_dup_rate:.1%} duplicate join keys",
+                    details={"step_id": step_id, "dup_rate": stats.left_dup_rate},
                 )
             )
 
@@ -653,6 +658,53 @@ def find(
 # ============ HELPERS ============
 
 
+def _get_merge_stats_for_df(df: pd.DataFrame, ctx) -> list[tuple[int, Any]]:
+    """
+    Get merge stats relevant to df's lineage only.
+
+    This prevents cross-contamination where check(df) would show warnings
+    from merges that produced OTHER DataFrames in the same session.
+    """
+    if not hasattr(ctx.store, "get_merge_stats"):
+        return []
+
+    all_stats = ctx.store.get_merge_stats()
+    if not all_stats:
+        return []
+
+    # Get row IDs from df
+    rids = ctx.row_manager.get_ids_array(df)
+    if rids is None:
+        return []
+
+    # Find which merge steps produced rows in df
+    relevant_step_ids = set()
+
+    # Check merge mappings to find which merges produced df's rows
+    if hasattr(ctx.store, "merge_mappings"):
+        for mapping in ctx.store.merge_mappings:
+            # Check if any of df's row IDs are in this merge's output
+            for rid in rids:
+                # Binary search in sorted out_rids
+                i = np.searchsorted(mapping.out_rids, rid)
+                if i < len(mapping.out_rids) and mapping.out_rids[i] == rid:
+                    relevant_step_ids.add(mapping.step_id)
+                    break  # Found at least one match, this merge is relevant
+
+    # If no merge mappings found, fall back to checking if df was just merged
+    # by seeing if it has more columns than typical (heuristic)
+    if not relevant_step_ids and all_stats:
+        # Fallback: return only the most recent merge that could have produced df
+        # This handles the case where merge_mappings aren't available
+        for step_id, stats in reversed(all_stats):
+            if stats.result_rows == len(df):
+                relevant_step_ids.add(step_id)
+                break
+
+    # Filter stats to relevant merges only
+    return [(sid, stats) for sid, stats in all_stats if sid in relevant_step_ids]
+
+
 def _json_safe(val: Any) -> Any:
     """Convert value to JSON-serializable form."""
     if pd.isna(val):

{tracepipe-0.3.1 → tracepipe-0.3.3}/tracepipe/instrumentation/series_capture.py

@@ -116,6 +116,10 @@ def wrap_series_assignment():
     """
     Wrap DataFrame.__setitem__ to capture diffs when assigning Series.
 
+    Note: For watched columns, _wrap_setitem (pandas_inst.py) already captures
+    the assignment. This wrapper only captures for NON-watched columns when
+    a TrackedSeries is assigned, to avoid double-logging.
+
     Handles:
     - df['col'] = series  (where series may have been modified)
     - df['col'] = scalar  (broadcast assignment)
@@ -127,28 +131,33 @@ def wrap_series_assignment():
     def tracked_setitem(self, key, value):
         ctx = get_context()
 
-        # Capture before state for watched columns
+        # For watched columns, _wrap_setitem already captures - skip to avoid double-logging
+        # We only capture here for NON-watched columns when a TrackedSeries is involved
+        should_capture_here = False
         before_values = None
+
         if (
             ctx.enabled
             and isinstance(key, str)
-            and key in ctx.watched_columns
             and key in self.columns
+            and key not in ctx.watched_columns  # Only capture NON-watched columns here
+            and isinstance(value, TrackedSeries)  # Only for TrackedSeries assignments
         ):
             rids = ctx.row_manager.get_ids_array(self)
             if rids is not None:
+                should_capture_here = True
                 before_values = {
                     "rids": rids.copy(),
                     "values": self[key].values.copy(),
                 }
 
-        # Always run original
+        # Always run original (which may be _wrap_setitem's wrapper)
         original_setitem(self, key, value)
 
         if not ctx.enabled:
             return
 
-        if before_values is None:
+        if not should_capture_here or before_values is None:
             return
 
         try:

{tracepipe-0.3.1 → tracepipe-0.3.3}/tracepipe/storage/lineage_store.py

@@ -710,7 +710,7 @@ class InMemoryLineageStore:
         diffs = list(self._iter_all_diffs())
 
         data = {
-            "tracepipe_version": "0.3.1",
+            "tracepipe_version": "0.3.2",
             "export_timestamp": time.time(),
             "total_diffs": len(diffs),
             "total_steps": len(self._steps),

{tracepipe-0.3.1 → tracepipe-0.3.3}/uv.lock

@@ -2051,7 +2051,7 @@ wheels = [
 
 [[package]]
 name = "tracepipe"
-version = "0.3.0"
+version = "0.3.2"
 source = { editable = "." }
 dependencies = [
     { name = "numpy", version = "2.0.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },