CLN: Lint for usage of Deprecation/FutureWarning

Author: rhshadrach

.pre-commit-config.yaml

@@ -266,6 +266,11 @@ repos:
         language: python
         entry: python scripts/validate_unwanted_patterns.py --validation-type="nodefault_used_not_only_for_typing"
         types: [python]
+    -   id: unwanted-patterns-doesnt-use-pandas-warnings
+        name: Check that warning classes for deprecations use pandas' warning classes
+        language: python
+        entry: python scripts/validate_unwanted_patterns.py --validation-type="doesnt_use_pandas_warnings"
+        types: [ python ]
     -   id: no-return-exception
         name: Use raise instead of return for exceptions
         language: pygrep

pandas/core/generic.py

@@ -9138,7 +9138,7 @@ def resample(
                 "deprecated and will be removed in a future version. "
                 "Explicitly cast PeriodIndex to DatetimeIndex before resampling "
                 "instead.",
-                FutureWarning,
+                FutureWarning,  # pdlint: ignore
                 stacklevel=find_stack_level(),
             )
         else:

pandas/core/groupby/groupby.py

@@ -557,7 +557,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,
+                FutureWarning,  # pdlint: ignore
                 stacklevel=find_stack_level(),
             )
         return self._grouper.groups

pandas/core/internals/__init__.py

@@ -25,7 +25,7 @@ def __getattr__(name: str):
         warnings.warn(
             f"{name} is deprecated and will be removed in a future version. "
             "Use public APIs instead.",
-            FutureWarning,
+            FutureWarning,  # pdlint: ignore
             # https://github.com/pandas-dev/pandas/pull/55139#pullrequestreview-1720690758
             # on hard-coding stacklevel
             stacklevel=2,

pandas/core/series.py

@@ -4435,7 +4435,7 @@ def map(
                 warnings.warn(
                     "The parameter `arg` has been renamed to `func`, and it "
                     "will stop being supported in a future version of pandas.",
-                    FutureWarning,
+                    FutureWarning,  # pdlint: ignore
                     stacklevel=find_stack_level(),
                 )
             else:

pandas/core/strings/object_array.py

@@ -163,7 +163,7 @@ def _str_contains(
             warnings.warn(
                 "Allowing a non-bool 'na' in obj.str.contains is deprecated "
                 "and will raise in a future version.",
-                FutureWarning,
+                FutureWarning,  # pdlint: ignore
                 stacklevel=find_stack_level(),
             )
         return self._str_map(f, na, dtype=np.dtype("bool"))
@@ -175,7 +175,7 @@ def _str_startswith(self, pat, na=lib.no_default):
             warnings.warn(
                 "Allowing a non-bool 'na' in obj.str.startswith is deprecated "
                 "and will raise in a future version.",
-                FutureWarning,
+                FutureWarning,  # pdlint: ignore
                 stacklevel=find_stack_level(),
             )
         return self._str_map(f, na_value=na, dtype=np.dtype(bool))
@@ -187,7 +187,7 @@ def _str_endswith(self, pat, na=lib.no_default):
             warnings.warn(
                 "Allowing a non-bool 'na' in obj.str.endswith is deprecated "
                 "and will raise in a future version.",
-                FutureWarning,
+                FutureWarning,  # pdlint: ignore
                 stacklevel=find_stack_level(),
             )
         return self._str_map(f, na_value=na, dtype=np.dtype(bool))

scripts/tests/test_validate_unwanted_patterns.py

@@ -296,3 +296,37 @@ def test_nodefault_used_not_only_for_typing_raises(self, data, expected) -> None
         fd = io.StringIO(data.strip())
         result = list(validate_unwanted_patterns.nodefault_used_not_only_for_typing(fd))
         assert result == expected
+
+
+@pytest.mark.parametrize("function", ["warnings.warn", "warn"])
+@pytest.mark.parametrize("positional", [True, False])
+@pytest.mark.parametrize(
+    "category",
+    [
+        "FutureWarning",
+        "DeprecationWarning",
+        "PendingDeprecationWarning",
+        "Pandas4Warning",
+        "RuntimeWarning"
+    ],
+)
+@pytest.mark.parametrize("pdlint_ignore", [True, False])
+
+def test_doesnt_use_pandas_warnings(function, positional, category, pdlint_ignore):
+    code = (
+        f"{function}({'  # pdlint: ignore[warning_class]' if pdlint_ignore else ''}\n"
+        f'   "message",\n'
+        f"   {'' if positional else 'category='}{category},\n"
+        f")\n"
+    )
+    flag_issue = (
+        category in ["FutureWarning", "DeprecationWarning", "PendingDeprecationWarning"]
+        and not pdlint_ignore
+    )
+    fd = io.StringIO(code)
+    result = list(validate_unwanted_patterns.doesnt_use_pandas_warnings(fd))
+    if flag_issue:
+        assert len(result) == 1
+        assert result[0] == (1, f"Don't use {category}")
+    else:
+        assert len(result) == 0

scripts/validate_unwanted_patterns.py

@@ -16,11 +16,15 @@
     Callable,
     Iterable,
 )
+import re
 import sys
 import token
 import tokenize
 from typing import IO
 
+DEPRECATION_WARNINGS_PATTERN = re.compile(
+    r"(PendingDeprecation|Deprecation|Future)Warning"
+)
 PRIVATE_IMPORTS_TO_IGNORE: set[str] = {
     "_extension_array_shared_docs",
     "_index_shared_docs",
@@ -344,6 +348,47 @@ def nodefault_used_not_only_for_typing(file_obj: IO[str]) -> Iterable[tuple[int,
                     if isinstance(value, ast.AST)
                 )
 
+def doesnt_use_pandas_warnings(file_obj: IO[str]) -> Iterable[tuple[int, str]]:
+    """
+    Checking that a private function is not used across modules.
+    Parameters
+    ----------
+    file_obj : IO
+        File-like object containing the Python code to validate.
+    Yields
+    ------
+    line_number : int
+        Line number of the private function that is used across modules.
+    msg : str
+        Explanation of the error.
+    """
+    contents = file_obj.read()
+    lines = contents.split("\n")
+    tree = ast.parse(contents)
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+
+        if isinstance(node.func, ast.Attribute):
+            if node.func.attr != "warn":
+                continue
+        elif isinstance(node.func, ast.Name):
+            if node.func.id != "warn":
+                continue
+        if any(
+            "# pdlint: ignore[warning_class]" in lines[k]
+            for k in range(node.lineno - 1, node.end_lineno + 1)
+        ):
+            continue
+        values = (
+                [arg.id for arg in node.args if isinstance(arg, ast.Name)]
+                + [kw.value.id for kw in node.keywords if kw.arg == "category"]
+        )
+        for value in values:
+            matches = re.match(DEPRECATION_WARNINGS_PATTERN, value)
+            if matches is not None:
+                yield (node.lineno, f"Don't use {matches[0]}")
+
 
 def main(
     function: Callable[[IO[str]], Iterable[tuple[int, str]]],
@@ -397,6 +442,7 @@ def main(
         "private_import_across_module",
         "strings_with_wrong_placed_whitespace",
         "nodefault_used_not_only_for_typing",
+        "doesnt_use_pandas_warnings",
     ]
 
     parser = argparse.ArgumentParser(description="Unwanted patterns checker.")