change merge validate errors to MergeError from ValueError (#16436)

* change merge validate errors to MergeError from ValueError
* move MergeError to pandas/errors

Author: nickeubank

doc/source/whatsnew/v0.21.0.txt

@@ -30,7 +30,7 @@ New features
 Other Enhancements
 ^^^^^^^^^^^^^^^^^^
 
-- 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. For more, see :ref:`here <merging.validation>` (:issue:`16270`)
+- 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 of type ``MergeError`` will be raised. For more, see :ref:`here <merging.validation>` (:issue:`16270`)
 - ``Series.to_dict()`` and ``DataFrame.to_dict()`` now support an ``into`` keyword which allows you to specify the ``collections.Mapping`` subclass that you would like returned.  The default is ``dict``, which is backwards compatible. (:issue:`16122`)
 - ``RangeIndex.append`` now returns a ``RangeIndex`` object when possible (:issue:`16212`)
 - :func:`to_pickle` has gained a protocol parameter (:issue:`16252`). By default, this parameter is set to `HIGHEST_PROTOCOL <https://docs.python.org/3/library/pickle.html#data-stream-format>`__
@@ -51,6 +51,7 @@ Backwards incompatible API changes
 Other API Changes
 ^^^^^^^^^^^^^^^^^
 
+- Moved definition of ``MergeError`` to the ``pandas.errors`` module.
 
 
 .. _whatsnew_0210.deprecations:

pandas/core/reshape/merge.py

@@ -40,6 +40,7 @@
 import pandas.core.algorithms as algos
 import pandas.core.common as com
 from pandas._libs import hashtable as libhashtable, join as libjoin, lib
+from pandas.errors import MergeError
 
 
 @Substitution('\nleft : DataFrame')
@@ -60,10 +61,6 @@ def merge(left, right, how='inner', on=None, left_on=None, right_on=None,
     merge.__doc__ = _merge_doc % '\nleft : DataFrame'
 
 
-class MergeError(ValueError):
-    pass
-
-
 def _groupby_and_merge(by, on, left, right, _merge_pieces,
                        check_duplicates=True):
     """
@@ -986,23 +983,23 @@ def _validate(self, validate):
         # Check data integrity
         if validate in ["one_to_one", "1:1"]:
             if not left_unique and not right_unique:
-                raise ValueError("Merge keys are not unique in either left"
+                raise MergeError("Merge keys are not unique in either left"
                                  " or right dataset; not a one-to-one merge")
             elif not left_unique:
-                raise ValueError("Merge keys are not unique in left dataset;"
+                raise MergeError("Merge keys are not unique in left dataset;"
                                  " not a one-to-one merge")
             elif not right_unique:
-                raise ValueError("Merge keys are not unique in right dataset;"
+                raise MergeError("Merge keys are not unique in right dataset;"
                                  " not a one-to-one merge")
 
         elif validate in ["one_to_many", "1:m"]:
             if not left_unique:
-                raise ValueError("Merge keys are not unique in left dataset;"
+                raise MergeError("Merge keys are not unique in left dataset;"
                                  "not a one-to-many merge")
 
         elif validate in ["many_to_one", "m:1"]:
             if not right_unique:
-                raise ValueError("Merge keys are not unique in right dataset;"
+                raise MergeError("Merge keys are not unique in right dataset;"
                                  " not a many-to-one merge")
 
         elif validate in ['many_to_many', 'm:m']:

pandas/errors/__init__.py

@@ -57,3 +57,9 @@ class ParserWarning(Warning):
     """
 
 
+class MergeError(ValueError):
+    """
+    Error raised when problems arise during merging due to problems
+    with input data. Subclass of `ValueError`.
+
+    """

pandas/tests/reshape/test_merge.py

@@ -789,11 +789,11 @@ def test_validation(self):
         merge(left, right_w_dups, left_index=True, right_index=True,
               validate='one_to_many')
 
-        with pytest.raises(ValueError):
+        with pytest.raises(MergeError):
             merge(left, right_w_dups, left_index=True, right_index=True,
                   validate='one_to_one')
 
-        with pytest.raises(ValueError):
+        with pytest.raises(MergeError):
             merge(left, right_w_dups, on='a', validate='one_to_one')
 
         # Dups on left
@@ -802,21 +802,21 @@ def test_validation(self):
         merge(left_w_dups, right, left_index=True, right_index=True,
               validate='many_to_one')
 
-        with pytest.raises(ValueError):
+        with pytest.raises(MergeError):
             merge(left_w_dups, right, left_index=True, right_index=True,
                   validate='one_to_one')
 
-        with pytest.raises(ValueError):
+        with pytest.raises(MergeError):
             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):
+        with pytest.raises(MergeError):
             merge(left_w_dups, right_w_dups, left_index=True,
                   right_index=True, validate='many_to_one')
 
-        with pytest.raises(ValueError):
+        with pytest.raises(MergeError):
             merge(left_w_dups, right_w_dups, on='a',
                   validate='one_to_many')
 
@@ -842,7 +842,7 @@ def test_validation(self):
                                           'um... weasel noise?']},
                                    index=range(3))
 
-        with pytest.raises(ValueError):
+        with pytest.raises(MergeError):
             merge(left, right, on='a', validate='1:1')
 
         result = merge(left, right, on=['a', 'b'], validate='1:1')

pandas/tests/test_errors.py

@@ -10,7 +10,7 @@
     "exc", ['UnsupportedFunctionCall', 'UnsortedIndexError',
             'OutOfBoundsDatetime',
             'ParserError', 'PerformanceWarning', 'DtypeWarning',
-            'EmptyDataError', 'ParserWarning'])
+            'EmptyDataError', 'ParserWarning', 'MergeError'])
 def test_exception_importable(exc):
     from pandas import errors
     e = getattr(errors, exc)