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,51 @@ 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

@@ -724,6 +724,63 @@ def test_indicator(self):
                           how='outer', indicator=True)
         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']: