ENH: Implement PDEP-17

Author: Aloqeely

doc/source/reference/testing.rst

@@ -51,6 +51,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/v3.0.0.rst

@@ -24,6 +24,12 @@ 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.
+
 .. _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,
@@ -11909,7 +11910,9 @@ def all(
         **kwargs,
     ) -> Series | bool: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="all")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="all"
+    )
     @doc(make_doc("all", ndim=1))
     def all(
         self,
@@ -11956,7 +11959,9 @@ def min(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="min")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="min"
+    )
     @doc(make_doc("min", ndim=2))
     def min(
         self,
@@ -12003,7 +12008,9 @@ def max(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="max")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="max"
+    )
     @doc(make_doc("max", ndim=2))
     def max(
         self,
@@ -12019,7 +12026,9 @@ def max(
             result = result.__finalize__(self, method="max")
         return result
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="sum")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="sum"
+    )
     def sum(
         self,
         axis: Axis | None = 0,
@@ -12120,7 +12129,9 @@ def sum(
             result = result.__finalize__(self, method="sum")
         return result
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="prod")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="prod"
+    )
     def prod(
         self,
         axis: Axis | None = 0,
@@ -12238,7 +12249,9 @@ def mean(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="mean")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="mean"
+    )
     @doc(make_doc("mean", ndim=2))
     def mean(
         self,
@@ -12285,7 +12298,9 @@ def median(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="median")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="median"
+    )
     @doc(make_doc("median", ndim=2))
     def median(
         self,
@@ -12335,7 +12350,9 @@ def sem(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="sem")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="sem"
+    )
     def sem(
         self,
         axis: Axis | None = 0,
@@ -12455,7 +12472,9 @@ def var(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="var")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="var"
+    )
     def var(
         self,
         axis: Axis | None = 0,
@@ -12574,7 +12593,9 @@ def std(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="std")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="std"
+    )
     def std(
         self,
         axis: Axis | None = 0,
@@ -12697,7 +12718,9 @@ def skew(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="skew")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=Pandas4Warning, allowed_args=["self"], name="skew"
+    )
     def skew(
         self,
         axis: Axis | None = 0,
@@ -12817,7 +12840,9 @@ def kurt(
         **kwargs,
     ) -> Series | Any: ...
 
-    @deprecate_nonkeyword_arguments(version="4.0", allowed_args=["self"], name="kurt")
+    @deprecate_nonkeyword_arguments(
+        version="4.0", klass=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 (
@@ -2594,15 +2595,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(),
             )
 
@@ -4381,12 +4382,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("method", klass=Pandas4Warning, 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,
@@ -3330,7 +3333,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 (
@@ -93,7 +94,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":