ENH: Move warnings to error/__init__.py per GH27656 (#47901)

* ENH: Move warnings to error/__init__.py per GH27656 * ENH: update whatsnew line * ENH: add and re-add final * ENH: add to __all__ * ENH: apply feedback * ENH: fix doc string * ENH: add additional exception/warnings to rst * ENH: fix rst and typo

Author: dataxerik

doc/source/reference/testing.rst

@@ -27,6 +27,7 @@ Exceptions and warnings
  errors.AbstractMethodError
  errors.AccessorRegistrationWarning
  errors.AttributeConflictWarning
+ errors.CategoricalConversionWarning
  errors.ClosedFileError
  errors.CSSWarning
  errors.DatabaseError
@@ -36,6 +37,7 @@ Exceptions and warnings
  errors.EmptyDataError
  errors.IncompatibilityWarning
  errors.IndexingError
+ errors.InvalidColumnName
  errors.InvalidIndexError
  errors.IntCastingNaNError
  errors.MergeError
@@ -49,6 +51,7 @@ Exceptions and warnings
  errors.ParserWarning
  errors.PerformanceWarning
  errors.PossibleDataLossError
+ errors.PossiblePrecisionLoss
  errors.PyperclipException
  errors.PyperclipWindowsException
  errors.SettingWithCopyError
@@ -57,6 +60,7 @@ Exceptions and warnings
  errors.UndefinedVariableError
  errors.UnsortedIndexError
  errors.UnsupportedFunctionCall
+ errors.ValueLabelTypeMismatch
 
 Bug report function
 -------------------

doc/source/whatsnew/v1.5.0.rst

@@ -275,7 +275,7 @@ Other enhancements
 - A :class:`errors.PerformanceWarning` is now thrown when using ``string[pyarrow]`` dtype with methods that don't dispatch to ``pyarrow.compute`` methods (:issue:`42613`)
 - Added ``numeric_only`` argument to :meth:`Resampler.sum`, :meth:`Resampler.prod`, :meth:`Resampler.min`, :meth:`Resampler.max`, :meth:`Resampler.first`, and :meth:`Resampler.last` (:issue:`46442`)
 - ``times`` argument in :class:`.ExponentialMovingWindow` now accepts ``np.timedelta64`` (:issue:`47003`)
-- :class:`.DataError`, :class:`.SpecificationError`, :class:`.SettingWithCopyError`, :class:`.SettingWithCopyWarning`, :class:`.NumExprClobberingError`, :class:`.UndefinedVariableError`, and :class:`.IndexingError` are now exposed in ``pandas.errors`` (:issue:`27656`)
+- :class:`.DataError`, :class:`.SpecificationError`, :class:`.SettingWithCopyError`, :class:`.SettingWithCopyWarning`, :class:`.NumExprClobberingError`, :class:`.UndefinedVariableError`, :class:`.IndexingError`, :class:`.PyperclipException`, :class:`.PyperclipWindowsException`, :class:`.CSSWarning`, :class:`.PossibleDataLossError`, :class:`.ClosedFileError`, :class:`.IncompatibilityWarning`, :class:`.AttributeConflictWarning`, :class:`.DatabaseError, :class:`.PossiblePrecisionLoss, :class:`.ValueLabelTypeMismatch, :class:`.InvalidColumnName, and :class:`.CategoricalConversionWarning` are now exposed in ``pandas.errors`` (:issue:`27656`)
 - Added ``check_like`` argument to :func:`testing.assert_series_equal` (:issue:`47247`)
 - Allow reading compressed SAS files with :func:`read_sas` (e.g., ``.sas7bdat.gz`` files)
 - :meth:`DatetimeIndex.astype` now supports casting timezone-naive indexes to ``datetime64[s]``, ``datetime64[ms]``, and ``datetime64[us]``, and timezone-aware indexes to the corresponding ``datetime64[unit, tzname]`` dtypes (:issue:`47579`)

pandas/errors/__init__.py

@@ -479,10 +479,67 @@ class DatabaseError(OSError):
  """
 
 
+class PossiblePrecisionLoss(Warning):
+ """
+ Warning raised by to_stata on a column with a value outside or equal to int64.
+
+ When the column value is outside or equal to the int64 value the column is
+ converted to a float64 dtype.
+
+ Examples
+ --------
+ >>> df = pd.DataFrame({"s": pd.Series([1, 2**53], dtype=np.int64)})
+ >>> df.to_stata('test') # doctest: +SKIP
+ ... # PossiblePrecisionLoss: Column converted from int64 to float64...
+ """
+
+
+class ValueLabelTypeMismatch(Warning):
+ """
+ Warning raised by to_stata on a category column that contains non-string values.
+
+ Examples
+ --------
+ >>> df = pd.DataFrame({"categories": pd.Series(["a", 2], dtype="category")})
+ >>> df.to_stata('test') # doctest: +SKIP
+ ... # ValueLabelTypeMismatch: Stata value labels (pandas categories) must be str...
+ """
+
+
+class InvalidColumnName(Warning):
+ """
+ Warning raised by to_stata the column contains a non-valid stata name.
+
+ Because the column name is an invalid Stata variable, the name needs to be
+ converted.
+
+ Examples
+ --------
+ >>> df = pd.DataFrame({"0categories": pd.Series([2, 2])})
+ >>> df.to_stata('test') # doctest: +SKIP
+ ... # InvalidColumnName: Not all pandas column names were valid Stata variable...
+ """
+
+
+class CategoricalConversionWarning(Warning):
+ """
+ Warning is raised when reading a partial labeled Stata file using a iterator.
+
+ Examples
+ --------
+ >>> from pandas.io.stata import StataReader
+ >>> with StataReader('dta_file', chunksize=2) as reader: # doctest: +SKIP
+ ... for i, block in enumerate(reader):
+ ... print(i, block))
+ ... # CategoricalConversionWarning: One or more series with value labels...
+ """
+
+
 __all__ = [
  "AbstractMethodError",
  "AccessorRegistrationWarning",
  "AttributeConflictWarning",
+ "CategoricalConversionWarning",
  "ClosedFileError",
  "CSSWarning",
  "DatabaseError",
@@ -492,6 +549,7 @@ class DatabaseError(OSError):
  "EmptyDataError",
  "IncompatibilityWarning",
  "IntCastingNaNError",
+ "InvalidColumnName",
  "InvalidIndexError",
  "IndexingError",
  "MergeError",
@@ -505,6 +563,7 @@ class DatabaseError(OSError):
  "ParserWarning",
  "PerformanceWarning",
  "PossibleDataLossError",
+ "PossiblePrecisionLoss",
  "PyperclipException",
  "PyperclipWindowsException",
  "SettingWithCopyError",
@@ -513,4 +572,5 @@ class DatabaseError(OSError):
  "UndefinedVariableError",
  "UnsortedIndexError",
  "UnsupportedFunctionCall",
+ "ValueLabelTypeMismatch",
 ]

pandas/io/stata.py

@@ -41,6 +41,12 @@
  StorageOptions,
  WriteBuffer,
 )
+from pandas.errors import (
+ CategoricalConversionWarning,
+ InvalidColumnName,
+ PossiblePrecisionLoss,
+ ValueLabelTypeMismatch,
+)
 from pandas.util._decorators import (
  Appender,
  doc,
@@ -493,31 +499,19 @@ def g(x: datetime.datetime) -> int:
 """
 
 
-class PossiblePrecisionLoss(Warning):
- pass
-
-
 precision_loss_doc: Final = """
 Column converted from {0} to {1}, and some data are outside of the lossless
 conversion range. This may result in a loss of precision in the saved data.
 """
 
 
-class ValueLabelTypeMismatch(Warning):
- pass
-
-
 value_label_mismatch_doc: Final = """
 Stata value labels (pandas categories) must be strings. Column {0} contains
 non-string labels which will be converted to strings. Please check that the
 Stata data file created has not lost information due to duplicate labels.
 """
 
 
-class InvalidColumnName(Warning):
- pass
-
-
 invalid_name_doc: Final = """
 Not all pandas column names were valid Stata variable names.
 The following replacements have been made:
@@ -530,11 +524,7 @@ class InvalidColumnName(Warning):
 """
 
 
-class CategoricalConversionWarning(Warning):
- pass
-
-
-categorical_conversion_warning = """
+categorical_conversion_warning: Final = """
 One or more series with value labels are not fully labeled. Reading this
 dataset with an iterator results in categorical variable with different
 categories. This occurs since it is not possible to know all possible values

pandas/tests/test_errors.py

@@ -35,6 +35,10 @@
  "IncompatibilityWarning",
  "AttributeConflictWarning",
  "DatabaseError",
+ "PossiblePrecisionLoss",
+ "CategoricalConversionWarning",
+ "InvalidColumnName",
+ "ValueLabelTypeMismatch",
  ],
 )
 def test_exception_importable(exc):