Refinements

Author: rhshadrach

doc/source/whatsnew/v3.0.0.rst

@@ -26,9 +26,15 @@ Enhancement2
 
 New Deprecation Policy
 ^^^^^^^^^^^^^^^^^^^^^^
-pandas 3.0.0 introduces a new 3-stage deprecation policy: using ``DeprecationWarning`` initially, then switching to ``FutureWarning`` for broader visibility in the last minor version before the next major release, and then removal of the deprecated functionality in the major release.
+pandas 3.0.0 introduces a new 3-stage deprecation policy: using ``DeprecationWarning`` initially, then switching to ``FutureWarning`` for broader visibility in the last minor version before the next major release, and then removal of the deprecated functionality in the major release. This was done to give downstream packages more time to adjust to pandas deprecations, which should reduce the amount of warnings that a user gets from code that isn't theirs. See `PDEP 17 <https://pandas.pydata.org/pdeps/0017-backwards-compatibility-and-deprecation-policy.html>`_ for more details.
 
-This was done to give downstream packages more time to adjust to pandas deprecations, which should reduce the amount of warnings that a user gets from code that isn't theirs.
+All warnings for upcoming changes in pandas will have the base class :class:`pandas.errors.PandasChangeWarning`. Users may also use the following subclasses to control warnings.
+
+- :class:`pandas.errors.Pandas4Warning`: Warnings which will be enforced in pandas 4.0.
+- :class:`pandas.errors.Pandas4Warning`: Warnings which will be enforced in pandas 5.0.
+- :class:`pandas.errors.PandasPendingDeprecationWarning`: Warnings which will emit a ``PendingDeprecationWarning``, independent of the version they will be enforced.
+- :class:`pandas.errors.PandasDeprecationWarning`: Warnings which will emit a ``DeprecationWarning``, independent of the version they will be enforced.
+- :class:`pandas.errors.PandasFutureWarning`: Warnings which will emit a ``PandasFutureWarning``, independent of the version they will be enforced.
 
 .. _whatsnew_300.enhancements.other:
 

pandas/errors/__init__.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import abc
 import ctypes
 
 from pandas._config.config import OptionError
@@ -93,18 +94,24 @@ class PerformanceWarning(Warning):
 
 class PandasChangeWarning(Warning):
     """
-    Warning raised for any an upcoming change.
+    Warning raised for any upcoming change.
 
     See Also
     --------
     errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.
+    errors.PandasFutureWarning : Class for deprecations that will raise a FutureWarning.
 
     Examples
     --------
     >>> pd.errors.PandasChangeWarning
     <class 'pandas.errors.PandasChangeWarning'>
     """
 
+    @classmethod
+    @abc.abstractmethod
+    def version(cls) -> str:
+        """Version where change will be enforced."""
+
 
 class PandasPendingDeprecationWarning(PandasChangeWarning, PendingDeprecationWarning):
     """
@@ -113,6 +120,7 @@ class PandasPendingDeprecationWarning(PandasChangeWarning, PendingDeprecationWar
     See Also
     --------
     errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.
+    errors.PandasFutureWarning : Class for deprecations that will raise a FutureWarning.
 
     Examples
     --------
@@ -128,6 +136,7 @@ class PandasDeprecationWarning(PandasChangeWarning, DeprecationWarning):
     See Also
     --------
     errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.
+    errors.PandasFutureWarning : Class for deprecations that will raise a FutureWarning.
 
     Examples
     --------
@@ -157,14 +166,19 @@ class Pandas4Warning(PandasDeprecationWarning):
 
     See Also
     --------
-    errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.
+    errors.PandasFutureWarning : Class for deprecations that will raise a FutureWarning.
 
     Examples
     --------
     >>> pd.errors.Pandas4Warning
     <class 'pandas.errors.Pandas4Warning'>
     """
 
+    @classmethod
+    def version(cls) -> str:
+        """Version where change will be enforced."""
+        return "4.0"
+
 
 class Pandas5Warning(PandasPendingDeprecationWarning):
     """
@@ -173,13 +187,22 @@ class Pandas5Warning(PandasPendingDeprecationWarning):
     See Also
     --------
     errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.
+    errors.PandasFutureWarning : Class for deprecations that will raise a FutureWarning.
 
     Examples
     --------
     >>> pd.errors.Pandas5Warning
     <class 'pandas.errors.Pandas5Warning'>
     """
 
+    @classmethod
+    def version(cls) -> str:
+        """Version where change will be enforced."""
+        return "5.0"
+
+
+_CurrentDeprecationWarning = Pandas4Warning
+
 
 class UnsupportedFunctionCall(ValueError):
     """

pandas/tests/api/test_api.py

@@ -367,7 +367,8 @@ def test_api_executors(self):
 
 class TestErrors(Base):
     def test_errors(self):
-        self.check(pd.errors, pd.errors.__all__, ignored=["ctypes", "cow"])
+        ignored = ["abstractmethod", "ctypes", "cow"]
+        self.check(pd.errors, pd.errors.__all__, ignored=ignored)
 
 
 class TestUtil(Base):

pandas/tests/groupby/test_groupby_subclass.py

@@ -3,6 +3,8 @@
 import numpy as np
 import pytest
 
+from pandas.errors import Pandas4Warning
+
 from pandas import (
     DataFrame,
     Index,
@@ -36,7 +38,7 @@ def test_groupby_preserves_subclass(obj, groupby_func):
 
     args = get_groupby_method_args(groupby_func, obj)
 
-    warn = FutureWarning if groupby_func == "corrwith" else None
+    warn = Pandas4Warning if groupby_func == "corrwith" else None
     msg = f"{type(grouped).__name__}.corrwith is deprecated"
     with tm.assert_produces_warning(warn, match=msg):
         result1 = getattr(grouped, groupby_func)(*args)

pandas/tests/util/test_deprecate_nonkeyword_arguments.py

@@ -4,12 +4,12 @@
 
 import inspect
 
-from pandas.errors import Pandas4Warning
+from pandas.errors import _CurrentDeprecationWarning
 from pandas.util._decorators import deprecate_nonkeyword_arguments
 
 import pandas._testing as tm
 
-WARNING_CATEGORY = Pandas4Warning
+WARNING_CATEGORY = _CurrentDeprecationWarning
 
 
 @deprecate_nonkeyword_arguments(

pandas/util/_decorators.py

@@ -23,6 +23,8 @@
         Mapping,
     )
 
+    from pandas.errors import PandasChangeWarning
+
 
 def deprecate(
     klass: type[Warning],
@@ -267,7 +269,7 @@ def future_version_msg(version: str | None) -> str:
 
 
 def deprecate_nonkeyword_arguments(
-    klass: type[Warning],
+    klass: type[PandasChangeWarning],
     allowed_args: list[str] | None = None,
     name: str | None = None,
 ) -> Callable[[F], F]:
@@ -289,17 +291,6 @@ def deprecate_nonkeyword_arguments(
         message. If None, then the Qualified name of the function
         is used.
     """
-    from pandas.errors import (
-        Pandas4Warning,
-        Pandas5Warning,
-    )
-
-    if klass is Pandas4Warning:
-        version = "4.0"
-    elif klass is Pandas5Warning:
-        version = "5.0"
-    else:
-        raise AssertionError(f"{type(klass)=} must be a versioned warning")
 
     def decorate(func):
         old_sig = inspect.signature(func)
@@ -328,7 +319,7 @@ def decorate(func):
 
         num_allow_args = len(allow_args)
         msg = (
-            f"{future_version_msg(version)} all arguments of "
+            f"{future_version_msg(klass.version())} all arguments of "
             f"{name or func.__qualname__}{{arguments}} will be keyword-only."
         )