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

@@ -75,6 +75,24 @@ Commonly called 'unix epoch' or POSIX time.
 
  pd.to_datetime([1, 2, 3], unit='D')
 
+.. _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