API: expose pandas.api.exceptions

xref pandas-dev#14800

Author: jreback

doc/source/whatsnew/v0.20.0.txt

@@ -50,6 +50,29 @@ fixed-width text files, and :func:`read_excel` for parsing Excel files.
    pd.read_fwf(StringIO(data)).dtypes
    pd.read_fwf(StringIO(data), dtype={'a':'float64', 'b':'object'}).dtypes
 
+
+.. _whatsnew_0200.enhancements.dev_api_exceptions:
+
+pandas development API
+^^^^^^^^^^^^^^^^^^^^^^
+
+In 0.19.0, we introduced standard sub-package to present a public API, see :ref:`here <whatsnew_0190.dev_api>`.
+We are adding ``pandas.api.exceptions`` so to expose supported exceptions and warnings. (:issue:`14800`)
+
+The following are now part of this API:
+
+.. ipython:: python
+
+   import pprint
+   from pandas.api import exceptions
+   excs = [ e for e in dir(exceptions) if not e.startswith('_') ]
+   pprint.pprint(excs)
+
+.. note::
+
+   These existing definitions for these are deprecated and will be removed in a future version.
+
+
 .. _whatsnew_0200.enhancements.groupby_access:
 
 Groupby Enhancements

pandas/api/exceptions/__init__.py

@@ -0,0 +1,10 @@
+# flake8: noqa
+
+""" public toolkit API """
+
+from pandas.core.common import (PandasError, PerformanceWarning,
+                                AmbiguousIndexError, UnsupportedFunctionCall,
+                                UnsortedIndexError)
+from pandas._libs.tslib import OutOfBoundsDatetime
+from pandas.io.common import (ParserError, DtypeWarning,
+                              EmptyDataError, ParserWarning)

pandas/lib.py

@@ -2,6 +2,7 @@
 
 import warnings
 warnings.warn("The pandas.lib module is deprecated and will be "
-              "removed in a future version. Please import from "
-              "the pandas._libs.lib instead", FutureWarning, stacklevel=2)
+              "removed in a future version. These are private functions "
+              "and can be accessed from pandas._libs.lib instead",
+              FutureWarning, stacklevel=2)
 from pandas._libs.lib import *

pandas/tests/api/test_api.py

@@ -1,12 +1,9 @@
 # -*- coding: utf-8 -*-
 
 from warnings import catch_warnings
-import numpy as np
 
 import pandas as pd
-from pandas.core import common as com
 from pandas import api
-from pandas.api import types
 from pandas.util import testing as tm
 
 
@@ -129,80 +126,6 @@ def test_api(self):
         self.check(api, self.allowed)
 
 
-class TestTypes(Base, tm.TestCase):
-
-    allowed = ['is_any_int_dtype', 'is_bool', 'is_bool_dtype',
-               'is_categorical', 'is_categorical_dtype', 'is_complex',
-               'is_complex_dtype', 'is_datetime64_any_dtype',
-               'is_datetime64_dtype', 'is_datetime64_ns_dtype',
-               'is_datetime64tz_dtype', 'is_datetimetz', 'is_dtype_equal',
-               'is_extension_type', 'is_float', 'is_float_dtype',
-               'is_floating_dtype', 'is_int64_dtype', 'is_integer',
-               'is_integer_dtype', 'is_number', 'is_numeric_dtype',
-               'is_object_dtype', 'is_scalar', 'is_sparse',
-               'is_string_dtype', 'is_signed_integer_dtype',
-               'is_timedelta64_dtype', 'is_timedelta64_ns_dtype',
-               'is_unsigned_integer_dtype', 'is_period',
-               'is_period_dtype', 'is_re', 'is_re_compilable',
-               'is_dict_like', 'is_iterator',
-               'is_list_like', 'is_hashable',
-               'is_named_tuple', 'is_sequence',
-               'pandas_dtype']
-
-    def test_types(self):
-
-        self.check(types, self.allowed)
-
-    def check_deprecation(self, fold, fnew):
-        with tm.assert_produces_warning(DeprecationWarning):
-            try:
-                result = fold('foo')
-                expected = fnew('foo')
-                self.assertEqual(result, expected)
-            except TypeError:
-                self.assertRaises(TypeError,
-                                  lambda: fnew('foo'))
-            except AttributeError:
-                self.assertRaises(AttributeError,
-                                  lambda: fnew('foo'))
-
-    def test_deprecation_core_common(self):
-
-        # test that we are in fact deprecating
-        # the pandas.core.common introspectors
-        for t in self.allowed:
-            self.check_deprecation(getattr(com, t), getattr(types, t))
-
-    def test_deprecation_core_common_array_equivalent(self):
-
-        with tm.assert_produces_warning(DeprecationWarning):
-            com.array_equivalent(np.array([1, 2]), np.array([1, 2]))
-
-    def test_deprecation_core_common_moved(self):
-
-        # these are in pandas.types.common
-        l = ['is_datetime_arraylike',
-             'is_datetime_or_timedelta_dtype',
-             'is_datetimelike',
-             'is_datetimelike_v_numeric',
-             'is_datetimelike_v_object',
-             'is_datetimetz',
-             'is_int_or_datetime_dtype',
-             'is_period_arraylike',
-             'is_string_like',
-             'is_string_like_dtype']
-
-        from pandas.types import common as c
-        for t in l:
-            self.check_deprecation(getattr(com, t), getattr(c, t))
-
-    def test_removed_from_core_common(self):
-
-        for t in ['is_null_datelike_scalar',
-                  'ensure_float']:
-            self.assertRaises(AttributeError, lambda: getattr(com, t))
-
-
 class TestDatetoolsDeprecation(tm.TestCase):
 
     def test_deprecation_access_func(self):
@@ -267,7 +190,7 @@ class TestLib(tm.TestCase):
     def test_deprecation_access_func(self):
         with tm.assert_produces_warning(FutureWarning,
                                         check_stacklevel=False):
-            pd.lib.infer_dtype
+            pd.lib.infer_dtype(['foo'])
 
 
 class TestTSLib(tm.TestCase):
@@ -276,4 +199,4 @@ def test_deprecation_access_func(self):
         # some libraries may be imported before we
         # test and could show the warning
         with catch_warnings(record=True):
-            pd.tslib.Timestamp
+            pd.tslib.Timestamp('20160101')

pandas/tests/api/test_exceptions.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+
+import pytest
+import pandas  # noqa
+import pandas as pd
+
+
+@pytest.mark.parametrize(
+    "exc", ['PandasError', 'AmbiguousIndexError',
+            'UnsupportedFunctionCall', 'UnsortedIndexError',
+            'OutOfBoundsDatetime',
+            'ParserError', 'PerformanceWarning', 'DtypeWarning',
+            'EmptyDataError', 'ParserWarning'])
+def test_exception_importable(exc):
+    from pandas.api import exceptions
+    e = getattr(exceptions, exc)
+    assert e is not None
+
+    # check that we can raise on them
+    with pytest.raises(e):
+        raise e()
+
+
+def test_catch_oob():
+    from pandas.api import exceptions
+
+    try:
+        pd.Timestamp('15000101')
+    except exceptions.OutOfBoundsDatetime:
+        pass

pandas/tests/api/test_types.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+
+import numpy as np
+
+from pandas.core import common as com
+from pandas.api import types
+from pandas.util import testing as tm
+
+from .test_api import Base
+
+
+class TestTypes(Base, tm.TestCase):
+
+    allowed = ['is_any_int_dtype', 'is_bool', 'is_bool_dtype',
+               'is_categorical', 'is_categorical_dtype', 'is_complex',
+               'is_complex_dtype', 'is_datetime64_any_dtype',
+               'is_datetime64_dtype', 'is_datetime64_ns_dtype',
+               'is_datetime64tz_dtype', 'is_datetimetz', 'is_dtype_equal',
+               'is_extension_type', 'is_float', 'is_float_dtype',
+               'is_floating_dtype', 'is_int64_dtype', 'is_integer',
+               'is_integer_dtype', 'is_number', 'is_numeric_dtype',
+               'is_object_dtype', 'is_scalar', 'is_sparse',
+               'is_string_dtype', 'is_signed_integer_dtype',
+               'is_timedelta64_dtype', 'is_timedelta64_ns_dtype',
+               'is_unsigned_integer_dtype', 'is_period',
+               'is_period_dtype', 'is_re', 'is_re_compilable',
+               'is_dict_like', 'is_iterator',
+               'is_list_like', 'is_hashable',
+               'is_named_tuple', 'is_sequence',
+               'pandas_dtype']
+
+    def test_types(self):
+
+        self.check(types, self.allowed)
+
+    def check_deprecation(self, fold, fnew):
+        with tm.assert_produces_warning(DeprecationWarning):
+            try:
+                result = fold('foo')
+                expected = fnew('foo')
+                self.assertEqual(result, expected)
+            except TypeError:
+                self.assertRaises(TypeError,
+                                  lambda: fnew('foo'))
+            except AttributeError:
+                self.assertRaises(AttributeError,
+                                  lambda: fnew('foo'))
+
+    def test_deprecation_core_common(self):
+
+        # test that we are in fact deprecating
+        # the pandas.core.common introspectors
+        for t in self.allowed:
+            self.check_deprecation(getattr(com, t), getattr(types, t))
+
+    def test_deprecation_core_common_array_equivalent(self):
+
+        with tm.assert_produces_warning(DeprecationWarning):
+            com.array_equivalent(np.array([1, 2]), np.array([1, 2]))
+
+    def test_deprecation_core_common_moved(self):
+
+        # these are in pandas.types.common
+        l = ['is_datetime_arraylike',
+             'is_datetime_or_timedelta_dtype',
+             'is_datetimelike',
+             'is_datetimelike_v_numeric',
+             'is_datetimelike_v_object',
+             'is_datetimetz',
+             'is_int_or_datetime_dtype',
+             'is_period_arraylike',
+             'is_string_like',
+             'is_string_like_dtype']
+
+        from pandas.types import common as c
+        for t in l:
+            self.check_deprecation(getattr(com, t), getattr(c, t))
+
+    def test_removed_from_core_common(self):
+
+        for t in ['is_null_datelike_scalar',
+                  'ensure_float']:
+            self.assertRaises(AttributeError, lambda: getattr(com, t))

pandas/tslib.py

@@ -3,6 +3,6 @@
 import warnings
 warnings.warn("The pandas.tslib module is deprecated and will be "
               "removed in a future version. Please import from "
-              "the pandas._libs.tslib instead", FutureWarning, stacklevel=2)
+              "the pandas or pandas.api.exceptions instead", FutureWarning, stacklevel=2)
 from pandas._libs.tslib import (Timestamp, Timedelta,
                                NaT, OutOfBoundsDatetime)

setup.py

@@ -626,6 +626,7 @@ def pxd(name):
       packages=['pandas',
                 'pandas.api',
                 'pandas.api.types',
+                'pandas.api.exceptions',
                 'pandas.compat',
                 'pandas.compat.numpy',
                 'pandas.computation',