DOC: make return type documentation of series methods consistent #35409…

… (#36862)
pandas-dev · Oct 10, 2020 · b110046 · b110046
1 parent 7d257c6
commit b110046
Show file tree

Hide file tree

Showing 7 changed files with 63 additions and 55 deletions.
diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py
@@ -723,8 +723,8 @@ def as_ordered(self, inplace=False):
 
         Returns
         -------
-        Categorical
-            Ordered Categorical.
+        Categorical or None
+            Ordered Categorical or None if ``inplace=True``.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         return self.set_ordered(True, inplace=inplace)
@@ -741,8 +741,8 @@ def as_unordered(self, inplace=False):
 
         Returns
         -------
-        Categorical
-            Unordered Categorical.
+        Categorical or None
+            Unordered Categorical or None if ``inplace=True``.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         return self.set_ordered(False, inplace=inplace)
@@ -848,8 +848,7 @@ def rename_categories(self, new_categories, inplace=False):
         Returns
         -------
         cat : Categorical or None
-           With ``inplace=False``, the new categorical is returned.
-           With ``inplace=True``, there is no return value.
+            Categorical with removed categories or None if ``inplace=True``.
 
         Raises
         ------
@@ -917,7 +916,8 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False):
 
         Returns
         -------
-        cat : Categorical with reordered categories or None if inplace.
+        cat : Categorical or None
+            Categorical with removed categories or None if ``inplace=True``.
 
         Raises
         ------
@@ -957,7 +957,8 @@ def add_categories(self, new_categories, inplace=False):
 
         Returns
         -------
-        cat : Categorical with new categories added or None if inplace.
+        cat : Categorical or None
+            Categorical with new categories added or None if ``inplace=True``.
 
         Raises
         ------
@@ -1007,7 +1008,8 @@ def remove_categories(self, removals, inplace=False):
 
         Returns
         -------
-        cat : Categorical with removed categories or None if inplace.
+        cat : Categorical or None
+            Categorical with removed categories or None if ``inplace=True``.
 
         Raises
         ------
@@ -1054,7 +1056,8 @@ def remove_unused_categories(self, inplace=False):
 
         Returns
         -------
-        cat : Categorical with unused categories dropped or None if inplace.
+        cat : Categorical or None
+            Categorical with unused categories dropped or None if ``inplace=True``.
 
         See Also
         --------

diff --git a/pandas/core/computation/eval.py b/pandas/core/computation/eval.py
@@ -242,7 +242,8 @@ def eval(
 
     Returns
     -------
-    ndarray, numeric scalar, DataFrame, Series
+    ndarray, numeric scalar, DataFrame, Series, or None
+        The completion value of evaluating the given code or None if ``inplace=True``.
 
     Raises
     ------

diff --git a/pandas/core/frame.py b/pandas/core/frame.py
@@ -3256,8 +3256,9 @@ def query(self, expr, inplace=False, **kwargs):
 
         Returns
         -------
-        DataFrame
-            DataFrame resulting from the provided query expression.
+        DataFrame or None
+            DataFrame resulting from the provided query expression or
+            None if ``inplace=True``.
 
         See Also
         --------
@@ -3404,8 +3405,8 @@ def eval(self, expr, inplace=False, **kwargs):
 
         Returns
         -------
-        ndarray, scalar, or pandas object
-            The result of the evaluation.
+        ndarray, scalar, pandas object, or None
+            The result of the evaluation or None if ``inplace=True``.
 
         See Also
         --------
@@ -4122,8 +4123,9 @@ def drop(
 
         Returns
         -------
-        DataFrame
-            DataFrame without the removed index or column labels.
+        DataFrame or None
+            DataFrame without the removed index or column labels or
+            None if ``inplace=True``.
 
         Raises
         ------
@@ -4277,8 +4279,8 @@ def rename(
 
         Returns
         -------
-        DataFrame
-            DataFrame with the renamed axis labels.
+        DataFrame or None
+            DataFrame with the renamed axis labels or None if ``inplace=True``.
 
         Raises
         ------
@@ -4533,8 +4535,8 @@ def set_index(
 
         Returns
         -------
-        DataFrame
-            Changed row labels.
+        DataFrame or None
+            Changed row labels or None if ``inplace=True``.
 
         See Also
         --------
@@ -4996,8 +4998,8 @@ def dropna(self, axis=0, how="any", thresh=None, subset=None, inplace=False):
 
         Returns
         -------
-        DataFrame
-            DataFrame with NA entries dropped from it.
+        DataFrame or None
+            DataFrame with NA entries dropped from it or None if ``inplace=True``.
 
         See Also
         --------
@@ -5132,7 +5134,7 @@ def drop_duplicates(
 
         Returns
         -------
-        DataFrame
+        DataFrame or None
             DataFrame with duplicates removed or None if ``inplace=True``.
 
         See Also
@@ -5455,8 +5457,8 @@ def sort_index(
 
         Returns
         -------
-        DataFrame
-            The original DataFrame sorted by the labels.
+        DataFrame or None
+            The original DataFrame sorted by the labels or None if ``inplace=True``.
 
         See Also
         --------

diff --git a/pandas/core/generic.py b/pandas/core/generic.py
@@ -650,7 +650,7 @@ def set_axis(self, labels, axis: Axis = 0, inplace: bool = False):
         Returns
         -------
         renamed : %(klass)s or None
-            An object of type %(klass)s if inplace=False, None otherwise.
+            An object of type %(klass)s or None if ``inplace=True``.
 
         See Also
         --------
@@ -1097,7 +1097,7 @@ def rename_axis(self, mapper=lib.no_default, **kwargs):
         Returns
         -------
         Series, DataFrame, or None
-            The same type as the caller or None if `inplace` is True.
+            The same type as the caller or None if ``inplace=True``.
 
         See Also
         --------
@@ -4330,7 +4330,7 @@ def sort_values(
         Returns
         -------
         DataFrame or None
-            DataFrame with sorted values if inplace=False, None otherwise.
+            DataFrame with sorted values or None if ``inplace=True``.
 
         See Also
         --------
@@ -6471,8 +6471,8 @@ def replace(
 
         Returns
         -------
-        {klass}
-            Object after replacement.
+        {klass} or None
+            Object after replacement or None if ``inplace=True``.
 
         Raises
         ------
@@ -6907,9 +6907,9 @@ def interpolate(
 
         Returns
         -------
-        Series or DataFrame
+        Series or DataFrame or None
             Returns the same object type as the caller, interpolated at
-            some or all ``NaN`` values.
+            some or all ``NaN`` values or None if ``inplace=True``.
 
         See Also
         --------
@@ -7508,9 +7508,9 @@ def clip(
 
         Returns
         -------
-        Series or DataFrame
+        Series or DataFrame or None
             Same type as calling object with the values outside the
-            clip boundaries replaced.
+            clip boundaries replaced or None if ``inplace=True``.
 
         See Also
         --------
@@ -9064,7 +9064,7 @@ def where(
 
         Returns
         -------
-        Same type as caller
+        Same type as caller or None if ``inplace=True``.
 
         See Also
         --------

diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py
@@ -1319,8 +1319,8 @@ def set_names(self, names, level=None, inplace: bool = False):
 
         Returns
         -------
-        Index
-            The same type as the caller or None if inplace is True.
+        Index or None
+            The same type as the caller or None if ``inplace=True``.
 
         See Also
         --------
@@ -1395,8 +1395,8 @@ def rename(self, name, inplace=False):
 
         Returns
         -------
-        Index
-            The same type as the caller or None if inplace is True.
+        Index or None
+            The same type as the caller or None if ``inplace=True``.
 
         See Also
         --------

diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py
@@ -787,7 +787,8 @@ def set_levels(self, levels, level=None, inplace=None, verify_integrity=True):
 
         Returns
         -------
-        new index (of same type and class...etc)
+        new index (of same type and class...etc) or None
+            The same type as the caller or None if ``inplace=True``.
 
         Examples
         --------
@@ -966,7 +967,8 @@ def set_codes(self, codes, level=None, inplace=None, verify_integrity=True):
 
         Returns
         -------
-        new index (of same type and class...etc)
+        new index (of same type and class...etc) or None
+            The same type as the caller or None if ``inplace=True``.
 
         Examples
         --------

diff --git a/pandas/core/series.py b/pandas/core/series.py
@@ -1193,7 +1193,7 @@ def reset_index(self, level=None, drop=False, name=None, inplace=False):
 
         Returns
         -------
-        Series or DataFrame
+        Series or DataFrame or None
             When `drop` is False (the default), a DataFrame is returned.
             The newly created columns will come first in the DataFrame,
             followed by the original Series values.
@@ -1917,8 +1917,8 @@ def drop_duplicates(self, keep="first", inplace=False) -> Optional["Series"]:
 
         Returns
         -------
-        Series
-            Series with duplicates dropped.
+        Series or None
+            Series with duplicates dropped or None if ``inplace=True``.
 
         See Also
         --------
@@ -3137,8 +3137,8 @@ def sort_values(
 
         Returns
         -------
-        Series
-            Series ordered by values.
+        Series or None
+            Series ordered by values or None if ``inplace=True``.
 
         See Also
         --------
@@ -3383,8 +3383,8 @@ def sort_index(
 
         Returns
         -------
-        Series
-            The original Series sorted by the labels.
+        Series or None
+            The original Series sorted by the labels or None if ``inplace=True``.
 
         See Also
         --------
@@ -4312,8 +4312,8 @@ def rename(
 
         Returns
         -------
-        Series
-            Series with index labels or name altered.
+        Series or None
+            Series with index labels or name altered or None if ``inplace=True``.
 
         See Also
         --------
@@ -4426,8 +4426,8 @@ def drop(
 
         Returns
         -------
-        Series
-            Series with specified index labels removed.
+        Series or None
+            Series with specified index labels removed or None if ``inplace=True``.
 
         Raises
         ------
@@ -4815,8 +4815,8 @@ def dropna(self, axis=0, inplace=False, how=None):
 
         Returns
         -------
-        Series
-            Series with NA entries dropped from it.
+        Series or None
+            Series with NA entries dropped from it or None if ``inplace=True``.
 
         See Also
         --------