ENH: Implement PDEP-17

doc/source/reference/testing.rst

@@ -52,6 +52,12 @@ Exceptions and warnings
    errors.OptionError
    errors.OutOfBoundsDatetime
    errors.OutOfBoundsTimedelta
+   errors.PandasChangeWarning
+   errors.Pandas4Warning
+   errors.Pandas5Warning
+   errors.PandasPendingDeprecationWarning
+   errors.PandasDeprecationWarning
+   errors.PandasFutureWarning
    errors.ParserError
    errors.ParserWarning
    errors.PerformanceWarning

doc/source/whatsnew/v0.23.0.rst

@@ -105,6 +105,16 @@ Please note that the string ``index`` is not supported with the round trip forma
 .. ipython:: python
    :okwarning:
 
+   df = pd.DataFrame(
+       {
+           'foo': [1, 2, 3, 4],
+           'bar': ['a', 'b', 'c', 'd'],
+           'baz': pd.date_range('2018-01-01', freq='d', periods=4),
+           'qux': pd.Categorical(['a', 'b', 'c', 'c'])
+       },
+       index=pd.Index(range(4), name='idx')
+   )
+
    df.index.name = 'index'
 
    df.to_json('test.json', orient='table')

doc/source/whatsnew/v3.0.0.rst

@@ -24,6 +24,18 @@ Enhancement1
 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. 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.
+
+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.Pandas5Warning`: Warnings which will be enforced in pandas 5.0.
+- :class:`pandas.errors.PandasPendingDeprecationWarning`: Base class of all warnings which emit a ``PendingDeprecationWarning``, independent of the version they will be enforced.
+- :class:`pandas.errors.PandasDeprecationWarning`: Base class of all warnings which emit a ``DeprecationWarning``, independent of the version they will be enforced.
+- :class:`pandas.errors.PandasFutureWarning`: Base class of all warnings which emit a ``PandasFutureWarning``, independent of the version they will be enforced.
+
 .. _whatsnew_300.enhancements.other:
 
 Other enhancements

pandas/_libs/tslibs/timestamps.pyx

@@ -1994,12 +1994,14 @@ class Timestamp(_Timestamp):
         >>> pd.Timestamp.utcnow()   # doctest: +SKIP
         Timestamp('2020-11-16 22:50:18.092888+0000', tz='UTC')
         """
+        from pandas.errors import Pandas4Warning
+
         warnings.warn(
             # The stdlib datetime.utcnow is deprecated, so we deprecate to match.
             #  GH#56680
             "Timestamp.utcnow is deprecated and will be removed in a future "
             "version. Use Timestamp.now('UTC') instead.",
-            FutureWarning,
+            Pandas4Warning,
             stacklevel=find_stack_level(),
         )
         return cls.now(UTC)
@@ -2036,13 +2038,15 @@ class Timestamp(_Timestamp):
         >>> pd.Timestamp.utcfromtimestamp(1584199972)
         Timestamp('2020-03-14 15:32:52+0000', tz='UTC')
         """
+        from pandas.errors import Pandas4Warning
+
         # GH#22451
         warnings.warn(
             # The stdlib datetime.utcfromtimestamp is deprecated, so we deprecate
             #  to match. GH#56680
             "Timestamp.utcfromtimestamp is deprecated and will be removed in a "
             "future version. Use Timestamp.fromtimestamp(ts, 'UTC') instead.",
-            FutureWarning,
+            Pandas4Warning,
             stacklevel=find_stack_level(),
         )
         return cls.fromtimestamp(ts, tz="UTC")

pandas/core/frame.py

@@ -55,6 +55,7 @@
 from pandas.errors import (
     ChainedAssignmentError,
     InvalidIndexError,
+    Pandas4Warning,
 )
 from pandas.errors.cow import (
     _chained_assignment_method_msg,
@@ -11970,7 +11971,7 @@ def all(
         **kwargs,
     ) -> Series | bool: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="all")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="all")
     @doc(make_doc("all", ndim=1))
     def all(
         self,
@@ -12017,7 +12018,7 @@ def min(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="min")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="min")
     @doc(make_doc("min", ndim=2))
     def min(
         self,
@@ -12064,7 +12065,7 @@ def max(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="max")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="max")
     @doc(make_doc("max", ndim=2))
     def max(
         self,
@@ -12080,7 +12081,7 @@ def max(
             result = result.__finalize__(self, method="max")
         return result
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="sum")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="sum")
     def sum(
         self,
         axis: Axis | None = 0,
@@ -12181,7 +12182,7 @@ def sum(
             result = result.__finalize__(self, method="sum")
         return result
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="prod")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="prod")
     def prod(
         self,
         axis: Axis | None = 0,
@@ -12299,7 +12300,7 @@ def mean(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="mean")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="mean")
     @doc(make_doc("mean", ndim=2))
     def mean(
         self,
@@ -12346,7 +12347,9 @@ def median(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="median")
+    @deprecate_nonkeyword_arguments(
+        Pandas4Warning, allowed_args=["self"], name="median"
+    )
     @doc(make_doc("median", ndim=2))
     def median(
         self,
@@ -12396,7 +12399,7 @@ def sem(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="sem")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="sem")
     def sem(
         self,
         axis: Axis | None = 0,
@@ -12516,7 +12519,7 @@ def var(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="var")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="var")
     def var(
         self,
         axis: Axis | None = 0,
@@ -12635,7 +12638,7 @@ def std(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="std")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="std")
     def std(
         self,
         axis: Axis | None = 0,
@@ -12758,7 +12761,7 @@ def skew(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="skew")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="skew")
     def skew(
         self,
         axis: Axis | None = 0,
@@ -12878,7 +12881,7 @@ def kurt(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="kurt")
+    @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="kurt")
     def kurt(
         self,
         axis: Axis | None = 0,

pandas/core/generic.py

@@ -90,6 +90,7 @@
     AbstractMethodError,
     ChainedAssignmentError,
     InvalidIndexError,
+    Pandas4Warning,
 )
 from pandas.errors.cow import _chained_assignment_method_msg
 from pandas.util._decorators import (
@@ -2589,15 +2590,15 @@ def to_json(
                 warnings.warn(
                     "The default 'epoch' date format is deprecated and will be removed "
                     "in a future version, please use 'iso' date format instead.",
-                    FutureWarning,
+                    Pandas4Warning,
                     stacklevel=find_stack_level(),
                 )
         elif date_format == "epoch":
             # GH#57063
             warnings.warn(
                 "'epoch' date format is deprecated and will be removed in a future "
                 "version, please use 'iso' date format instead.",
-                FutureWarning,
+                Pandas4Warning,
                 stacklevel=find_stack_level(),
             )
 
@@ -4376,12 +4377,12 @@ def _check_copy_deprecation(copy):
                 "version. Copy-on-Write is active in pandas since 3.0 which utilizes "
                 "a lazy copy mechanism that defers copies until necessary. Use "
                 ".copy() to make an eager copy if necessary.",
-                DeprecationWarning,
+                Pandas4Warning,
                 stacklevel=find_stack_level(),
             )
 
     # issue 58667
-    @deprecate_kwarg("method", None)
+    @deprecate_kwarg(Pandas4Warning, "method", new_arg_name=None)
     @final
     def reindex_like(
         self,

pandas/core/groupby/generic.py

@@ -27,7 +27,10 @@
 
 from pandas._libs import Interval
 from pandas._libs.hashtable import duplicated
-from pandas.errors import SpecificationError
+from pandas.errors import (
+    Pandas4Warning,
+    SpecificationError,
+)
 from pandas.util._decorators import (
     Appender,
     Substitution,
@@ -3332,7 +3335,7 @@ def corrwith(
         """
         warnings.warn(
             "DataFrameGroupBy.corrwith is deprecated",
-            FutureWarning,
+            Pandas4Warning,
             stacklevel=find_stack_level(),
         )
         result = self._op_via_apply(

pandas/core/indexes/accessors.py

@@ -14,6 +14,7 @@
 import numpy as np
 
 from pandas._libs import lib
+from pandas.errors import Pandas4Warning
 from pandas.util._exceptions import find_stack_level
 
 from pandas.core.dtypes.common import (
@@ -218,7 +219,7 @@ def to_pytimedelta(self):
             "in a future version this will return a Series containing python "
             "datetime.timedelta objects instead of an ndarray. To retain the "
             "old behavior, call `np.array` on the result",
-            FutureWarning,
+            Pandas4Warning,
             stacklevel=find_stack_level(),
         )
         return cast(ArrowExtensionArray, self._parent.array)._dt_to_pytimedelta()
@@ -501,7 +502,7 @@ def to_pytimedelta(self) -> np.ndarray:
             "in a future version this will return a Series containing python "
             "datetime.timedelta objects instead of an ndarray. To retain the "
             "old behavior, call `np.array` on the result",
-            FutureWarning,
+            Pandas4Warning,
             stacklevel=find_stack_level(),
         )
         return self._get_values().to_pytimedelta()

pandas/core/internals/api.py

@@ -15,6 +15,7 @@
 import numpy as np
 
 from pandas._libs.internals import BlockPlacement
+from pandas.errors import Pandas4Warning
 
 from pandas.core.dtypes.common import pandas_dtype
 from pandas.core.dtypes.dtypes import (
@@ -102,7 +103,7 @@ def make_block(
         "make_block is deprecated and will be removed in a future version. "
         "Use pd.api.internals.create_dataframe_from_blocks or "
         "(recommended) higher-level public APIs instead.",
-        DeprecationWarning,
+        Pandas4Warning,
         stacklevel=2,
     )
 

pandas/core/reshape/concat.py

@@ -17,6 +17,7 @@
 import numpy as np
 
 from pandas._libs import lib
+from pandas.errors import Pandas4Warning
 from pandas.util._decorators import set_module
 from pandas.util._exceptions import find_stack_level
 
@@ -392,7 +393,7 @@ def concat(
             "version. Copy-on-Write is active in pandas since 3.0 which utilizes "
             "a lazy copy mechanism that defers copies until necessary. Use "
             ".copy() to make an eager copy if necessary.",
-            DeprecationWarning,
+            Pandas4Warning,
             stacklevel=find_stack_level(),
         )
     if join == "outer":