ENH: New proposed deprecation policy

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

@@ -50,7 +50,10 @@ import datetime as dt
 from pandas._libs.tslibs cimport ccalendar
 from pandas._libs.tslibs.base cimport ABCTimestamp
 
-from pandas.util._exceptions import find_stack_level
+from pandas.util._exceptions import (
+    Pandas4DeprecationWarning,
+    find_stack_level,
+)
 
 from pandas._libs.tslibs.conversion cimport (
     _TSObject,
@@ -1533,7 +1536,7 @@ class Timestamp(_Timestamp):
             #  GH#56680
             "Timestamp.utcnow is deprecated and will be removed in a future "
             "version. Use Timestamp.now('UTC') instead.",
-            FutureWarning,
+            Pandas4DeprecationWarning,
             stacklevel=find_stack_level(),
         )
         return cls.now(UTC)
@@ -1561,7 +1564,7 @@ class Timestamp(_Timestamp):
             #  to match. GH#56680
             "Timestamp.utcfromtimestamp is deprecated and will be removed in a "
             "future version. Use Timestamp.fromtimestamp(ts, 'UTC') instead.",
-            FutureWarning,
+            Pandas4DeprecationWarning,
             stacklevel=find_stack_level(),
         )
         return cls.fromtimestamp(ts, tz="UTC")

pandas/core/generic.py

@@ -97,7 +97,10 @@
     deprecate_kwarg,
     doc,
 )
-from pandas.util._exceptions import find_stack_level
+from pandas.util._exceptions import (
+    Pandas4DeprecationWarning,
+    find_stack_level,
+)
 from pandas.util._validators import (
     check_dtype_backend,
     validate_ascending,
@@ -2570,15 +2573,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,
+                    Pandas4DeprecationWarning,
                     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,
+                Pandas4DeprecationWarning,
                 stacklevel=find_stack_level(),
             )
 
@@ -4306,7 +4309,7 @@ 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,
+                Pandas4DeprecationWarning,
                 stacklevel=find_stack_level(),
             )
 

pandas/core/groupby/generic.py

@@ -33,7 +33,10 @@
     Substitution,
     doc,
 )
-from pandas.util._exceptions import find_stack_level
+from pandas.util._exceptions import (
+    Pandas4DeprecationWarning,
+    find_stack_level,
+)
 
 from pandas.core.dtypes.common import (
     ensure_int64,
@@ -2791,7 +2794,7 @@ def corrwith(
         """
         warnings.warn(
             "DataFrameGroupBy.corrwith is deprecated",
-            FutureWarning,
+            Pandas4DeprecationWarning,
             stacklevel=find_stack_level(),
         )
         result = self._op_via_apply(

pandas/core/indexes/accessors.py

@@ -14,7 +14,10 @@
 import numpy as np
 
 from pandas._libs import lib
-from pandas.util._exceptions import find_stack_level
+from pandas.util._exceptions import (
+    Pandas4DeprecationWarning,
+    find_stack_level,
+)
 
 from pandas.core.dtypes.common import (
     is_integer_dtype,
@@ -218,7 +221,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,
+            Pandas4DeprecationWarning,
             stacklevel=find_stack_level(),
         )
         return cast(ArrowExtensionArray, self._parent.array)._dt_to_pytimedelta()
@@ -479,7 +482,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,
+            Pandas4DeprecationWarning,
             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.util._exceptions import Pandas4DeprecationWarning
 
 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,
+        Pandas4DeprecationWarning,
         stacklevel=2,
     )
 

pandas/core/reshape/concat.py

@@ -18,7 +18,10 @@
 
 from pandas._libs import lib
 from pandas.util._decorators import cache_readonly
-from pandas.util._exceptions import find_stack_level
+from pandas.util._exceptions import (
+    Pandas4DeprecationWarning,
+    find_stack_level,
+)
 
 from pandas.core.dtypes.common import is_bool
 from pandas.core.dtypes.concat import concat_compat
@@ -382,7 +385,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,
+            Pandas4DeprecationWarning,
             stacklevel=find_stack_level(),
         )
 

pandas/io/feather_format.py

@@ -13,6 +13,7 @@
 from pandas._libs import lib
 from pandas.compat._optional import import_optional_dependency
 from pandas.util._decorators import doc
+from pandas.util._exceptions import Pandas4DeprecationWarning
 from pandas.util._validators import check_dtype_backend
 
 import pandas as pd
@@ -136,7 +137,7 @@ def read_feather(
                 warnings.filterwarnings(
                     "ignore",
                     "make_block is deprecated",
-                    DeprecationWarning,
+                    Pandas4DeprecationWarning,
                 )
 
                 return feather.read_feather(

pandas/io/parquet.py

@@ -21,6 +21,7 @@
 from pandas.compat._optional import import_optional_dependency
 from pandas.errors import AbstractMethodError
 from pandas.util._decorators import doc
+from pandas.util._exceptions import Pandas4DeprecationWarning
 from pandas.util._validators import check_dtype_backend
 
 import pandas as pd
@@ -278,7 +279,7 @@ def read(
                 filterwarnings(
                     "ignore",
                     "make_block is deprecated",
-                    DeprecationWarning,
+                    Pandas4DeprecationWarning,
                 )
                 result = pa_table.to_pandas(**to_pandas_kwargs)
 
@@ -397,7 +398,7 @@ def read(
                 filterwarnings(
                     "ignore",
                     "make_block is deprecated",
-                    DeprecationWarning,
+                    Pandas4DeprecationWarning,
                 )
                 return parquet_file.to_pandas(
                     columns=columns, filters=filters, **kwargs

pandas/io/parsers/arrow_parser_wrapper.py

@@ -11,7 +11,10 @@
     ParserError,
     ParserWarning,
 )
-from pandas.util._exceptions import find_stack_level
+from pandas.util._exceptions import (
+    Pandas4DeprecationWarning,
+    find_stack_level,
+)
 
 from pandas.core.dtypes.common import pandas_dtype
 from pandas.core.dtypes.inference import is_integer
@@ -291,7 +294,7 @@ def read(self) -> DataFrame:
             warnings.filterwarnings(
                 "ignore",
                 "make_block is deprecated",
-                DeprecationWarning,
+                Pandas4DeprecationWarning,
             )
             if dtype_backend == "pyarrow":
                 frame = table.to_pandas(types_mapper=pd.ArrowDtype)

pandas/tests/copy_view/test_copy_deprecation.py

@@ -1,5 +1,7 @@
 import pytest
 
+from pandas.util._exceptions import Pandas4DeprecationWarning
+
 import pandas as pd
 from pandas import (
     concat,
@@ -38,34 +40,34 @@ def test_copy_deprecation(meth, kwargs):
         df = df.set_index(["b", "c"])
 
     if meth != "swaplevel":
-        with tm.assert_produces_warning(DeprecationWarning, match="copy"):
+        with tm.assert_produces_warning(Pandas4DeprecationWarning, match="copy"):
             getattr(df, meth)(copy=False, **kwargs)
 
     if meth != "transpose":
-        with tm.assert_produces_warning(DeprecationWarning, match="copy"):
+        with tm.assert_produces_warning(Pandas4DeprecationWarning, match="copy"):
             getattr(df.a, meth)(copy=False, **kwargs)
 
 
 def test_copy_deprecation_reindex_like_align():
     df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
     # Somehow the stack level check is incorrect here
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas4DeprecationWarning, match="copy", check_stacklevel=False
     ):
         df.reindex_like(df, copy=False)
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas4DeprecationWarning, match="copy", check_stacklevel=False
     ):
         df.a.reindex_like(df.a, copy=False)
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas4DeprecationWarning, match="copy", check_stacklevel=False
     ):
         df.align(df, copy=False)
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas4DeprecationWarning, match="copy", check_stacklevel=False
     ):
         df.a.align(df.a, copy=False)
 
@@ -74,16 +76,16 @@ def test_copy_deprecation_merge_concat():
     df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas4DeprecationWarning, match="copy", check_stacklevel=False
     ):
         df.merge(df, copy=False)
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas4DeprecationWarning, match="copy", check_stacklevel=False
     ):
         merge(df, df, copy=False)
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas4DeprecationWarning, match="copy", check_stacklevel=False
     ):
         concat([df, df], copy=False)

pandas/tests/extension/test_arrow.py

@@ -43,6 +43,7 @@
     pa_version_under13p0,
     pa_version_under14p0,
 )
+from pandas.util._exceptions import Pandas4DeprecationWarning
 import pandas.util._test_decorators as td
 
 from pandas.core.dtypes.dtypes import (
@@ -2862,14 +2863,14 @@ def test_dt_to_pytimedelta():
     ser = pd.Series(data, dtype=ArrowDtype(pa.duration("ns")))
 
     msg = "The behavior of ArrowTemporalProperties.to_pytimedelta is deprecated"
-    with tm.assert_produces_warning(FutureWarning, match=msg):
+    with tm.assert_produces_warning(Pandas4DeprecationWarning, match=msg):
         result = ser.dt.to_pytimedelta()
     expected = np.array(data, dtype=object)
     tm.assert_numpy_array_equal(result, expected)
     assert all(type(res) is timedelta for res in result)
 
     msg = "The behavior of TimedeltaProperties.to_pytimedelta is deprecated"
-    with tm.assert_produces_warning(FutureWarning, match=msg):
+    with tm.assert_produces_warning(Pandas4DeprecationWarning, match=msg):
         expected = ser.astype("timedelta64[ns]").dt.to_pytimedelta()
     tm.assert_numpy_array_equal(result, expected)
 

pandas/tests/frame/methods/test_reindex_like.py

@@ -1,6 +1,8 @@
 import numpy as np
 import pytest
 
+from pandas.util._exceptions import Pandas4DeprecationWarning
+
 from pandas import DataFrame
 import pandas._testing as tm
 
@@ -22,10 +24,10 @@ def test_reindex_like(self, float_frame):
     def test_reindex_like_methods(self, method, expected_values):
         df = DataFrame({"x": list(range(5))})
 
-        with tm.assert_produces_warning(FutureWarning):
+        with tm.assert_produces_warning(Pandas4DeprecationWarning):
             result = df.reindex_like(df, method=method, tolerance=0)
         tm.assert_frame_equal(df, result)
-        with tm.assert_produces_warning(FutureWarning):
+        with tm.assert_produces_warning(Pandas4DeprecationWarning):
             result = df.reindex_like(df, method=method, tolerance=[0, 0, 0, 0])
         tm.assert_frame_equal(df, result)
 

pandas/tests/groupby/test_all_methods.py

@@ -13,6 +13,8 @@
 
 import pytest
 
+from pandas.util._exceptions import Pandas4DeprecationWarning
+
 import pandas as pd
 from pandas import DataFrame
 import pandas._testing as tm
@@ -26,7 +28,7 @@ def test_multiindex_group_all_columns_when_empty(groupby_func):
     method = getattr(gb, groupby_func)
     args = get_groupby_method_args(groupby_func, df)
     if groupby_func == "corrwith":
-        warn = FutureWarning
+        warn = Pandas4DeprecationWarning
         warn_msg = "DataFrameGroupBy.corrwith is deprecated"
     else:
         warn = None
@@ -72,7 +74,7 @@ def test_dup_labels_output_shape(groupby_func, idx):
 
     args = get_groupby_method_args(groupby_func, df)
     if groupby_func == "corrwith":
-        warn = FutureWarning
+        warn = Pandas4DeprecationWarning
         warn_msg = "DataFrameGroupBy.corrwith is deprecated"
     else:
         warn = None

pandas/tests/groupby/test_apply.py

@@ -6,6 +6,8 @@
 import numpy as np
 import pytest
 
+from pandas.util._exceptions import Pandas4DeprecationWarning
+
 import pandas as pd
 from pandas import (
     DataFrame,
@@ -1198,7 +1200,7 @@ def test_apply_is_unchanged_when_other_methods_are_called_first(reduction_func):
     grp = df.groupby(by="a")
     args = get_groupby_method_args(reduction_func, df)
     if reduction_func == "corrwith":
-        warn = FutureWarning
+        warn = Pandas4DeprecationWarning
         msg = "DataFrameGroupBy.corrwith is deprecated"
     else:
         warn = None