DOC: Inconsistent return type documentation for functions with "inplace" option

[SycamoreLeaf]

Location of the documentation

This proposal concerns all methods with the inplace keyword argument. Three examples:

1 (Return type described as "blah-blah-type or None if inplace=True) https://pandas.pydata.org/docs/dev/reference/api/pandas.CategoricalIndex.add_categories.html?highlight=inplace

2 (Return type specified, but doesn't mention None) https://pandas.pydata.org/docs/dev/reference/api/pandas.Series.interpolate.html?highlight=inplace

Documentation problem

Many methods in pandas have keyword argument inplace. When inplace=True is supplied, the method updates self and returns None. When inplace=False is supplied, the method does not affect self and returns a changed copy of self.

Some of these functions' return types are documented as "Returns blah-type if inplace=True". Others just say "Returns blah-type". This is confusing because it suggests inconsistencies in behavior that are not really there.

Suggested fix for documentation

Find all methods with the inplace keyword argument. Change the "returns" section of their docstrings to this form:

        Returns
        -------
        Series or DataFrame
            Returns the same object type as the caller, interpolated at
            some or all ``NaN`` values. (Or return `None` if
            `inplace=True`.)

Also change all the formal return type signatures to the form "--> Optional[Foo]" if they aren't all already like that.

[SycamoreLeaf]

I will take this issue if it gets any support.

[rhshadrach]

Thanks for raising this issue, correcting the documentation as you mentioned is certainly welcomed. I would recommend not making it a parenthetical statement as it does not provide context nor expand upon the previous sentence, but is essential to the correctness.

[SycamoreLeaf]

take

[junjunjunk]

take

[junjunjunk]

The following methods have the inplace keyword argument.
( I searched docs with "inplace" keyward. Please point out any omissions.)

DataFrame

• pandas.DataFrame.backfill
• pandas.DataFrame.bfill
• pandas.DataFrame.clip
• pandas.DataFrame.drop
• pandas.DataFrame.drop_duplicates
• pandas.DataFrame.dropna
• pandas.DataFrame.eval
• pandas.DataFrame.ffill
• pandas.DataFrame.fillna
• pandas.DataFrame.interpolate
• pandas.DataFrame.mask
• pandas.DataFrame.pad
• pandas.DataFrame.query
• pandas.DataFrame.rename
• pandas.DataFrame.rename_axis
• pandas.DataFrame.replace
• pandas.DataFrame.reset_index
• pandas.DataFrame.set_axis
• pandas.DataFrame.set_index
• pandas.DataFrame.sort_index
• pandas.DataFrame.sort_values
• pandas.DataFrame.where

Series

• pandas.Series.backfill
• pandas.Series.bfill
• pandas.Series.cat.add_categories
• pandas.Series.cat.as_ordered
• pandas.Series.cat.as_unordered
• pandas.Series.cat.remove_categories
• pandas.Series.cat.remove_unused_categories
• pandas.Series.cat.rename_categories
• pandas.Series.cat.reorder_categories
• pandas.Series.cat.set_categories
• pandas.Series.clip
• pandas.Series.drop
• pandas.Series.drop_duplicates
• pandas.Series.dropna
• pandas.Series.ffill
• pandas.Series.fillna
• pandas.Series.interpolate
• pandas.Series.mask
• pandas.Series.pad
• pandas.Series.rename
• pandas.Series.rename_axis
• pandas.Series.replace
• pandas.Series.reset_index
• pandas.Series.set_axis
• pandas.Series.sort_index
• pandas.Series.sort_values
• pandas.Series.where

Other

• pandas.eval
• pandas.Index.rename
• pandas.Index.set_names
• pandas.MultiIndex.set_codes
• pandas.MultiIndex.set_levels
• pandas.CategoricalIndex.add_categories
• pandas.CategoricalIndex.as_ordered
• pandas.CategoricalIndex.as_unordered
• pandas.CategoricalIndex.remove_categories
• pandas.CategoricalIndex.remove_unused_categories
• pandas.CategoricalIndex.rename_categories
• pandas.CategoricalIndex.reorder_categories
• pandas.CategoricalIndex.set_categories
• pandas.core.groupby.DataFrameGroupBy.fillna
• pandas.core.resample.Resampler.interpolate

[junjunjunk]

I'm going to change the "returns" section of their docstrings as follow.
This is the example of https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.dropna.html .

        Returns
        -------
        DataFrame
            DataFrame with NA entries dropped from it.

to

        Returns
        -------
        DataFrame or None
            DataFrame with NA entries dropped from it or None if inplace=True.

If the docstring already has a similar description, does it need to be modified to make the description consistent across all methods?

[junjunjunk]

Then, in the example of https://pandas.pydata.org/docs/dev/reference/api/pandas.CategoricalIndex.add_categories.html , would be as follows.

        Returns
        -------
        cat : Categorical with new categories added or None if inplace.

to

        Returns
        -------
        cat : Categorical or None
            Categorical with new categories added or None if inplace=True.

[junjunjunk]

And I found the source link is wrong in https://pandas.pydata.org/docs/dev/reference/api/pandas.CategoricalIndex.add_categories.html .

Should This link jump to the following link?

pandas/pandas/core/arrays/categorical.py

Line 943 in 40daf00

def add_categories(self, new_categories, inplace=False):

If corrections are needed, I'll set up a separate issue.

[rhshadrach]

+1 on editing of docstrings, including making them consistent. It looks like you are right, and yes a separate issue should be raised.

[junjunjunk]

Thank you for reply.
I raised an separate issue. #36858