From 0f5e99f3f7c3bd2766a7e9a04b81e4eff5bedc81 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sat, 19 Jan 2019 18:18:25 -0600 Subject: [PATCH 01/12] DOC: Clean sort_values and sort_index docstrings --- pandas/core/generic.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a0ee9cb253fef..441b3a778460e 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3977,7 +3977,7 @@ def sort_values(self, by=None, axis=0, ascending=True, inplace=False, orders. If this is a list of bools, must match the length of the by. inplace : bool, default False - if True, perform operation in-place + If True, perform operation in-place kind : {'quicksort', 'mergesort', 'heapsort'}, default 'quicksort' Choice of sorting algorithm. See also ndarray.np.sort for more information. `mergesort` is the only stable algorithm. For @@ -4062,11 +4062,11 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, ---------- axis : %(axes)s to direct sorting level : int or level name or list of ints or list of level names - if not None, sort on values in specified index level(s) + If not None, sort on values in specified index level(s) ascending : boolean, default True Sort ascending vs. descending inplace : bool, default False - if True, perform operation in-place + If True, perform operation in-place kind : {'quicksort', 'mergesort', 'heapsort'}, default 'quicksort' Choice of sorting algorithm. See also ndarray.np.sort for more information. `mergesort` is the only stable algorithm. For @@ -4076,7 +4076,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, `first` puts NaNs at the beginning, `last` puts NaNs at the end. Not implemented for MultiIndex. sort_remaining : bool, default True - if true and sorting by level and index is multilevel, sort by other + If True and sorting by level and index is multilevel, sort by other levels too (in order) after sorting by specified level Returns From 73a911e19738b7807cd15debdde510ea68c3a63a Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Mon, 21 Jan 2019 18:49:43 -0600 Subject: [PATCH 02/12] Clean docstrings * Add periods * Realign descriptions --- pandas/core/generic.py | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 441b3a778460e..0742063aad8b9 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3966,25 +3966,25 @@ def add_suffix(self, suffix): def sort_values(self, by=None, axis=0, ascending=True, inplace=False, kind='quicksort', na_position='last'): """ - Sort by the values along either axis + Sort by the values along either axis. Parameters ----------%(optional_by)s axis : %(axes_single_arg)s, default 0 - Axis to be sorted + Axis to be sorted. ascending : bool or list of bool, default True Sort ascending vs. descending. Specify list for multiple sort orders. If this is a list of bools, must match the length of the by. inplace : bool, default False - If True, perform operation in-place + If True, perform operation in-place. kind : {'quicksort', 'mergesort', 'heapsort'}, default 'quicksort' Choice of sorting algorithm. See also ndarray.np.sort for more information. `mergesort` is the only stable algorithm. For DataFrames, this option is only applied when sorting on a single column or label. na_position : {'first', 'last'}, default 'last' - `first` puts NaNs at the beginning, `last` puts NaNs at the end + Puts NaNs at the beginning if `first`; `last` puts NaNs at the end. Returns ------- @@ -4056,28 +4056,28 @@ def sort_values(self, by=None, axis=0, ascending=True, inplace=False, def sort_index(self, axis=0, level=None, ascending=True, inplace=False, kind='quicksort', na_position='last', sort_remaining=True): """ - Sort object by labels (along an axis) + Sort object by labels (along an axis). Parameters ---------- axis : %(axes)s to direct sorting level : int or level name or list of ints or list of level names - If not None, sort on values in specified index level(s) + If not None, sort on values in specified index level(s). ascending : boolean, default True - Sort ascending vs. descending + Sort ascending vs. descending. inplace : bool, default False If True, perform operation in-place kind : {'quicksort', 'mergesort', 'heapsort'}, default 'quicksort' - Choice of sorting algorithm. See also ndarray.np.sort for more - information. `mergesort` is the only stable algorithm. For - DataFrames, this option is only applied when sorting on a single - column or label. + Choice of sorting algorithm. See also ndarray.np.sort for more + information. `mergesort` is the only stable algorithm. For + DataFrames, this option is only applied when sorting on a single + column or label. na_position : {'first', 'last'}, default 'last' - `first` puts NaNs at the beginning, `last` puts NaNs at the end. - Not implemented for MultiIndex. + Puts NaNs at the beginning if `first`; `last` puts NaNs at the end. + Not implemented for MultiIndex. sort_remaining : bool, default True If True and sorting by level and index is multilevel, sort by other - levels too (in order) after sorting by specified level + levels too (in order) after sorting by specified level. Returns ------- From b02d67271c5870954d8d964d5ed072a3070b70b1 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Mon, 21 Jan 2019 22:22:50 -0600 Subject: [PATCH 03/12] Fix PEP8 line length --- pandas/core/generic.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 0742063aad8b9..cb6200883d7c4 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3984,7 +3984,8 @@ def sort_values(self, by=None, axis=0, ascending=True, inplace=False, DataFrames, this option is only applied when sorting on a single column or label. na_position : {'first', 'last'}, default 'last' - Puts NaNs at the beginning if `first`; `last` puts NaNs at the end. + Puts NaNs at the beginning if `first`; `last` puts NaNs at the + end. Returns ------- From 794aae165408caeacf3bd9b629954b90122ceffa Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Wed, 23 Jan 2019 18:24:14 -0600 Subject: [PATCH 04/12] Capitalize True --- pandas/core/series.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 0c8e697c572e8..e3f3ffb60b179 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2857,7 +2857,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, If 'first' puts NaNs at the beginning, 'last' puts NaNs at the end. Not implemented for MultiIndex. sort_remaining : bool, default True - If true and sorting by level and index is multilevel, sort by other + If True and sorting by level and index is multilevel, sort by other levels too (in order) after sorting by specified level. Returns From 5063294e1694b404465515540351ebaa6f5de9f4 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Wed, 23 Jan 2019 19:19:26 -0600 Subject: [PATCH 05/12] Fix PEP8 in example --- pandas/core/generic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index cb6200883d7c4..e722113c7a55c 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3994,8 +3994,8 @@ def sort_values(self, by=None, axis=0, ascending=True, inplace=False, Examples -------- >>> df = pd.DataFrame({ - ... 'col1' : ['A', 'A', 'B', np.nan, 'D', 'C'], - ... 'col2' : [2, 1, 9, 8, 7, 4], + ... 'col1': ['A', 'A', 'B', np.nan, 'D', 'C'], + ... 'col2': [2, 1, 9, 8, 7, 4], ... 'col3': [0, 1, 9, 4, 2, 3], ... }) >>> df From 171acfdc9a0b35d1a00f3d3d0e2897bd2f3fd877 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Wed, 23 Jan 2019 19:20:35 -0600 Subject: [PATCH 06/12] Use bool not boolean --- 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 e722113c7a55c..836d5420d05f7 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4064,7 +4064,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, axis : %(axes)s to direct sorting level : int or level name or list of ints or list of level names If not None, sort on values in specified index level(s). - ascending : boolean, default True + ascending : bool, default True Sort ascending vs. descending. inplace : bool, default False If True, perform operation in-place From a2fbe010f690d14d19715f758e1a5b2229c12858 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Wed, 23 Jan 2019 19:32:45 -0600 Subject: [PATCH 07/12] Add periods to descriptions --- pandas/core/generic.py | 2 +- pandas/core/series.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 836d5420d05f7..8fb2e20fd78b2 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4067,7 +4067,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, ascending : bool, default True Sort ascending vs. descending. inplace : bool, default False - If True, perform operation in-place + If True, perform operation in-place. kind : {'quicksort', 'mergesort', 'heapsort'}, default 'quicksort' Choice of sorting algorithm. See also ndarray.np.sort for more information. `mergesort` is the only stable algorithm. For diff --git a/pandas/core/series.py b/pandas/core/series.py index e3f3ffb60b179..a25aa86a47927 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2863,7 +2863,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, Returns ------- pandas.Series - The original Series sorted by the labels + The original Series sorted by the labels. See Also -------- From 2f8c8aebbee821759d91885f9860ec04bfa5747c Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Wed, 23 Jan 2019 21:21:19 -0600 Subject: [PATCH 08/12] Fix docstring errors --- pandas/core/generic.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 8fb2e20fd78b2..399add3672277 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -530,7 +530,7 @@ def set_axis(self, labels, axis=0, inplace=None): The axis to update. The value 0 identifies the rows, and 1 identifies the columns. - inplace : boolean, default None + inplace : bool, default None Whether to return a new %(klass)s instance. .. warning:: @@ -3989,7 +3989,8 @@ def sort_values(self, by=None, axis=0, ascending=True, inplace=False, Returns ------- - sorted_obj : %(klass)s + sorted_obj : %(klass)s or None + An object of same type as caller if inplace=False, None otherwise. Examples -------- @@ -4061,7 +4062,9 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, Parameters ---------- - axis : %(axes)s to direct sorting + axis : {0 or 'index', 1 or 'columns'}, default 0 + The axis along which to sort. The value 0 identifies the rows, + and 1 identifies the columns. level : int or level name or list of ints or list of level names If not None, sort on values in specified index level(s). ascending : bool, default True @@ -4082,7 +4085,8 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, Returns ------- - sorted_obj : %(klass)s + sorted_obj : %(klass)s or None + An object of same type as caller if inplace=False, None otherwise. """ inplace = validate_bool_kwarg(inplace, 'inplace') axis = self._get_axis_number(axis) From 612311e410ca0b6f04a110ee7dae8dd4d00bbd8e Mon Sep 17 00:00:00 2001 From: William Ayd Date: Thu, 24 Jan 2019 19:41:44 -0600 Subject: [PATCH 09/12] Update pandas/core/generic.py Co-Authored-By: dsaxton --- 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 399add3672277..304f32864ab78 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4086,7 +4086,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, Returns ------- sorted_obj : %(klass)s or None - An object of same type as caller if inplace=False, None otherwise. + DataFrame with sorted values. """ inplace = validate_bool_kwarg(inplace, 'inplace') axis = self._get_axis_number(axis) From cc5893394a1a4e3774d58558251b128ede062661 Mon Sep 17 00:00:00 2001 From: William Ayd Date: Thu, 24 Jan 2019 19:41:52 -0600 Subject: [PATCH 10/12] Update pandas/core/generic.py Co-Authored-By: dsaxton --- 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 304f32864ab78..75b2b37332424 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4085,7 +4085,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, Returns ------- - sorted_obj : %(klass)s or None + sorted_obj : DataFrame DataFrame with sorted values. """ inplace = validate_bool_kwarg(inplace, 'inplace') From 6a40a223242d0630d654447c0df67922554cf017 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 24 Jan 2019 20:07:21 -0600 Subject: [PATCH 11/12] Edit sort_index returns section --- pandas/core/generic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 75b2b37332424..8da07a8de2285 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4085,8 +4085,8 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, Returns ------- - sorted_obj : DataFrame - DataFrame with sorted values. + sorted_obj : DataFrame or None + DataFrame with sorted index if inplace=False, None otherwise. """ inplace = validate_bool_kwarg(inplace, 'inplace') axis = self._get_axis_number(axis) From 75750da2a0e1bb24058cc8539f7a41fec6970fce Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Fri, 25 Jan 2019 18:58:33 -0600 Subject: [PATCH 12/12] Update sort_values docstring --- pandas/core/generic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 8da07a8de2285..63d16f7bcb78d 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3989,8 +3989,8 @@ def sort_values(self, by=None, axis=0, ascending=True, inplace=False, Returns ------- - sorted_obj : %(klass)s or None - An object of same type as caller if inplace=False, None otherwise. + sorted_obj : DataFrame or None + DataFrame with sorted values if inplace=False, None otherwise. Examples --------