API: expose pandas.errors

move all exception / warning impls (and references)
from pandas.core.common and pandas.io.common

closes pandas-dev#14800

Author: jreback

doc/source/whatsnew/v0.20.0.txt

@@ -55,6 +55,25 @@ 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.errors:
+
+pandas errors
+^^^^^^^^^^^^^
+
+We are adding a standard public location for all pandas exceptions & warnings ``pandas.errors``. (:issue:`14800`). Previously
+these exceptions & warnings could be imported from ``pandas.core.common`` or ``pandas.io.common``. These exceptions and warnings
+will be removed from the ``*.common`` locations in a future release. (:issue:`15541`)
+
+The following are now part of this API:
+
+.. ipython:: python
+
+   import pprint
+   from pandas import errors
+   excs = [ e for e in dir(errors) if not e.startswith('_') ]
+   pprint.pprint(excs)
+
 .. _whatsnew_0200.enhancements.groupby_access:
 
 Groupby Enhancements

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.errors import UnsupportedFunctionCall
 from pandas.types.common import is_integer, is_bool
 from pandas.compat import OrderedDict
 

pandas/computation/align.py

@@ -9,7 +9,8 @@
 
 import pandas as pd
 from pandas import compat
-import pandas.core.common as com
+from pandas.errors import PerformanceWarning
+from pandas.core.common import flatten
 from pandas.computation.common import _result_type_many
 
 
@@ -101,7 +102,7 @@ def _align_core(terms):
                                   'than an order of magnitude on term {1!r}, '
                                   'by more than {2:.4g}; performance may '
                                   'suffer'.format(axis, terms[i].name, ordm),
-                                  category=pd.core.common.PerformanceWarning,
+                                  category=PerformanceWarning,
                                   stacklevel=6)
 
                 if transpose:
@@ -121,7 +122,7 @@ def _align(terms):
     """Align a set of terms"""
     try:
         # flatten the parse tree (a nested list, really)
-        terms = list(com.flatten(terms))
+        terms = list(flatten(terms))
     except TypeError:
         # can't iterate so it must just be a constant or single variable
         if isinstance(terms.value, pd.core.generic.NDFrame):

pandas/core/common.py

@@ -20,6 +20,11 @@
 from pandas.api import types
 from pandas.types import common
 
+# compat
+from pandas.errors import (  # noqa
+    PandasError, PerformanceWarning,
+    AmbiguousIndexError, UnsupportedFunctionCall, UnsortedIndexError)
+
 # back-compat of public API
 # deprecate these functions
 m = sys.modules['pandas.core.common']
@@ -73,14 +78,6 @@ def array_equivalent(*args, **kwargs):
     return missing.array_equivalent(*args, **kwargs)
 
 
-class PandasError(Exception):
-    pass
-
-
-class PerformanceWarning(Warning):
-    pass
-
-
 class SettingWithCopyError(ValueError):
     pass
 
@@ -89,24 +86,6 @@ 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.

pandas/core/frame.py

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

pandas/core/ops.py

@@ -21,8 +21,8 @@
 from pandas.compat import bind_method
 import pandas.core.missing as missing
 
-from pandas.core.common import (_values_from_object, _maybe_match_name,
-                                PerformanceWarning)
+from pandas.errors 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

@@ -21,7 +21,8 @@
 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.errors import PandasError
+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/errors/__init__.py

@@ -0,0 +1,63 @@
+# flake8: noqa
+
+""" expose public exceptions & warnings """
+
+from pandas._libs.tslib import OutOfBoundsDatetime
+
+
+class PandasError(Exception):
+    pass
+
+
+class PerformanceWarning(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 ParserError(ValueError):
+    """
+    Exception that is thrown by an error is encountered in `pd.read_csv`
+    """
+    pass
+
+
+class DtypeWarning(Warning):
+    """
+    Warning that is raised whenever `pd.read_csv` encounters non-
+    uniform dtypes in a column(s) of a given CSV file
+    """
+    pass
+
+
+class EmptyDataError(ValueError):
+    """
+    Exception that is thrown in `pd.read_csv` (by both the C and
+    Python engines) when empty data or header is encountered
+    """
+    pass
+
+
+class ParserWarning(Warning):
+    """
+    Warning that is raised in `pd.read_csv` whenever it is necessary
+    to change parsers (generally from 'c' to 'python') contrary to the
+    one specified by the user due to lack of support or functionality for
+    parsing particular attributes of a CSV file with the requsted engine
+    """
+    pass

pandas/indexes/multi.py

@@ -19,12 +19,10 @@
                                  is_list_like,
                                  is_scalar)
 from pandas.types.missing import isnull, array_equivalent
+from pandas.errors import PerformanceWarning, UnsortedIndexError
 from pandas.core.common import (_values_from_object,
                                 is_bool_indexer,
-                                is_null_slice,
-                                PerformanceWarning,
-                                UnsortedIndexError)
-
+                                is_null_slice)
 
 import pandas.core.base as base
 from pandas.util.decorators import (Appender, cache_readonly,

pandas/io/common.py

@@ -12,6 +12,14 @@
 from pandas.core.common import AbstractMethodError
 from pandas.types.common import is_number
 
+# compat
+from pandas.errors import (ParserError, DtypeWarning,  # noqa
+                           EmptyDataError, ParserWarning)
+
+# gh-12665: Alias for now and remove later.
+CParserError = ParserError
+
+
 try:
     from s3fs import S3File
     need_text_wrapping = (BytesIO, S3File)
@@ -69,43 +77,6 @@ def urlopen(*args, **kwargs):
 _VALID_URLS.discard('')
 
 
-class ParserError(ValueError):
-    """
-    Exception that is thrown by an error is encountered in `pd.read_csv`
-    """
-    pass
-
-
-# gh-12665: Alias for now and remove later.
-CParserError = ParserError
-
-
-class DtypeWarning(Warning):
-    """
-    Warning that is raised whenever `pd.read_csv` encounters non-
-    uniform dtypes in a column(s) of a given CSV file
-    """
-    pass
-
-
-class EmptyDataError(ValueError):
-    """
-    Exception that is thrown in `pd.read_csv` (by both the C and
-    Python engines) when empty data or header is encountered
-    """
-    pass
-
-
-class ParserWarning(Warning):
-    """
-    Warning that is raised in `pd.read_csv` whenever it is necessary
-    to change parsers (generally from 'c' to 'python') contrary to the
-    one specified by the user due to lack of support or functionality for
-    parsing particular attributes of a CSV file with the requsted engine
-    """
-    pass
-
-
 class BaseIterator(object):
     """Subclass this and provide a "__next__()" method to obtain an iterator.
     Useful only when the object being iterated is non-reusable (e.g. OK for a

pandas/io/excel.py

@@ -15,9 +15,9 @@
 
 from pandas.core.frame import DataFrame
 from pandas.io.parsers import TextParser
+from pandas.errors import EmptyDataError
 from pandas.io.common import (_is_url, _urlopen, _validate_header_arg,
-                              EmptyDataError, get_filepath_or_buffer,
-                              _NA_VALUES)
+                              get_filepath_or_buffer, _NA_VALUES)
 from pandas.tseries.period import Period
 from pandas.io.json import libjson
 from pandas.compat import (map, zip, reduce, range, lrange, u, add_metaclass,

pandas/io/html.py

@@ -13,7 +13,8 @@
 import numpy as np
 
 from pandas.types.common import is_list_like
-from pandas.io.common import (EmptyDataError, _is_url, urlopen,
+from pandas.errors import EmptyDataError
+from pandas.io.common import (_is_url, urlopen,
                               parse_url, _validate_header_arg)
 from pandas.io.parsers import TextParser
 from pandas.compat import (lrange, lmap, u, string_types, iteritems,

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.errors 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

pandas/io/parsers.py

@@ -29,10 +29,11 @@
 from pandas.core import algorithms
 from pandas.core.common import AbstractMethodError
 from pandas.io.date_converters import generic_parser
+from pandas.errors import ParserWarning, ParserError, EmptyDataError
 from pandas.io.common import (get_filepath_or_buffer, _validate_header_arg,
                               _get_handle, UnicodeReader, UTF8Recoder,
-                              BaseIterator, ParserError, EmptyDataError,
-                              ParserWarning, _NA_VALUES, _infer_compression)
+                              BaseIterator,
+                              _NA_VALUES, _infer_compression)
 from pandas.tseries import tools
 
 from pandas.util.decorators import Appender

pandas/io/parsers.pyx

@@ -13,12 +13,12 @@ from cpython cimport (PyObject, PyBytes_FromString,
                       PyUnicode_Check, PyUnicode_AsUTF8String,
                       PyErr_Occurred, PyErr_Fetch)
 from cpython.ref cimport PyObject, Py_XDECREF
-from pandas.io.common import (ParserError, DtypeWarning,
-                              EmptyDataError, ParserWarning)
+from pandas.errors import (ParserError, DtypeWarning,
+                           EmptyDataError, ParserWarning)
 
 # Import CParserError as alias of ParserError for backwards compatibility.
 # Ultimately, we want to remove this import. See gh-12665 and gh-14479.
-from pandas.io.common import CParserError
+CParserError = ParserError
 
 cdef extern from "Python.h":
     object PyUnicode_FromString(char *v)

pandas/io/pytables.py

@@ -32,7 +32,8 @@
 from pandas.sparse.array import BlockIndex, IntIndex
 from pandas.core.base import StringMixin
 from pandas.formats.printing import adjoin, pprint_thing
-from pandas.core.common import _asarray_tuplesafe, PerformanceWarning
+from pandas.errors import PerformanceWarning
+from pandas.core.common import _asarray_tuplesafe
 from pandas.core.algorithms import match, unique
 from pandas.core.categorical import Categorical, _factorize_from_iterables
 from pandas.core.internals import (BlockManager, make_block,

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 *