DOC: Questions on Usage of *args, **kwargs, and inplace parameters in pandas.Series.cat methods

[saldanhad]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.Series.cat.remove_categories.html#pandas.Series.cat.remove_categories

https://pandas.pydata.org/docs/reference/api/pandas.Series.cat.rename_categories.html#pandas.Series.cat.rename_categories

Documentation problem

I am currently trying to work on the issue #59592, specifically for the remove_categories and rename_categories methods. Before finalizing my changes, I need some clarification on a few points regarding the documentation:

1. *args and **kwargs Usage:

• For remove_categories, the method only seems to use the removals parameter.
• Similarly, for rename_categories, *args and **kwargs are mentioned but not utilized in the method implementation. Could you clarify whether the inclusion of *args and **kwargs in the documentation for methods is by design?
• I have noticed this pattern across many methods and wanted to confirm if this is intentional or if the documentation should be updated to reflect actual usage.

2. inplace Parameter: The inplace parameter for methods is included in the error codes of the validation docstring. However, it is not explicitly mentioned in the current documentation, nor is it included as part of the method definition for both methods.

Suggested fix for documentation

Verify usage of **args, **kwargs, and 'inplace' if not make changes to the pandas.Series.cat methods in docs.

[rhshadrach]

Thanks for the report! In the pandas code, the signature of the function is

def remove_categories(self, removals) -> Self:

I believe when we wrap it for adding it to the cat accessor, the signature gets changed to *args, **kwargs as these are passed through by _create_delegator_method:

pandas/pandas/core/accessor.py

Line 119 in 73c4fce

def _create_delegator_method(name: str):

I wonder if we should be using functools.wraps here. E.g.

import functools as ft
import inspect

def add_one(func):
    @ft.wraps(func)
    def wrapper(*args, **kwargs):
        args = (args[0]+1, *args[1:])
        return func(*args, **kwargs)
    return wrapper

@add_one
def foo(a, b, c=5):
    return 100 * a + 10 * b + c

print(foo(1, 2))
# 225

print(inspect.signature(foo))
# <Signature (a, b, c=5)>

Without @ft.wraps(func), you get the signature *args, **kwargs.

Further investigations and PRs to improve are welcome!

[saldanhad]

take