DEPR: relocate exceptions from pandas.core.common pandas-dev#14800

Move exceptions/warnings from pandas.core.common to pandas.api.exceptions
The exceptions/warnings can still be imported from pandas.core.common however
a DeprecationWarning will be issued when they are raised.

Author: m-charlton

doc/source/whatsnew/v0.20.0.txt

@@ -265,6 +265,23 @@ Deprecations
 - ``DataFrame.astype()`` has deprecated the ``raise_on_error`` parameter in favor of ``errors`` (:issue:`14878`)
 - ``Series.sortlevel`` and ``DataFrame.sortlevel`` have been deprecated in favor of ``Series.sort_index`` and ``DataFrame.sort_index`` (:issue:`15099`)
 
+.. _whatsnew_0200.moved
+
+Moved
+^^^^^
+
+The following exceptions have been relocated from ``pandas.core.common`` to ``pandas.api.exceptions``:
+
+- ``AbstractMethodError``
+- ``AmbiguousIndexError``
+- ``PandasError``
+- ``PerformanceWarning``
+- ``SettingWithCopyError``
+- ``SettingWithCopyWarning``
+- ``UnsupportedFunctionCall``
+- ``UnsortedIndexError``
+
+Raising any of the above exceptions, imported from ``pandas.core.common``, will show a ``DeprecationWarning`` (:issue:`14800`)
 
 .. _whatsnew_0200.prior_deprecations:
 
@@ -369,4 +386,4 @@ Bug Fixes
 - Bug in ``Series`` constructor when both ``copy=True`` and ``dtype`` arguments are provided (:issue:`15125`)
 - Bug in ``pd.read_csv()`` for the C engine where ``usecols`` were being indexed incorrectly with ``parse_dates`` (:issue:`14792`)
 
-- Bug in ``Series.dt.round`` inconsistent behaviour on NAT's with different arguments (:issue:`14940`)
+- Bug in ``Series.dt.round`` inconsistent behaviour on NAT's with different arguments (:issue:`14940`)

pandas/api/exceptions.py

@@ -0,0 +1,46 @@
+
+class PandasError(Exception):
+    pass
+
+
+class PerformanceWarning(Warning):
+    pass
+
+
+class SettingWithCopyError(ValueError):
+    pass
+
+
+class SettingWithCopyWarning(Warning):
+    pass
+
+
+class AmbiguousIndexError(PandasError, KeyError):
+    pass
+
+
+class UnsupportedFunctionCall(ValueError):
+    pass
+
+
+class UnsortedIndexError(KeyError):
+    """ Error raised when attempting to get a slice of a MultiIndex
+    and the index has not been lexsorted. Subclass of `KeyError`.
+
+    .. versionadded:: 0.20.0
+
+    """
+    pass
+
+
+class AbstractMethodError(NotImplementedError):
+    """Raise this error instead of NotImplementedError for abstract methods
+    while keeping compatibility with Python 2 and Python 3.
+    """
+
+    def __init__(self, class_instance):
+        self.class_instance = class_instance
+
+    def __str__(self):
+        return ("This method must be defined in the concrete class of %s" %
+                self.class_instance.__class__.__name__)

pandas/api/tests/test_api.py

@@ -3,6 +3,8 @@
 import numpy as np
 
 import pandas as pd
+import pandas.core.common
+from pandas.api import exceptions
 from pandas.core import common as com
 from pandas import api
 from pandas.api import types
@@ -135,7 +137,7 @@ def test_api(self):
 
 class TestApi(Base, tm.TestCase):
 
-    allowed = ['tests', 'types']
+    allowed = ['exceptions', 'tests', 'types']
 
     def test_api(self):
 
@@ -215,6 +217,50 @@ def test_removed_from_core_common(self):
                   'ensure_float']:
             self.assertRaises(AttributeError, lambda: getattr(com, t))
 
+    def test_exceptions_deprecated_in_commom_core(self):
+        # see issue #14800. Exceptions deprecated & moved from
+        # pandas.common.core to pandas.api.exceptions
+
+        class _ConcreteClass:
+            pass
+
+        moved_exceptions = ('AmbiguousIndexError', 'PandasError',
+                            'PerformanceWarning', 'SettingWithCopyError',
+                            'SettingWithCopyWarning',
+                            'UnsupportedFunctionCall',
+                            'UnsortedIndexError')
+
+        for moved_exception in moved_exceptions:
+            with tm.assert_produces_warning(DeprecationWarning):
+                getattr(pandas.core.common, moved_exception)()
+
+        with tm.assert_produces_warning(DeprecationWarning):
+            pandas.core.common.AbstractMethodError(_ConcreteClass())
+
+        with self.assertRaises(exceptions.AbstractMethodError):
+            raise exceptions.AbstractMethodError(_ConcreteClass())
+
+        with self.assertRaises(exceptions.AmbiguousIndexError):
+            raise exceptions.AmbiguousIndexError()
+
+        with self.assertRaises(exceptions.PandasError):
+            raise exceptions.PandasError()
+
+        with self.assertRaises(exceptions.PerformanceWarning):
+            raise exceptions.PerformanceWarning()
+
+        with self.assertRaises(exceptions.SettingWithCopyError):
+            raise exceptions.SettingWithCopyError()
+
+        with self.assertRaises(exceptions.SettingWithCopyWarning):
+            raise exceptions.SettingWithCopyWarning()
+
+        with self.assertRaises(exceptions.UnsupportedFunctionCall):
+            raise exceptions.UnsupportedFunctionCall()
+
+        with self.assertRaises(exceptions.UnsortedIndexError):
+            raise exceptions.UnsortedIndexError()
+
 
 class TestDatetools(tm.TestCase):
 
@@ -228,6 +274,7 @@ def test_deprecation_access_obj(self):
                                         check_stacklevel=False):
             pd.datetools.monthEnd
 
+
 if __name__ == '__main__':
     import nose
     nose.runmodule(argv=[__file__, '-vvs', '-x', '--pdb', '--pdb-failure'],

pandas/compat/numpy/function.py

@@ -21,7 +21,7 @@
 from numpy import ndarray
 from pandas.util.validators import (validate_args, validate_kwargs,
                                     validate_args_and_kwargs)
-from pandas.core.common import UnsupportedFunctionCall
+from pandas.api.exceptions import UnsupportedFunctionCall
 from pandas.types.common import is_integer, is_bool
 from pandas.compat import OrderedDict
 

pandas/core/base.py

@@ -16,7 +16,7 @@
 from pandas.compat.numpy import function as nv
 from pandas.util.decorators import (Appender, cache_readonly,
                                     deprecate_kwarg, Substitution)
-from pandas.core.common import AbstractMethodError
+from pandas.api.exceptions import AbstractMethodError
 from pandas.formats.printing import pprint_thing
 
 _shared_docs = dict()

pandas/core/common.py

@@ -20,6 +20,8 @@
 from pandas.api import types
 from pandas.types import common
 
+from pandas.util.depr_module import _add_proxies
+
 # back-compat of public API
 # deprecate these functions
 m = sys.modules['pandas.core.common']
@@ -63,6 +65,20 @@ def wrapper(*args, **kwargs):
 
     setattr(m, t, outer(t))
 
+# Relocate exceptions, see #14800
+_moved_exceptions = ('AbstractMethodError',
+                     'AmbiguousIndexError',
+                     'PandasError',
+                     'PerformanceWarning',
+                     'SettingWithCopyError',
+                     'SettingWithCopyWarning',
+                     'UnsupportedFunctionCall',
+                     'UnsortedIndexError')
+
+_add_proxies(old_mod_name='pandas.core.common',
+             new_mod_name='pandas.api.exceptions',
+             entities=_moved_exceptions)
+
 
 # deprecate array_equivalent
 
@@ -73,53 +89,6 @@ def array_equivalent(*args, **kwargs):
     return missing.array_equivalent(*args, **kwargs)
 
 
-class PandasError(Exception):
-    pass
-
-
-class PerformanceWarning(Warning):
-    pass
-
-
-class SettingWithCopyError(ValueError):
-    pass
-
-
-class SettingWithCopyWarning(Warning):
-    pass
-
-
-class AmbiguousIndexError(PandasError, KeyError):
-    pass
-
-
-class UnsupportedFunctionCall(ValueError):
-    pass
-
-
-class UnsortedIndexError(KeyError):
-    """ Error raised when attempting to get a slice of a MultiIndex
-    and the index has not been lexsorted. Subclass of `KeyError`.
-
-    .. versionadded:: 0.20.0
-
-    """
-    pass
-
-
-class AbstractMethodError(NotImplementedError):
-    """Raise this error instead of NotImplementedError for abstract methods
-    while keeping compatibility with Python 2 and Python 3.
-    """
-
-    def __init__(self, class_instance):
-        self.class_instance = class_instance
-
-    def __str__(self):
-        return ("This method must be defined in the concrete class of %s" %
-                self.class_instance.__class__.__name__)
-
-
 def flatten(l):
     """Flatten an arbitrarily nested sequence.
 

pandas/core/frame.py

@@ -56,7 +56,9 @@
                                  is_named_tuple)
 from pandas.types.missing import isnull, notnull
 
-from pandas.core.common import (PandasError, _try_sort,
+from pandas.api.exceptions import PandasError
+
+from pandas.core.common import (_try_sort,
                                 _default_index,
                                 _values_from_object,
                                 _maybe_box_datetimelike,

pandas/core/generic.py

@@ -27,11 +27,11 @@
 from pandas.types.cast import _maybe_promote, _maybe_upcast_putmask
 from pandas.types.missing import isnull, notnull
 from pandas.types.generic import ABCSeries, ABCPanel
-
+from pandas.api.exceptions import SettingWithCopyError, AbstractMethodError
 from pandas.core.common import (_values_from_object,
-                                _maybe_box_datetimelike,
-                                SettingWithCopyError, SettingWithCopyWarning,
-                                AbstractMethodError)
+                                _maybe_box_datetimelike)
+
+from pandas.api.exceptions import SettingWithCopyWarning
 
 from pandas.core.base import PandasObject
 from pandas.core.index import (Index, MultiIndex, _ensure_index,

pandas/core/groupby.py

@@ -32,8 +32,8 @@
                                  _ensure_float)
 from pandas.types.cast import _possibly_downcast_to_dtype
 from pandas.types.missing import isnull, notnull, _maybe_fill
-
-from pandas.core.common import _values_from_object, AbstractMethodError
+from pandas.api.exceptions import AbstractMethodError
+from pandas.core.common import _values_from_object
 from pandas.core.base import (PandasObject, SelectionMixin, GroupByError,
                               DataError, SpecificationError)
 from pandas.core.categorical import Categorical

pandas/core/ops.py

@@ -19,8 +19,8 @@
 from pandas.compat import bind_method
 import pandas.core.missing as missing
 import pandas.algos as _algos
-from pandas.core.common import (_values_from_object, _maybe_match_name,
-                                PerformanceWarning)
+from pandas.api.exceptions import PerformanceWarning
+from pandas.core.common import _values_from_object, _maybe_match_name
 from pandas.types.missing import notnull, isnull
 from pandas.types.common import (needs_i8_conversion,
                                  is_datetimelike_v_numeric,

pandas/core/panel.py

@@ -14,14 +14,16 @@
                                  is_string_like, is_scalar)
 from pandas.types.missing import notnull
 
+from pandas.api.exceptions import PandasError
+
 import pandas.computation.expressions as expressions
 import pandas.core.common as com
 import pandas.core.ops as ops
 import pandas.core.missing as missing
 from pandas import compat
 from pandas.compat import (map, zip, range, u, OrderedDict, OrderedDefaultdict)
 from pandas.compat.numpy import function as nv
-from pandas.core.common import PandasError, _try_sort, _default_index
+from pandas.core.common import _try_sort, _default_index
 from pandas.core.frame import DataFrame
 from pandas.core.generic import NDFrame, _shared_docs
 from pandas.core.index import (Index, MultiIndex, _ensure_index,

pandas/core/series.py

@@ -32,14 +32,13 @@
                                _possibly_convert_platform,
                                _possibly_cast_to_datetime, _possibly_castable)
 from pandas.types.missing import isnull, notnull
-
+from pandas.api.exceptions import SettingWithCopyError
 from pandas.core.common import (is_bool_indexer,
                                 _default_index,
                                 _asarray_tuplesafe,
                                 _values_from_object,
                                 _try_sort,
                                 _maybe_match_name,
-                                SettingWithCopyError,
                                 _maybe_box_datetimelike,
                                 _dict_compat)
 from pandas.core.index import (Index, MultiIndex, InvalidIndexError,

pandas/indexes/multi.py

@@ -22,11 +22,10 @@
                                  is_list_like,
                                  is_scalar)
 from pandas.types.missing import isnull, array_equivalent
+from pandas.api.exceptions import PerformanceWarning, UnsortedIndexError
 from pandas.core.common import (_values_from_object,
                                 is_bool_indexer,
-                                is_null_slice,
-                                PerformanceWarning,
-                                UnsortedIndexError)
+                                is_null_slice)
 
 
 from pandas.core.base import FrozenList

pandas/io/common.py

@@ -9,7 +9,7 @@
 from pandas.compat import StringIO, BytesIO, string_types, text_type
 from pandas import compat
 from pandas.formats.printing import pprint_thing
-from pandas.core.common import AbstractMethodError
+from pandas.api.exceptions import AbstractMethodError
 from pandas.types.common import is_number
 
 try:

pandas/io/gbq.py

@@ -13,7 +13,7 @@
 from pandas import compat
 from pandas.core.api import DataFrame
 from pandas.tools.merge import concat
-from pandas.core.common import PandasError
+from pandas.api.exceptions import PandasError
 from pandas.compat import lzip, bytes_to_str
 
 

pandas/io/html.py

@@ -19,7 +19,7 @@
 from pandas.compat import (lrange, lmap, u, string_types, iteritems,
                            raise_with_traceback, binary_type)
 from pandas import Series
-from pandas.core.common import AbstractMethodError
+from pandas.api.exceptions import AbstractMethodError
 from pandas.formats.printing import pprint_thing
 
 _IMPORTS = False

pandas/io/json.py

@@ -10,8 +10,8 @@
 from pandas.compat import StringIO, long, u
 from pandas import compat, isnull
 from pandas import Series, DataFrame, to_datetime
+from pandas.api.exceptions import AbstractMethodError
 from pandas.io.common import get_filepath_or_buffer, _get_handle
-from pandas.core.common import AbstractMethodError
 from pandas.formats.printing import pprint_thing
 
 loads = _json.loads

pandas/io/packers.py

@@ -59,7 +59,7 @@
 from pandas.sparse.api import SparseSeries, SparseDataFrame
 from pandas.sparse.array import BlockIndex, IntIndex
 from pandas.core.generic import NDFrame
-from pandas.core.common import PerformanceWarning
+from pandas.api.exceptions import PerformanceWarning
 from pandas.io.common import get_filepath_or_buffer
 from pandas.core.internals import BlockManager, make_block, _safe_reshape
 import pandas.core.internals as internals