ENH: New proposed deprecation policy

doc/source/whatsnew/v3.0.0.rst

@@ -24,6 +24,10 @@ 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.
+
 .. _whatsnew_300.enhancements.other:
 
 Other enhancements
@@ -159,6 +163,7 @@ Other API changes
 Deprecations
 ~~~~~~~~~~~~
 
+
 Copy keyword
 ^^^^^^^^^^^^
 

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 (
+    Pandas40DeprecationWarning,
+    find_stack_level,
+)
 
 from pandas._libs.tslibs.conversion cimport (
     _TSObject,
@@ -1423,7 +1426,7 @@ class Timestamp(_Timestamp):
             #  GH#56680
             "Timestamp.utcnow is deprecated and will be removed in a future "
             "version. Use Timestamp.now('UTC') instead.",
-            FutureWarning,
+            Pandas40DeprecationWarning,
             stacklevel=find_stack_level(),
         )
         return cls.now(UTC)
@@ -1451,7 +1454,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,
+            Pandas40DeprecationWarning,
             stacklevel=find_stack_level(),
         )
         return cls.fromtimestamp(ts, tz="UTC")

pandas/core/generic.py

@@ -94,7 +94,10 @@
 )
 from pandas.errors.cow import _chained_assignment_method_msg
 from pandas.util._decorators import doc
-from pandas.util._exceptions import find_stack_level
+from pandas.util._exceptions import (
+    Pandas40DeprecationWarning,
+    find_stack_level,
+)
 from pandas.util._validators import (
     check_dtype_backend,
     validate_ascending,
@@ -4255,7 +4258,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,
+                Pandas40DeprecationWarning,
                 stacklevel=find_stack_level(),
             )
 

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 (
+    Pandas40DeprecationWarning,
+    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,
+            Pandas40DeprecationWarning,
             stacklevel=find_stack_level(),
         )
 

pandas/core/window/expanding.py

@@ -709,7 +709,7 @@ def kurt(self, numeric_only: bool = False):
         aggregation_description="quantile",
         agg_method="quantile",
     )
-    @deprecate_kwarg(old_arg_name="quantile", new_arg_name="q")
+    @deprecate_kwarg(old_arg_name="quantile", new_arg_name="q", klass=FutureWarning)
     def quantile(
         self,
         q: float,

pandas/core/window/rolling.py

@@ -2556,7 +2556,7 @@ def kurt(self, numeric_only: bool = False):
         aggregation_description="quantile",
         agg_method="quantile",
     )
-    @deprecate_kwarg(old_arg_name="quantile", new_arg_name="q")
+    @deprecate_kwarg(old_arg_name="quantile", new_arg_name="q", klass=FutureWarning)
     def quantile(
         self,
         q: float,

pandas/tests/copy_view/test_copy_deprecation.py

@@ -1,5 +1,7 @@
 import pytest
 
+from pandas.util._exceptions import Pandas40DeprecationWarning
+
 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(Pandas40DeprecationWarning, match="copy"):
             getattr(df, meth)(copy=False, **kwargs)
 
     if meth != "transpose":
-        with tm.assert_produces_warning(DeprecationWarning, match="copy"):
+        with tm.assert_produces_warning(Pandas40DeprecationWarning, 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
+        Pandas40DeprecationWarning, match="copy", check_stacklevel=False
     ):
         df.reindex_like(df, copy=False)
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas40DeprecationWarning, match="copy", check_stacklevel=False
     ):
         df.a.reindex_like(df.a, copy=False)
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas40DeprecationWarning, match="copy", check_stacklevel=False
     ):
         df.align(df, copy=False)
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas40DeprecationWarning, 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
+        Pandas40DeprecationWarning, match="copy", check_stacklevel=False
     ):
         df.merge(df, copy=False)
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas40DeprecationWarning, match="copy", check_stacklevel=False
     ):
         merge(df, df, copy=False)
 
     with tm.assert_produces_warning(
-        DeprecationWarning, match="copy", check_stacklevel=False
+        Pandas40DeprecationWarning, match="copy", check_stacklevel=False
     ):
         concat([df, df], copy=False)

pandas/tests/io/formats/test_to_markdown.py

@@ -2,6 +2,8 @@
 
 import pytest
 
+from pandas.util._exceptions import Pandas40DeprecationWarning
+
 import pandas as pd
 import pandas._testing as tm
 
@@ -15,7 +17,7 @@ def test_keyword_deprecation():
         "except for the argument 'buf' will be keyword-only."
     )
     s = pd.Series()
-    with tm.assert_produces_warning(FutureWarning, match=msg):
+    with tm.assert_produces_warning(Pandas40DeprecationWarning, match=msg):
         s.to_markdown(None, "wt")
 
 

pandas/tests/io/formats/test_to_string.py

@@ -12,6 +12,8 @@
 
 from pandas._config import using_pyarrow_string_dtype
 
+from pandas.util._exceptions import Pandas40DeprecationWarning
+
 from pandas import (
     CategoricalIndex,
     DataFrame,
@@ -42,7 +44,7 @@ def test_keyword_deprecation(self):
             "except for the argument 'buf' will be keyword-only."
         )
         s = Series(["a", "b"])
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas40DeprecationWarning, match=msg):
             s.to_string(None, "NaN")
 
     def test_to_string_masked_ea_with_formatter(self):

pandas/tests/scalar/timestamp/test_constructors.py

@@ -20,6 +20,7 @@
 from pandas._libs.tslibs.dtypes import NpyDatetimeUnit
 from pandas.compat import PY310
 from pandas.errors import OutOfBoundsDatetime
+from pandas.util._exceptions import Pandas40DeprecationWarning
 
 from pandas import (
     NA,
@@ -332,13 +333,13 @@ class TestTimestampClassMethodConstructors:
     def test_utcnow_deprecated(self):
         # GH#56680
         msg = "Timestamp.utcnow is deprecated"
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas40DeprecationWarning, match=msg):
             Timestamp.utcnow()
 
     def test_utcfromtimestamp_deprecated(self):
         # GH#56680
         msg = "Timestamp.utcfromtimestamp is deprecated"
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas40DeprecationWarning, match=msg):
             Timestamp.utcfromtimestamp(43)
 
     def test_constructor_strptime(self):

pandas/tests/scalar/timestamp/test_timestamp.py

@@ -31,6 +31,7 @@
     tz_compare,
 )
 from pandas.compat import IS64
+from pandas.util._exceptions import Pandas40DeprecationWarning
 
 from pandas import (
     NaT,
@@ -269,7 +270,7 @@ def test_disallow_setting_tz(self, tz):
 
     def test_default_to_stdlib_utc(self):
         msg = "Timestamp.utcnow is deprecated"
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas40DeprecationWarning, match=msg):
             assert Timestamp.utcnow().tz is timezone.utc
         assert Timestamp.now("UTC").tz is timezone.utc
         assert Timestamp("2016-01-01", tz="UTC").tz is timezone.utc
@@ -314,13 +315,13 @@ def compare(x, y):
         compare(Timestamp.now("UTC"), datetime.now(pytz.timezone("UTC")))
         compare(Timestamp.now("UTC"), datetime.now(tzutc()))
         msg = "Timestamp.utcnow is deprecated"
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas40DeprecationWarning, match=msg):
             compare(Timestamp.utcnow(), datetime.now(timezone.utc))
         compare(Timestamp.today(), datetime.today())
         current_time = calendar.timegm(datetime.now().utctimetuple())
 
         msg = "Timestamp.utcfromtimestamp is deprecated"
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas40DeprecationWarning, match=msg):
             ts_utc = Timestamp.utcfromtimestamp(current_time)
         assert ts_utc.timestamp() == current_time
         compare(

pandas/tests/tools/test_to_datetime.py

@@ -1006,7 +1006,9 @@ def test_to_datetime_today(self, tz):
     def test_to_datetime_today_now_unicode_bytes(self, arg):
         to_datetime([arg])
 
-    @pytest.mark.filterwarnings("ignore:Timestamp.utcnow is deprecated:FutureWarning")
+    @pytest.mark.filterwarnings(
+        "ignore:Timestamp.utcnow is deprecated:DeprecationWarning"
+    )
     @pytest.mark.parametrize(
         "format, expected_ds",
         [

pandas/tests/util/test_deprecate.py

@@ -37,7 +37,9 @@ def new_func_with_deprecation():
 
 
 def test_deprecate_ok():
-    depr_func = deprecate("depr_func", new_func, "1.0", msg="Use new_func instead.")
+    depr_func = deprecate(
+        "depr_func", new_func, "1.0", msg="Use new_func instead.", klass=FutureWarning
+    )
 
     with tm.assert_produces_warning(FutureWarning):
         result = depr_func()
@@ -48,7 +50,11 @@ def test_deprecate_ok():
 
 def test_deprecate_no_docstring():
     depr_func = deprecate(
-        "depr_func", new_func_no_docstring, "1.0", msg="Use new_func instead."
+        "depr_func",
+        new_func_no_docstring,
+        "1.0",
+        msg="Use new_func instead.",
+        klass=FutureWarning,
     )
     with tm.assert_produces_warning(FutureWarning):
         result = depr_func()

pandas/tests/util/test_deprecate_kwarg.py

@@ -5,15 +5,15 @@
 import pandas._testing as tm
 
 
-@deprecate_kwarg("old", "new")
+@deprecate_kwarg("old", "new", klass=FutureWarning)
 def _f1(new=False):
     return new
 
 
 _f2_mappings = {"yes": True, "no": False}
 
 
-@deprecate_kwarg("old", "new", _f2_mappings)
+@deprecate_kwarg("old", "new", _f2_mappings, klass=FutureWarning)
 def _f2(new=False):
     return new
 
@@ -22,7 +22,7 @@ def _f3_mapping(x):
     return x + 1
 
 
-@deprecate_kwarg("old", "new", _f3_mapping)
+@deprecate_kwarg("old", "new", _f3_mapping, klass=FutureWarning)
 def _f3(new=0):
     return new
 
@@ -70,7 +70,7 @@ def f4(new=None):
             return new
 
 
-@deprecate_kwarg("old", None)
+@deprecate_kwarg("old", None, klass=FutureWarning)
 def _f4(old=True, unchanged=True):
     return old, unchanged
 

pandas/tests/util/test_deprecate_nonkeyword_arguments.py

@@ -10,7 +10,7 @@
 
 
 @deprecate_nonkeyword_arguments(
-    version="1.1", allowed_args=["a", "b"], name="f_add_inputs"
+    version="1.1", allowed_args=["a", "b"], name="f_add_inputs", klass=FutureWarning
 )
 def f(a, b=0, c=0, d=0):
     return a + b + c + d
@@ -59,7 +59,7 @@ def test_three_arguments_with_name_in_warning():
         assert f(6, 3, 3) == 12
 
 
-@deprecate_nonkeyword_arguments(version="1.1")
+@deprecate_nonkeyword_arguments(version="1.1", klass=FutureWarning)
 def g(a, b=0, c=0, d=0):
     with tm.assert_produces_warning(None):
         return a + b + c + d
@@ -88,7 +88,7 @@ def test_three_positional_argument_with_warning_message_analysis():
         assert g(6, 3, 3) == 12
 
 
-@deprecate_nonkeyword_arguments(version="1.1")
+@deprecate_nonkeyword_arguments(version="1.1", klass=FutureWarning)
 def h(a=0, b=0, c=0, d=0):
     return a + b + c + d
 
@@ -113,7 +113,7 @@ def test_one_positional_argument_with_warning_message_analysis():
         assert h(19) == 19
 
 
-@deprecate_nonkeyword_arguments(version="1.1")
+@deprecate_nonkeyword_arguments(version="1.1", klass=FutureWarning)
 def i(a=0, /, b=0, *, c=0, d=0):
     return a + b + c + d
 
@@ -123,7 +123,9 @@ def test_i_signature():
 
 
 class Foo:
-    @deprecate_nonkeyword_arguments(version=None, allowed_args=["self", "bar"])
+    @deprecate_nonkeyword_arguments(
+        version=None, allowed_args=["self", "bar"], klass=FutureWarning
+    )
     def baz(self, bar=None, foobar=None):  # pylint: disable=disallowed-name
         ...