Refinements

Author: rhshadrach

pandas/_config/config.py

@@ -73,6 +73,7 @@
 
 class DeprecatedOption(NamedTuple):
     key: str
+    category: type[Warning]
     msg: str | None
     rkey: str | None
     removal_ver: str | None
@@ -589,6 +590,7 @@ def register_option(
 
 def deprecate_option(
     key: str,
+    category: type[Warning],
     msg: str | None = None,
     rkey: str | None = None,
     removal_ver: str | None = None,
@@ -608,6 +610,8 @@ def deprecate_option(
     key : str
         Name of the option to be deprecated.
         must be a fully-qualified option name (e.g "x.y.z.rkey").
+    category : Warning
+        Warning class for the deprecation.
     msg : str, optional
         Warning message to output when the key is referenced.
         if no message is given a default message will be emitted.
@@ -631,7 +635,7 @@ def deprecate_option(
     if key in _deprecated_options:
         raise OptionError(f"Option '{key}' has already been defined as deprecated.")
 
-    _deprecated_options[key] = DeprecatedOption(key, msg, rkey, removal_ver)
+    _deprecated_options[key] = DeprecatedOption(key, category, msg, rkey, removal_ver)
 
 
 #
@@ -716,7 +720,7 @@ def _warn_if_deprecated(key: str) -> bool:
         if d.msg:
             warnings.warn(
                 d.msg,
-                FutureWarning,  # pdlint: ignore[warning_class]
+                d.category,
                 stacklevel=find_stack_level(),
             )
         else:
@@ -730,7 +734,7 @@ def _warn_if_deprecated(key: str) -> bool:
 
             warnings.warn(
                 msg,
-                FutureWarning,  # pdlint: ignore[warning_class]
+                d.category,
                 stacklevel=find_stack_level(),
             )
         return True

pandas/core/groupby/groupby.py

@@ -61,6 +61,7 @@ class providing the base-class of operations.
 from pandas.errors import (
     AbstractMethodError,
     DataError,
+    Pandas4Warning,
 )
 from pandas.util._decorators import (
     Appender,
@@ -557,7 +558,7 @@ def groups(self) -> dict[Hashable, Index]:
                 "and will be removed. In a future version `groups` by one element "
                 "list will return tuple. Use ``df.groupby(by='a').groups`` "
                 "instead of ``df.groupby(by=['a']).groups`` to avoid this warning",
-                FutureWarning,  # pdlint: ignore[warning_class]
+                Pandas4Warning,
                 stacklevel=find_stack_level(),
             )
         return self._grouper.groups

pandas/core/resample.py

@@ -2293,6 +2293,7 @@ def _get_resampler(self, obj: NDFrame) -> Resampler:
             )
         elif isinstance(ax, PeriodIndex):
             if isinstance(ax, PeriodIndex):
+                # TODO: Enforce in 3.0 (#53481)
                 # GH#53481
                 warnings.warn(
                     "Resampling with a PeriodIndex is deprecated. "

pandas/core/strings/object_array.py

@@ -159,6 +159,7 @@ def _str_contains(
                 upper_pat = pat.upper()
                 f = lambda x: upper_pat in x.upper()
         if na is not lib.no_default and not isna(na) and not isinstance(na, bool):
+            # TODO: Enforce in 3.0 (#59615)
             # GH#59561
             warnings.warn(
                 "Allowing a non-bool 'na' in obj.str.contains is deprecated "
@@ -171,6 +172,7 @@ def _str_contains(
     def _str_startswith(self, pat, na=lib.no_default):
         f = lambda x: x.startswith(pat)
         if na is not lib.no_default and not isna(na) and not isinstance(na, bool):
+            # TODO: Enforce in 3.0 (#59615)
             # GH#59561
             warnings.warn(
                 "Allowing a non-bool 'na' in obj.str.startswith is deprecated "
@@ -183,6 +185,7 @@ def _str_startswith(self, pat, na=lib.no_default):
     def _str_endswith(self, pat, na=lib.no_default):
         f = lambda x: x.endswith(pat)
         if na is not lib.no_default and not isna(na) and not isinstance(na, bool):
+            # TODO: Enforce in 3.0 (#59615)
             # GH#59561
             warnings.warn(
                 "Allowing a non-bool 'na' in obj.str.endswith is deprecated "

pandas/tests/config/test_config.py

@@ -75,14 +75,14 @@ def test_register_option(self):
     def test_describe_option(self):
         cf.register_option("a", 1, "doc")
         cf.register_option("b", 1, "doc2")
-        cf.deprecate_option("b")
+        cf.deprecate_option("b", FutureWarning)
 
         cf.register_option("c.d.e1", 1, "doc3")
         cf.register_option("c.d.e2", 1, "doc4")
         cf.register_option("f", 1)
         cf.register_option("g.h", 1)
         cf.register_option("k", 2)
-        cf.deprecate_option("g.h", rkey="k")
+        cf.deprecate_option("g.h", FutureWarning, rkey="k")
         cf.register_option("l", "foo")
 
         # non-existent keys raise KeyError
@@ -111,7 +111,8 @@ def test_describe_option(self):
         cf.set_option("l", "bar")
         assert "bar" in cf.describe_option("l", _print_desc=False)
 
-    def test_case_insensitive(self):
+    @pytest.mark.parametrize("category", [DeprecationWarning, FutureWarning])
+    def test_case_insensitive(self, category):
         cf.register_option("KanBAN", 1, "doc")
 
         assert "doc" in cf.describe_option("kanbaN", _print_desc=False)
@@ -124,9 +125,9 @@ def test_case_insensitive(self):
         with pytest.raises(OptionError, match=msg):
             cf.get_option("no_such_option")
 
-        cf.deprecate_option("KanBan")
+        cf.deprecate_option("KanBan", category)
         msg = "'kanban' is deprecated, please refrain from using it."
-        with pytest.raises(FutureWarning, match=msg):
+        with pytest.raises(category, match=msg):
             cf.get_option("kAnBaN")
 
     def test_get_option(self):
@@ -285,7 +286,7 @@ def test_reset_option_all(self):
 
     def test_deprecate_option(self):
         # we can deprecate non-existent options
-        cf.deprecate_option("foo")
+        cf.deprecate_option("foo", FutureWarning)
 
         with tm.assert_produces_warning(FutureWarning, match="deprecated"):
             with pytest.raises(KeyError, match="No such keys.s.: 'foo'"):
@@ -295,15 +296,15 @@ def test_deprecate_option(self):
         cf.register_option("b.c", "hullo", "doc2")
         cf.register_option("foo", "hullo", "doc2")
 
-        cf.deprecate_option("a", removal_ver="nifty_ver")
+        cf.deprecate_option("a", FutureWarning, removal_ver="nifty_ver")
         with tm.assert_produces_warning(FutureWarning, match="eprecated.*nifty_ver"):
             cf.get_option("a")
 
             msg = "Option 'a' has already been defined as deprecated"
             with pytest.raises(OptionError, match=msg):
-                cf.deprecate_option("a")
+                cf.deprecate_option("a", FutureWarning)
 
-        cf.deprecate_option("b.c", "zounds!")
+        cf.deprecate_option("b.c", FutureWarning, "zounds!")
         with tm.assert_produces_warning(FutureWarning, match="zounds!"):
             cf.get_option("b.c")
 
@@ -313,7 +314,7 @@ def test_deprecate_option(self):
         assert cf.get_option("d.a") == "foo"
         assert cf.get_option("d.dep") == "bar"
 
-        cf.deprecate_option("d.dep", rkey="d.a")  # reroute d.dep to d.a
+        cf.deprecate_option("d.dep", FutureWarning, rkey="d.a")  # reroute d.dep to d.a
         with tm.assert_produces_warning(FutureWarning, match="eprecated"):
             assert cf.get_option("d.dep") == "foo"
 

pandas/tests/groupby/test_grouping.py

@@ -10,7 +10,10 @@
 import numpy as np
 import pytest
 
-from pandas.errors import SpecificationError
+from pandas.errors import (
+    Pandas4Warning,
+    SpecificationError,
+)
 
 import pandas as pd
 from pandas import (
@@ -545,21 +548,21 @@ def test_multiindex_columns_empty_level(self):
         grouped = df.groupby("to filter").groups
         assert grouped["A"] == [0]
 
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
             grouped = df.groupby([("to filter", "")]).groups
         assert grouped["A"] == [0]
 
         df = DataFrame([[1, "A"], [2, "B"]], columns=midx)
 
         expected = df.groupby("to filter").groups
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
             result = df.groupby([("to filter", "")]).groups
         assert result == expected
 
         df = DataFrame([[1, "A"], [2, "A"]], columns=midx)
 
         expected = df.groupby("to filter").groups
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
             result = df.groupby([("to filter", "")]).groups
         tm.assert_dict_equal(result, expected)
 
@@ -571,7 +574,7 @@ def test_groupby_multiindex_tuple(self):
         )
 
         msg = "`groups` by one element list returns scalar is deprecated"
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
             expected = df.groupby([("b", 1)]).groups
         result = df.groupby(("b", 1)).groups
         tm.assert_dict_equal(expected, result)
@@ -583,14 +586,14 @@ def test_groupby_multiindex_tuple(self):
             ),
         )
 
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
             expected = df2.groupby([("b", "d")]).groups
         result = df.groupby(("b", 1)).groups
         tm.assert_dict_equal(expected, result)
 
         df3 = DataFrame(df.values, columns=[("a", "d"), ("b", "d"), ("b", "e"), "c"])
 
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
             expected = df3.groupby([("b", "d")]).groups
         result = df.groupby(("b", 1)).groups
         tm.assert_dict_equal(expected, result)
@@ -623,7 +626,7 @@ def test_groupby_multiindex_partial_indexing_equivalence(self):
         tm.assert_frame_equal(expected_max, result_max)
 
         msg = "`groups` by one element list returns scalar is deprecated"
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
             expected_groups = df.groupby([("a", 1)])[[("b", 1), ("b", 2)]].groups
             result_groups = df.groupby([("a", 1)])["b"].groups
         tm.assert_dict_equal(expected_groups, result_groups)
@@ -737,7 +740,7 @@ def test_list_grouper_with_nat(self):
         # Grouper in a list grouping
         gb = df.groupby([grouper])
         expected = {Timestamp("2011-01-01"): Index(list(range(364)))}
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
             result = gb.groups
         tm.assert_dict_equal(result, expected)
 
@@ -1019,7 +1022,7 @@ def test_groups(self, df):
         grouped = df.groupby(["A"])
         msg = "`groups` by one element list returns scalar is deprecated"
 
-        with tm.assert_produces_warning(FutureWarning, match=msg):
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
             groups = grouped.groups
             assert groups is grouped.groups  # caching works
 

scripts/validate_unwanted_patterns.py

@@ -371,10 +371,15 @@ def doesnt_use_pandas_warnings(file_obj: IO[str]) -> Iterable[tuple[int, str]]:
         if not isinstance(node, ast.Call):
             continue
 
-        if isinstance(node.func, ast.Attribute):
-            if node.func.attr != "warn":
+        if (
+            isinstance(node.func, ast.Attribute)
+            and isinstance(node.func.value, ast.Name)
+        ):
+            # Check for `warnings.warn`.
+            if node.func.value.id != "warnings" or node.func.attr != "warn":
                 continue
         elif isinstance(node.func, ast.Name):
+            # Check for just `warn` when using `from warnings import warn`.
             if node.func.id != "warn":
                 continue
         if any(