Pandas Unclear error statement printed when python ./scripts/validate_docstrings.py --errors=PR02 is run

When I run python ./scripts/validate_docstrings.py --errors=PR02, one of the error statements printed is /home/pandas/pandas/core/generic.py:1092:PR02:pandas.DataFrame.rename_axis:Unknown parameters {'inplace'}. However in the generic.py file, "inplace" is declared in the function, overloaded functions, and the doc-string, so I was unsure what the error statement meant.

Comment From: MarcoGorelli

Thanks for the report - I think the issue is that rewrite_axis_style_signature isn't keeping inplace in the signature

Comment From: MarcoGorelli

Does it work to get around this by applying:

diff --git a/pandas/core/generic.py b/pandas/core/generic.py
index 8ed3ba0299..96118dda55 100644
--- a/pandas/core/generic.py
+++ b/pandas/core/generic.py
@@ -1140,12 +1140,11 @@ class NDFrame(PandasObject, indexing.IndexingMixin):
     ) -> NDFrameT | None:
         ...

-    @rewrite_axis_style_signature("mapper", [("copy", True)])
+    @rewrite_axis_style_signature("mapper", [("copy", True), ('inplace', False)])
     @deprecate_nonkeyword_arguments(version=None, allowed_args=["self", "mapper"])
     def rename_axis(
         self: NDFrameT,
         mapper: IndexLabel | lib.NoDefault = lib.no_default,
-        inplace: bool_t = False,
         **kwargs,
     ) -> NDFrameT | None:
         """
@@ -1271,7 +1270,6 @@ class NDFrame(PandasObject, indexing.IndexingMixin):
                cat            4         0
                monkey         2         2
         """
-        kwargs["inplace"] = inplace
         axes, kwargs = self._construct_axes_from_arguments(
             (), kwargs, sentinel=lib.no_default
         )

?

If so, do you want to make a PR?

Comment From: MarcoGorelli

@twoertwein looks like this was changed in #47587 - is it OK to put inplace back into @rewrite_axis_style_signature?

Comment From: twoertwein

If inplace is back in the decorator, there is no way for static type checkers to know that is parameter exists. In this case, knowing the value of inplace is important to determine the output of the method.

I haven't looked into the doc issue, ideally, the docs should know that this parameter exists.

Comment From: MarcoGorelli

Thanks - where is it needed? Aren't the overloads enough? e.g.

(pandas-dev) marco@marco-Predator-PH315-52:~/pandas-marco$ cat t.py 
import pandas as pd

df = pd.DataFrame({'a': [1,2,3]})

reveal_type(df.rename_axis(index='foo'))
reveal_type(df.rename_axis(index='foo', inplace=True))
(pandas-dev) marco@marco-Predator-PH315-52:~/pandas-marco$ mypy t.py 
t.py:5: note: Revealed type is "pandas.core.frame.DataFrame"
t.py:6: note: Revealed type is "None"
Success: no issues found in 1 source file

Comment From: twoertwein

Aren't the overloads enough?

That's a good point! The overloads might actually be enough. When a function has overloads, the implementation is not actually used for type checking (there might be some consistency checks between overloads and implementation but you could add an ignore comment if needed).