From 22b1ef6392fc23e05f5b36edef653dc220a69260 Mon Sep 17 00:00:00 2001 From: Jun Kudo Date: Sun, 4 Oct 2020 16:47:31 +0000 Subject: [PATCH 1/6] DOC: make return type documentation of series methods consistent #35409 --- pandas/core/arrays/categorical.py | 23 +++++++++++++---------- pandas/core/generic.py | 20 ++++++++++---------- pandas/core/series.py | 26 +++++++++++++------------- 3 files changed, 36 insertions(+), 33 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 1a8861af10ed1..04913599ac773 100644 --- 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 : Categprocal 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/generic.py b/pandas/core/generic.py index 04e1fc91c5fd4..c4d04acf214b0 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -649,7 +649,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 -------- @@ -1096,7 +1096,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 -------- @@ -6461,8 +6461,8 @@ def replace( Returns ------- - {klass} - Object after replacement. + {klass} or None + Object after replacement or None if ``inplace=True``. Raises ------ @@ -6896,9 +6896,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 See Also -------- @@ -7494,9 +7494,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 -------- @@ -9048,9 +9048,9 @@ def where( try_cast : bool, default False Try to cast the result back to the input type (if possible). - Returns + Returns or None ------- - Same type as caller + Same type as caller or None if ``inplace=True``. See Also -------- diff --git a/pandas/core/series.py b/pandas/core/series.py index 2b972d33d7cdd..3c4fe4a4fe547 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1192,7 +1192,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. @@ -1911,8 +1911,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 -------- @@ -3129,8 +3129,8 @@ def sort_values( Returns ------- - Series - Series ordered by values. + Series or None + Series ordered by values or None if ``inplace=True``. See Also -------- @@ -3375,8 +3375,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 -------- @@ -4304,8 +4304,8 @@ def rename( Returns ------- - Series - Series with index labels or name altered. + Series or None + Series with index labels or name altered See Also -------- @@ -4418,8 +4418,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 ------ @@ -4807,8 +4807,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 -------- From fe486cc9251dbf2864b0c2de4e244bb568431e78 Mon Sep 17 00:00:00 2001 From: Jun Kudo Date: Sun, 4 Oct 2020 17:00:20 +0000 Subject: [PATCH 2/6] DOC: remove unnecessary addition --- pandas/core/generic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index c4d04acf214b0..ef98a101d137a 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -9048,7 +9048,7 @@ def where( try_cast : bool, default False Try to cast the result back to the input type (if possible). - Returns or None + Returns ------- Same type as caller or None if ``inplace=True``. From 148fb6a78ecf46d894ab06fd0f8b5c81cbb6ce92 Mon Sep 17 00:00:00 2001 From: Jun Kudo Date: Sun, 4 Oct 2020 17:32:47 +0000 Subject: [PATCH 3/6] DOC: fix typo of addition --- pandas/core/arrays/categorical.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 04913599ac773..8dc5e6c0ff2aa 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -916,7 +916,7 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False): Returns ------- - cat : Categprocal or None + cat : Categorical or None Categorical with removed categories or None if ``inplace=True``. Raises From e9f32e2249b4c666a7a037ef5902c1f6f5d79feb Mon Sep 17 00:00:00 2001 From: Jun Kudo Date: Sun, 4 Oct 2020 18:05:43 +0000 Subject: [PATCH 4/6] DOC: fix the missing documentation of series methods & missing dots --- pandas/core/generic.py | 4 ++-- pandas/core/series.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index ef98a101d137a..93ba035b58376 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4326,7 +4326,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 -------- @@ -6898,7 +6898,7 @@ def interpolate( ------- 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 -------- diff --git a/pandas/core/series.py b/pandas/core/series.py index 3c4fe4a4fe547..41d88ba4c705c 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -4305,7 +4305,7 @@ def rename( Returns ------- Series or None - Series with index labels or name altered + Series with index labels or name altered or None if ``inplace=True``. See Also -------- From 16214330e71d1f4a2b58af8776a780c8c2d7254f Mon Sep 17 00:00:00 2001 From: Jun Kudo Date: Sun, 4 Oct 2020 18:35:18 +0000 Subject: [PATCH 5/6] DOC: make the return type documentation of frame methods consistent --- pandas/core/frame.py | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 1f9987d9d3f5b..8cddad2df0746 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -3251,8 +3251,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 -------- @@ -3399,8 +3400,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 -------- @@ -4117,8 +4118,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 ------ @@ -4272,8 +4274,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 ------ @@ -4501,8 +4503,8 @@ def set_index( Returns ------- - DataFrame - Changed row labels. + DataFrame or None + Changed row labels or None if ``inplace=True``. See Also -------- @@ -4964,8 +4966,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 -------- @@ -5100,7 +5102,7 @@ def drop_duplicates( Returns ------- - DataFrame + DataFrame or None DataFrame with duplicates removed or None if ``inplace=True``. See Also @@ -5423,8 +5425,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 -------- From 3618783f783f8f4563237be9bfb1d88cbc09daf0 Mon Sep 17 00:00:00 2001 From: Jun Kudo Date: Sun, 4 Oct 2020 18:40:26 +0000 Subject: [PATCH 6/6] DOC: make the return type documentation of rest consistent --- pandas/core/computation/eval.py | 3 ++- pandas/core/indexes/base.py | 8 ++++---- pandas/core/indexes/multi.py | 6 ++++-- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/pandas/core/computation/eval.py b/pandas/core/computation/eval.py index 913f135b449f3..b77204861f0a4 100644 --- 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/indexes/base.py b/pandas/core/indexes/base.py index ff3d8bf05f9a5..84c33f9d0ea4a 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -1345,8 +1345,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 -------- @@ -1421,8 +1421,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 index a157fdfdde447..c81175c577cc4 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -782,7 +782,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 -------- @@ -961,7 +962,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 --------