API: expose pandas.api.exceptions

xref pandas-dev#14800

Author: jreback

doc/source/whatsnew/v0.20.0.txt

@@ -53,6 +53,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,8 @@
+""" public toolkit API """
+
+from pandas.core.common import (PandasError, PerformanceWarning,
+                                AmbiguousIndexError, UnsupportedFunctionCall,
+                                UnsortedIndexError)
+from pandas.tslib import OutOfBoundsDatetime
+from pandas.io.common import (ParserError, DtypeWarning,
+                              EmptyDataError, ParserWarning)

pandas/tests/api/test_api.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 
+import pytest
 import numpy as np
 
 import pandas as pd
@@ -214,6 +215,26 @@ def test_removed_from_core_common(self):
             self.assertRaises(AttributeError, lambda: getattr(com, t))
 
 
+class TestException(object):
+
+    @pytest.mark.parametrize(
+        "exc", ['PandasError', 'AmbiguousIndexError',
+                'UnsupportedFunctionCall', 'UnsortedIndexError', 'OutOfBoundsDatetime',
+                'ParserError', 'PerformanceWarning', 'DtypeWarning',
+                'EmptyDataError', 'ParserWarning'])
+    def test_exception_importable(self, exc):
+        from pandas.api import exceptions
+        assert getattr(exceptions, exc)
+
+    def test_catch_oob(self):
+        from pandas.api import exceptions
+
+        try:
+            pd.Timestamp('15000101')
+        except exceptions.OutOfBoundsDatetime:
+            pass
+
+
 class TestDatetools(tm.TestCase):
 
     def test_deprecation_access_func(self):

setup.py

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