add validate argument to merge

Author: Nick Eubank

doc/source/whatsnew/v0.21.0.txt

@@ -20,6 +20,14 @@ Check the :ref:`API Changes <whatsnew_0210.api_breaking>` and :ref:`deprecations
 New features
 ~~~~~~~~~~~~
 
+.. _whatsnew_0210.enhancements.merge_validate:
+
+``validate`` argument checks merge key uniqueness
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``validate`` argument for :func:`merge` function now checks whether a merge is
+one-to-one, one-to-many, many-to-one, or many-to-many. If a merge is found to not 
+be an example of specified merge type, an exception will be raised. 
 
 
 .. _whatsnew_0210.enhancements.other:

pandas/core/frame.py

@@ -174,6 +174,17 @@
 
     .. versionadded:: 0.17.0
 
+validate: None or string, default None
+    If specified, checks to ensure merge is of specified type. 
+    If "one_to_one" or "1:1", checks merge keys are unique in both 
+    left and right dataset. 
+    If "one_to_many" or "1:m", checks merge keys are unique in left 
+    dataset. 
+    If "many_to_one" or "m:1", checks merge keys are unique in right 
+    dataset.     
+
+    .. versionadded:: 0.21.0
+
 Examples
 --------
 
@@ -4812,12 +4823,13 @@ def _join_compat(self, other, on=None, how='left', lsuffix='', rsuffix='',
     @Appender(_merge_doc, indents=2)
     def merge(self, right, how='inner', on=None, left_on=None, right_on=None,
               left_index=False, right_index=False, sort=False,
-              suffixes=('_x', '_y'), copy=True, indicator=False):
+              suffixes=('_x', '_y'), copy=True, indicator=False, 
+              validate=None):
         from pandas.core.reshape.merge import merge
         return merge(self, right, how=how, on=on, left_on=left_on,
                      right_on=right_on, left_index=left_index,
                      right_index=right_index, sort=sort, suffixes=suffixes,
-                     copy=copy, indicator=indicator)
+                     copy=copy, indicator=indicator, validate=validate)
 
     def round(self, decimals=0, *args, **kwargs):
         """

pandas/core/reshape/merge.py

@@ -46,11 +46,13 @@
 @Appender(_merge_doc, indents=0)
 def merge(left, right, how='inner', on=None, left_on=None, right_on=None,
           left_index=False, right_index=False, sort=False,
-          suffixes=('_x', '_y'), copy=True, indicator=False):
+          suffixes=('_x', '_y'), copy=True, indicator=False, 
+          validate=None):
     op = _MergeOperation(left, right, how=how, on=on, left_on=left_on,
                          right_on=right_on, left_index=left_index,
                          right_index=right_index, sort=sort, suffixes=suffixes,
-                         copy=copy, indicator=indicator)
+                         copy=copy, indicator=indicator, 
+                         validate=validate)
     return op.get_result()
 
 
@@ -498,7 +500,8 @@ class _MergeOperation(object):
     def __init__(self, left, right, how='inner', on=None,
                  left_on=None, right_on=None, axis=1,
                  left_index=False, right_index=False, sort=True,
-                 suffixes=('_x', '_y'), copy=True, indicator=False):
+                 suffixes=('_x', '_y'), copy=True, indicator=False,
+                 validate=None):
         self.left = self.orig_left = left
         self.right = self.orig_right = right
         self.how = how
@@ -516,6 +519,7 @@ def __init__(self, left, right, how='inner', on=None,
         self.right_index = right_index
 
         self.indicator = indicator
+        self.validate = validate
 
         if isinstance(self.indicator, compat.string_types):
             self.indicator_name = self.indicator
@@ -561,6 +565,9 @@ def __init__(self, left, right, how='inner', on=None,
         # to avoid incompat dtypes
         self._maybe_coerce_merge_keys()
 
+        if self.validate is not None:
+            self._validate()
+
     def get_result(self):
         if self.indicator:
             self.left, self.right = self._indicator_pre_merge(
@@ -952,6 +959,47 @@ def _validate_specification(self):
         if len(self.right_on) != len(self.left_on):
             raise ValueError("len(right_on) must equal len(left_on)")
 
+    def _validate(self):
+        
+        # Get merging series:
+        left_key = self.left_on if self.left_on is not None else self.on
+        right_key = self.right_on if self.right_on is not None else self.on
+
+        if self.left_index:
+            left_unique = not (self.orig_left.index.duplicated()).any()
+        else:
+            left_unique = not (self.orig_left[left_key].duplicated()).any()
+
+        if self.right_index:
+            right_unique = not (self.orig_right.index.duplicated()).any()
+        else:
+            right_unique = not (self.orig_right[right_key].duplicated()).any()
+
+        # Check valid arg
+        if self.validate not in ['one_to_one', '1:1',
+                                    'one_to_many', '1:m',
+                                    'many_to_one', 'm:1',
+                                    'many_to_many', 'm:m']:
+            
+            raise ValueError("Not a valid argument for validate")
+
+        # Check data integrity
+        if self.validate in ["one_to_one", "1:1"]:
+            if not left_unique or not right_unique:
+                raise ValueError("Merge keys are not unique in either left or right dataset; not a one-to-one merge")
+            if not left_unique:
+                raise ValueError("Merge keys are not unique in left dataset; not a one-to-one merge")
+            if not right_unique:
+                raise ValueError("Merge keys are not unique in right dataset; not a one-to-one merge")
+            
+        if self.validate in ["one_to_many", "1:m"]:
+            if not left_unique:
+                raise ValueError("Merge keys are not unique in left dataset; not a one-to-many merge")
+
+        if self.validate in ["many_to_one", "m:1"]:
+            if not right_unique:
+                raise ValueError("Merge keys are not unique in right dataset; not a many-to-one merge")
+
 
 def _get_join_indexers(left_keys, right_keys, sort=False, how='inner',
                        **kwargs):

pandas/tests/reshape/test_merge.py

@@ -725,6 +725,55 @@ def test_indicator(self):
         assert_frame_equal(test5, hand_coded_result)
 
 
+
+    def test_validation(self):
+        left = DataFrame({'a':['a', 'b', 'c', 'd'], 
+                          'b':['cat', 'dog', 'weasel', 'horse']},
+                         index = range(4))
+        right = DataFrame({'a':['a', 'b', 'c', 'd', 'e'], 
+                           'c':['meow', 'bark', 'um... weasel noise?', 
+                                'nay', 'chirp']},
+                         index = range(5))
+        merge(left, right, left_index=True, right_index=True, validate='1:1')
+        merge(left, right, left_index=True, right_index=True, validate='one_to_one')
+        merge(left, right, on='a', validate='1:1')
+        merge(left, right, on='a', validate='one_to_one')
+
+        
+        # Dups on right
+        right_w_dups = right.append(pd.DataFrame({'a':['e'], 'c':['moo']}, index=[4]))
+        merge(left, right_w_dups, left_index=True, right_index=True, validate='one_to_many')
+
+        with pytest.raises(ValueError):
+            merge(left, right_w_dups, left_index=True, right_index=True, validate='one_to_one')
+
+        with pytest.raises(ValueError):
+            merge(left, right_w_dups, on='a', validate='one_to_one')
+
+        # Dups on left
+        left_w_dups = left.append(pd.DataFrame({'a':['a'], 'c':['cow']}, index=[3]))
+        merge(left_w_dups, right, left_index=True, right_index=True, validate='many_to_one')
+
+        with pytest.raises(ValueError):
+            merge(left_w_dups, right, left_index=True, right_index=True, validate='one_to_one')
+
+        with pytest.raises(ValueError):
+            merge(left_w_dups, right, on='a', validate='one_to_one')
+
+        # Dups on both
+        merge(left_w_dups, right_w_dups, on='a', validate='many_to_many')
+
+        with pytest.raises(ValueError):
+            merge(left_w_dups, right_w_dups, left_index=True, right_index=True, validate='many_to_one')
+
+        with pytest.raises(ValueError):
+            merge(left_w_dups, right_w_dups, on='a', validate='one_to_many')
+
+        # Check invalid arguments
+        with pytest.raises(ValueError):
+            merge(left, right, on='a', validate='jibberish')
+
+
 def _check_merge(x, y):
     for how in ['inner', 'left', 'outer']:
         result = x.join(y, how=how)