Joining on a key you think is unique, but isn't, silently multiplies rows and inflates every sum downstream. Validate joins before trusting them.
Implement:
key_report(left, right, on): a dict with "left_only", "right_only" and "both" (counts of distinct keys), "left_dupes" and "right_dupes" (counts of distinct keys appearing more than once on each side) and "row_multiplier" (rows in the inner join divided by rows in left)safe_merge(left, right, on, how="inner", expect="many_to_one"): expect is "one_to_one", "one_to_many" or "many_to_one". If the side that should be unique has duplicate keys, raise ValueError naming the side ("left" or "right") and one duplicated key (the smallest). Otherwise return left.merge(right, on=on, how=how).on is a single column name.